💡 Tam çalışan örnek GitHub’da mevcuttur:
ml-dsa-sertifikalari-ile-docx-imzala-python

Giriş

Bu öğleden sonra bir sözleşmeyi RSA-2048 ile imzalarsınız ve sözleşmenin geçerli olduğu sürece geçerli olması gereken bir vaat yapmış olursunuz. Bu, yirmi ya da otuz yıl olabilir – ve tapular, onay formları ve mühendislik onayları için genellikle öyledir – vaat algoritmanın ömründen daha uzun sürmelidir. Saldırı bugünkü var olmak zorunda değildir. Belgenin önemi kaybolmadan önce var olması yeterlidir; o zaman herkese açık anahtarı tutan herkes özel anahtarı türetebilir ve sizin adınıza imzalayabilir.

Post-kuantum belge imzalama, Python için GroupDocs.Signature özelliğidir ve bu vaat yerine 2024’te FIPS 204 olarak NIST tarafından standartlaştırılan ML-DSA imza algoritmasını kullanır. Word formatı desteği GroupDocs.Signature 26.9’da geldi ve zaten sahip olduğunuz API’yi yeniden kullanır: bir ML-DSA anahtarı bir PFX içinde bulunur ve DigitalSignOptions içine RSA anahtarı gibi konur.

Bu kılavuz bir DOCX’i dört adımda imzalar, üç güvenlik seviyesini ölçülen çıktıya göre karşılaştırır, sadece bir açık sertifika ile imzayı doğrular ve taahhüt etmeden önce bilmeniz gereken iki sınırlama ile sona erer.

Neden Bu, Alışılmış Göçten Daha Önemli

İmza göçü, bir yönüyle şifreleme göçünden farklıdır ve bu da ertelemeyi kolaylaştırıp düzeltmeyi daha zor hâle getirir.

Şifreleme ile, “şimdi topla‑daha sonra çöz” sorunu anındadır: bugün yakalanan her şey depolanıp daha sonra açılabilir. İmzalarla, zaten imzaladığınız hiçbir şey geriye dönük olarak sahte yapılamaz – ancak bir kez anahtar, herkesin bir kopyasına sahip olduğu sertifikadan türetilebildiğinde, imzaladığınız hiçbir şey de kanıtlanabilir olmaz. On yıl boyunca arşivlenmiş belgeleri yeni anahtarlarla yeniden imzalamak mümkündür ve kimse bunu planlamak istemez.

Bu yüzden pratik tavsiye geniş kapsamlı değil, dar kapsamlıdır: saklama süresi uzun olan belgeleri göç ettirin, geri kalanını bırakın. Bazı profiller zaten çıtayı koymuştur – CNSA 2.0 ulusal güvenlik sistemleri için ML-DSA-87 gerektirir – ve diğerleri için belirleyici faktör, dosyanın ne kadar süre savunulabilir kalması gerektiğidir.

Önkoşullar

  • 64‑bit yorumlayıcıda Python 3.9 veya üzeri – paket bir .NET çalışma zamanı içerir ve 32‑bit tekerlek (wheel) sunmaz
  • .NET 26.10.0 üzerinden Python için GroupDocs.Signature, ücretsiz geçici lisans ile değerlendirme sınırlamaları kaldırılmış
  • Parola korumalı bir PFX olarak ML-DSA sertifikası ve imzalanacak bir Word belgesi

Kurulum

pip install groupdocs-signature-net

Adım 1 – ML-DSA sertifikasıyla imzala

Sertifika işi yapar. Çağrı, RSA için yazacağınız şeyle aynıdır:

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

    result = sign.sign(output_path, options)

Bu, zaten imzalayan kod için tam benimseme hikayesidir: DigitalSignOptions‘ı farklı bir PFX’e yönlendirin. Yeni bir seçenek, ayrı bir algoritma parametresi ya da post‑kuantum için ayrı bir dal yok.

İmzayı geri okumak bir adım daha gerektirir ve tüm alıştırmadaki tek Python‑özel tuzak burada bulunur:

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

DigitalSignature üzerindeki sertifika, nitelikleri dinamik olarak çözen bir köprü nesnedir. certificate.subject CN=GroupDocs.Signature MLDSA65 test döndürürken, aynı nesne üzerinde dir() hiçbir şey listelemez. İlk önce dir() ile inceledim, konunun ortaya çıkmadığını düşündüm ve yanıldım – bu yüzden okumadan önce içeriği sorgularsanız, mevcut bir değeri atlayabilirsiniz.

Adım 2 – Üç güvenlik seviyesini karşılaştır

ML-DSA üç parametre setiyle gelir ve farklı bir sertifika vererek seçilirler:

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)

Bu, gerçekten çalıştırmaya değer adımdır; çünkü takas genellikle tarif edilir ama nadiren ölçülür. 132 KB kaynak sözleşmeden:

Seviye NIST güvenlik kategorisi İmzalı dosya En küçüğe göre
ML-DSA-44 2 138.202 bayt -
ML-DSA-65 3 140.650 bayt +2.448 bayt
ML-DSA-87 5 143.971 bayt +5.769 bayt

En zayıf seviyeyi en güçlüden 6 KB ayırır. Bir sözleşme için bu önemsizdir ve karar şu şekilde çökertilir: varsayılan olarak ML-DSA-65 kullanın, bir profil kategori 5 talep ediyorsa ya da boyut önemsizse ML-DSA-87, ve yalnızca çok sayıda dosyayı imzalıyorsanız ve kilobaytlar gerçek bir birikime dönüşüyorsa ML-DSA-44.

Adım 3 – Açık sertifika ile doğrula

Alıcı, imzalayanın açık sertifikasına ve gizli bir şeye ihtiyaç duymaz:

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

Örnek aynı dosyada iki kez çağırır: bir kez mldsa65.cer (imza anahtarının açık yarısı) ile, bir kez farklı bir imzalayanın PFX’i ile. İlki True, ikincisi False döndürür. Yanlış sertifikanın False döndürdüğüne dikkat edin; bir istisna fırlatmaz – “başka biri tarafından imzalanmış” kodunuzun ele alması gereken bir yanıttır, bir hata değil. Kontrol, belge içeriğini, sertifikanın seri numarası ve parmak izini de kapsar; bu yüzden imzalandıktan sonra düzenlenen bir dosya da başarısız olur.

Adım 4 – Belgedeki imzaları oku

İmzalı bir belge geldiğinde ve hangi sertifikayı bekleyeceğinizi bilmiyorsanız:

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

SignatureType.DIGITAL ile search DigitalSignature nesnelerini döndürür; bu nesneler sertifika, imzalama zamanı ve geçerlilik bayrağını taşır. Bir Word belgesi birden fazla imza içerebilir; RSA ve ML-DSA karışımı dahil, ve her biri kendi sertifikası ve geçerliliği ile raporlanır.

Bu, alıcıların doğrulama şeklini değiştirir mi?

Hiçbir şekilde fark etmeyecekleri bir değişiklik yoktur. Alıcı hâlâ sadece imzalayanın açık sertifikasına ihtiyaç duyar, aynı DigitalVerifyOptions nesnesine verir ve bir boolean döner. Doğrulama yolunda ML-DSA’ya özgü bir şey yoktur. Algoritmanın göründüğü tek yer, Microsoft Word’ün kendi imza göstergesi olup, formatın standart bir tanımlayıcısı olmadığı için ML-DSA’yı henüz tanımayabilir.

Gerçek Dünya Uygulamaları

Uzun saklama süresi gerektiren sözleşmeler

En net örnek. On yıllarca doğrulanabilir kalması gereken bir belge, şimdi bir kez ML-DSA-65 ya da ML-DSA-87 ile imzalanır ve algoritması eskidiği için yeniden imzalanmasına gerek kalmaz.

Belirli bir profil ile düzenlenmiş ortamlar

CNSA 2.0 ya da benzeri bir profil uygulandığında seviye bir yargı meselesi değildir – ML-DSA-87 zorunludur ve tek mühendislik sorusu formatın desteklenip desteklenmediğidir.

Göç sırasında karışık hatlar

Arşivi dokunmadan yeni belgeleri post‑kuantum ile imzalamak tamamen makul bir ara durumdur ve search her imzayı ayrı ayrı raporladığı için yönetilebilir.

En İyi Uygulamalar ve İpuçları

  • Saklama süresine göre göç edin, hacme göre değil. Bu ihtiyacı olan belgeler uzun ömürlü olanlardır; 90 gün için önemli bir makbuz buna girmez.
  • Varsayılan olarak ML-DSA-65 kullanın, bir profil bir seviye belirtmedikçe; ve boyut farkı üzerinde endişelenmeyin – imza başına 6 KB’nın altında.
  • RSA’yı, alıcı Word’de doğrulama yapıyorsa tutun. Bir okuyucunun işaretlediği hatalı imzalar, daha yavaş bir göçten daha kötüdür.
  • Test sertifikalarını değiştirin. Örnekteki PFX dosyaları yayınlanmış bir parola ile kendi kendine imzalanmıştır; bunlarla imzalanan hiçbir şey bir şey kanıtlamaz.
  • İmzalamadan sonra doğrulayın; alıcının sahip olacağı açık sertifikayı kullanarak herhangi bir hat hattında.

Yaygın Sorunların Çözümü

Microsoft Word imzayı geçerli olarak göstermiyor. Şu an için beklenen bir durum: ML-DSA için standart bir XML‑DSig tanımlayıcısı yoktur, bu yüzden Word imzayı doğru olsa bile tanımayabilir ve GroupDocs.Signature doğrulasa bile. Kendi hattınızda doğrulayın ve alıcıların Word göstergesine güvendiği belgeler için RSA’yı tutun.

İmza çağrısı bir PDF ya da elektronik tabloyu reddediyor. ML-DSA imzalama Word formatlarını kapsar – DOCX, DOC, ODT ve diğerleri. PDF, elektronik tablolar ve sunumlar henüz desteklenmez; bunlar hâlâ RSA ya da ECDSA ile imzalanır.

Sertifika konusu boş dönüyor. Neredeyse her zaman Adım 1’deki dir() tuzağıdır: nitelik dinamik olarak çözülür, bu yüzden önce test etmek yerine okuyun.

Sonuç

Kod değişikliği bir sertifika değişikliğidir; bu da acil olmadan önce yapmayı değer kılan bölümdür. Uzun ömürlü Word belgelerini ML-DSA-65 ile imzalayın, bir profil gerektiriyorsa ML-DSA-87 kullanın, açık sertifika ile doğrulayın ve format ya da okuyucu gerektiriyorsa RSA’yı tutun.

Örneği kendi sözleşmelerinizden biriyle çalıştırın; üç boyut size bayt cinsinden en güçlü seviyenin ne kadar maliyet getirdiğini söyleyecektir. Test ettiğim dosyada bu 5.769 bayttı.

Ek Kaynaklar