💡 Plně funkční příklad dostupný na GitHubu:
sign-docx-with-mldsa-certificates-python

Úvod

Podepište smlouvu dnes odpoledne pomocí RSA‑2048 a učiníte slib, který musí platit tak dlouho, dokud je smlouva relevantní. Pokud je to dvacet nebo třicet let – a u listin, souhlasných formulářů a technických schválení to často bývá – slib musí přežít algoritmus. Útok nemusí existovat dnes. Musí existovat dříve, než dokument přestane mít význam, a pak kdokoli, kdo má veřejný klíč, může odvodit soukromý a podepsat vaším jménem.

Post‑kvantové podepisování dokumentů je funkce GroupDocs.Signature pro Python, která nahrazuje tento slib algoritmem ML‑DSA, podpisovým algoritmem standardizovaným NIST jako FIPS 204 v roce 2024. Podpora formátu Word přišla ve GroupDocs.Signature 26.9 a znovu využívá API, které již máte: klíč ML‑DSA žije v PFX a předává se do DigitalSignOptions přesně jako RSA klíč.

Tento návod podepisuje DOCX ve čtyřech krocích, porovnává tři úrovně zabezpečení na měřeném výstupu, ověřuje podpis pouze pomocí veřejného certifikátu a končí dvěma omezeními, která je dobré znát před nasazením.

Proč je to důležitější než běžná migrace

Migrace podpisů se liší od migrace šifrování v jednom ohledu, který usnadňuje odkládání a ztěžuje opravu.

U šifrování je problém „sklízet‑te‑nyní‑dešifrujte‑později“ okamžitý: vše zachycené dnes může být uloženo a otevřeno později. U podpisů se nic, co jste již podepsali, nestane zpětně padělatelným – ale nic, co jste podepsali, také nezůstane prokazatelně vaše, jakmile lze klíč odvodit z certifikátu, který má každý kopii. Přepodpisování desetiletí archivovaných dokumentů novými klíči je možné a nikdo nechce být tím, kdo to plánuje.

Proto je praktické doporučení úzké, nikoli obecné: migrujte dokumenty s dlouhou dobou archivace, ostatní nechte. Některé profily už stanovily laťku – CNSA 2.0 vyžaduje ML‑DSA‑87 pro systémy národní bezpečnosti – a pro všechny ostatní je rozhodujícím faktorem, jak dlouho má být soubor obhajitelný.

Předpoklady

  • Python 3.9 nebo novější na 64‑bitovém interpretru – balíček obsahuje zabalený .NET runtime a nemá 32‑bitové kolo
  • GroupDocs.Signature pro Python přes .NET 26.10.0, s bezplatnou dočasnou licencí pro odstranění evaluačních omezení
  • Certifikát ML‑DSA jako chráněný PFX a Word dokument, který chcete podepsat

Instalace

pip install groupdocs-signature-net

Krok 1 – Podepsání certifikátem ML‑DSA

Certifikát vykoná práci. Volání je stejné jako u RSA:

with signature.Signature(source_path) as sign:
    options = DigitalSignOptions(pfx_path)
    options.password = CERTIFICATE_PASSWORD

    result = sign.sign(output_path, options)

To je celý příběh adopce pro kód, který už podepisuje: nasměrujte DigitalSignOptions na jiný PFX. Žádná nová volba, žádný samostatný parametr algoritmu, žádná větev pro post‑kvantové.

Načtení podpisu zpět vyžaduje ještě jeden krok a obsahuje jedinou Python‑specifickou past v celém cvičení:

for created in result.succeeded:
    certificate = getattr(created, "certificate", None)
    subject = getattr(certificate, "subject", None)
    if subject:
        return str(subject)

Certifikát na DigitalSignature je mostní objekt, který dynamicky řeší atributy. certificate.subject vrací CN=GroupDocs.Signature MLDSA65 test, zatímco dir() na stejném objektu nic neukáže. Nejprve jsem to zkoušel s dir(), usoudil, že předmět není vystaven, a byl jsem prostě špatně – takže pokud introspektujete před čtením, přeskočíte hodnotu, která tam je.

Krok 2 – Porovnání tří úrovní zabezpečení

ML‑DSA existuje ve třech sadách parametrů a vybírá se předáním jiného certifikátu:

levels = (
    ("ML-DSA-44", MLDSA44_PFX),
    ("ML-DSA-65", MLDSA65_PFX),
    ("ML-DSA-87", MLDSA87_PFX),
)

for level, pfx_path in levels:
    with signature.Signature(source_path) as sign:
        options = DigitalSignOptions(pfx_path)
        options.password = CERTIFICATE_PASSWORD
        sign.sign(output_path, options)

    sizes[f"{level} -> {file_name}"] = os.path.getsize(output_path)

Toto je krok, který stojí za to skutečně spustit, protože kompromis je obvykle popisován a zřídka měřen. Z 132 KB zdrojové smlouvy:

Úroveň Kategorie bezpečnosti NIST Podepsaný soubor Nad nejmenším
ML-DSA-44 2 138 202 bajtů -
ML-DSA-65 3 140 650 bajtů +2 448 bajtů
ML-DSA-87 5 143 971 bajtů +5 769 bajtů

Méně než 6 KB odděluje nejslabší úroveň od nejsilnější. U smlouvy to není nic, což zjednodušuje rozhodnutí: použijte ML‑DSA‑65 jako výchozí, ML‑DSA‑87 tam, kde profil vyžaduje kategorii 5 nebo kde velikost není podstatná, a ML‑DSA‑44 jen když podepisujete tolik souborů, že kilobajty se sčítají do něčeho reálného.

Krok 3 – Ověření pomocí veřejného certifikátu

Příjemce potřebuje veřejný certifikát podepisujícího a nic tajného:

with signature.Signature(signed_path) as sign:
    options = DigitalVerifyOptions(certificate_path)
    if password is not None:
        options.password = password

    return sign.verify(options).is_valid

Ukázka volá tuto funkci dvakrát na stejném souboru: jednou s mldsa65.cer, veřejnou polovinou podpisového klíče, a podruhé s jiným PFX podepisujícího. První vrátí True, druhý False. Všimněte si, že špatný certifikát dává False místo výjimky – „podepsáno někým jiným“ je odpověď, kterou by váš kód měl zvládnout, ne výjimku. Kontrola zahrnuje obsah dokumentu spolu se sériovým číslem a otiskem certifikátu, takže soubor upravený po podpisu také selže.

Krok 4 – Načtení podpisů z dokumentu

Když dorazí podepsaný dokument a nevíte, který certifikát očekávat:

with signature.Signature(signed_path) as sign:
    found = sign.search(SignatureType.DIGITAL)
    for item in found:
        print(item.sign_time, item.is_valid)

search s SignatureType.DIGITAL vrací objekty DigitalSignature, které nesou certifikát, čas podpisu a příznak platnosti. Word dokument může obsahovat několik podpisů, včetně kombinace RSA a ML‑DSA, a každý je hlášen se svým certifikátem a vlastní platností.

Mění to způsob, jakým příjemci ověřují?

V žádném ohledu, který by si všimli. Příjemce stále potřebuje jen veřejný certifikát podepisujícího, předá ho stejným DigitalVerifyOptions a získá zpět boolean. Nic na ověřovací cestě není specifické pro ML‑DSA. Jediné místo, kde se algoritmus projeví, je indikátor podpisu v Microsoft Word, který ML‑DSA možná ještě nepozná, protože formát nemá standardní identifikátor.

Praktické aplikace

Dlouhodobé smlouvy

Nejjasnější případ. Dokument, který má být ověřitelný po desetiletí, se podepíše jednou, nyní, pomocí ML‑DSA‑65 nebo ML‑DSA‑87, a už nikdy není potřeba přepodpisovat, protože algoritmus nevyprší.

Regulované prostředí s pojmenovaným profilem

Kde se uplatňuje CNSA 2.0 nebo podobný profil, úroveň není otázkou úsudku – ML‑DSA‑87 je požadavek a jediná technická otázka je, zda je formát podporován.

Smíšené pipeline během migrace

Podepisování nových dokumentů post‑kvantově při zachování archivu beze změny je naprosto rozumný mezistav a search, který hlásí každý podpis zvlášť, umožňuje to řídit.

Nejlepší postupy a tipy

  • Migrujte podle doby archivace, ne podle objemu. Dokumenty, které to potřebují, jsou dlouhodobé; účtenka, která má smysl jen 90 dnů, ne.
  • Výchozí volba ML‑DSA‑65, pokud profil neurčuje úroveň, a nepropadejte velikostnímu rozdílu – je to méně než 6 KB na podpis.
  • Zachovejte RSA tam, kde příjemce ověřuje ve Wordu. Správné podpisy, které čtečnice označí jako chybu, jsou horší než pomalejší migrace.
  • Vyměňte testovací certifikáty. PFX soubory ve vzoru jsou samopodepsané s publikovaným heslem, takže cokoliv s nimi podepsané nic neprokazuje.
  • Ověřujte po podpisu v každé pipeline pomocí veřejného certifikátu, který by měl mít příjemce.

Řešení běžných problémů

Microsoft Word nezobrazuje podpis jako platný. Očekávané zatím: neexistuje standardní XML‑DSig identifikátor pro ML‑DSA, takže Word jej nemusí rozpoznat, i když je podpis správný a GroupDocs.Signature jej ověří. Ověřte ve své pipeline a zachovejte RSA pro dokumenty, jejichž příjemci spoléhají na indikátor Wordu.

Volání podpisu odmítá PDF nebo tabulku. Podepisování ML‑DSA pokrývá formáty Word – DOCX, DOC, ODT a další. PDF, tabulky a prezentace zatím nejsou podporovány a stále se podepisují RSA nebo ECDSA jako dříve.

Předmět certifikátu vrací prázdný řetězec. Téměř vždy past dir() z Kroku 1: atribut se řeší dynamicky, takže jej čtěte místo předchozího testování.

Závěr

Změna kódu je změna certifikátu, což je část, která dává smysl provést dříve, než se stane urgentní. Podepište dlouhodobé Word dokumenty pomocí ML‑DSA‑65, použijte ML‑DSA‑87 tam, kde to profil vyžaduje, ověřujte veřejným certifikátem a zachovejte RSA tam, kde formát nebo čtečka vyžadují.

Spusťte vzor proti jedné ze svých vlastních smluv a tři velikosti vám řeknou v bajtech, kolik vás stojí nejsilnější dostupná úroveň. Na souboru, který jsem testoval, to bylo 5 769 bajtů.

Další zdroje