💡 Tam çalışan örnek GitHub’da mevcuttur: vault-transit-pdf-signing-python

Neden Otomatik İmzalama, Anahtar Saklama İncelemesinde Başarısız Olur

Uyum ve finans operasyon ekipleri belgeleri binlerce kez imzalar: kredi sözleşmeleri, beyanlar, politika paketleri, denetim mektupları. Bunların neredeyse hiçbiri bir kişinin bir düğmeye tıklamasıyla imzalanmaz. Bir hizmet bunu bir zaman çizelgesine göre yapar ve bu belgelerle ilişkilendirilen sertifika kuruluşun adını taşır. Bu da imzalama anahtarını şirketin sahip olduğu en hassas şeylerden biri yapar ve genellikle onu kullanan uygulamanın yanındaki bir PFX dosyasında bulunur.

Harici imzalama, .NET üzerinden Python için bir GroupDocs.Signature yeteneğidir ve belge özetini, uygulamanın tuttuğu özel anahtarla imzalamak yerine sizin sağladığınız koda gönderir. Bu, PFX düzenlemesinin denetimden geçememesi nedeniyle vardır. Bir dosya bir kopyadır ve kopyalar yayılır: konteyner imajına, dağıtım hattına, yedeklemeye, geçen baharda bir üretim sorununu ayıklayan geliştiricinin dizüstü bilgisayarına. Bu kopyalardan birine ve parolaya sahip olan herkes, birisi fark edip sertifikayı iptal edene kadar adınıza imza atabilir.

Bu ekiplerin ihtiyacı farklı bir dosya formatı değil. Anahtarın tam olarak bir yerde bulunmasını, her kullanımının bir denetim izine sahip olmasını ve anahtara hiç güvenmeden bir imza talep edebilen bir imzalama hizmeti olmasını isterler. Bu, HashiCorp Vault gibi bir anahtar yöneticisinin görevidir ve yalnızca belge kütüphanesi kriptografiyi devretmeye izin verirse işe yarar.

Neden Şifreli Sertifika Dosyası Yeterli Değildir

İçgüdü, PFX’yi kilitlemektir: dosya izinlerini kısıtlamak, parolayı bir gizli yöneticiye koymak, birimi şifrelemek. Her adım yardımcı olur ve hiçbiri temel gerçeği değiştirmez. İmzalama anında, özel anahtar işleme yüklenir, bu yüzden bir bellek dökümü, bir konteyner kaçışı ya da dikkatsiz bir günlük ifadesi hâlâ onu ortaya çıkarabilir. İstediğiniz kontrol, okunamayan bir anahtar, okunması zor bir anahtar değil.

Vault’un Transit motoru bunu sağlar. Kriptografiyi bir hizmet olarak gerçekleştirir: bir değer gönderirsiniz, anahtarını tuttuğu bir anahtarla imzalar veya şifreler ve sonucu döndürür. İçinde oluşturulan anahtarlar dışa aktarılabilir olarak işaretlenemez ve aldığı veriyi asla depolamaz. GroupDocs.Signature diğer yarıyı kapsar, çünkü DigitalSignOptions.custom_sign_hash PDF imzalama hattına kendi imzalayıcınızı takmanıza izin verir.

Kurulum: Python için GroupDocs.Signature ve Vault Transit

GroupDocs.Signature her şeyi kriptografiye kadar yapar. PDF’i açar, imzanın kapsadığı bayt aralığını belirler, o aralığı özetler ve özetle sizin imzalayıcınıza çağrı yapar. İmzalaçınız özeti Vault’a gönderir ve Vault’un ürettiği baytları geri alır. Kütüphane bunları sertifika ile birlikte gömer ve normal bir imzalı PDF yazar.

Python 3.11 veya 3.13, groupdocs-signature-net ve asn1crypto paketleri ve bir geliştirme‑modu Vault konteyneri gerekir. GroupDocs lisansı isteğe bağlıdır; lisans olmadan değerlendirme modu en fazla 2 sayfalık belgeleri kabul eder. Örnek depo iki komutla uçtan uca çalışır ve aynı kod iki ortam değişkeni değiştirilerek bir üretim Vault’una yönlendirilir.

Adım Adım Oluşturma

Adım 1 - İmzalama anahtarını Vault’tan oku

Uygulama, kullanmasına izin verilen anahtarı Vault’tan ister ve bir sürüm numarası ile bir genel anahtar alır. Özel yarı asla yanıtın bir parçası değildir.

key = vault.read_key(KEY_NAME)
if key is None:
    # First run: enable Transit and create an RSA-2048 key.
    vault.enable_transit()
    vault.create_key(KEY_NAME, "rsa-2048")
    key = vault.read_key(KEY_NAME)
print(f"Signing key: '{KEY_NAME}', version {key.version}")

Sürümü bir kez okumak bu adımın amacıdır. Bir sertifika tek bir genel anahtar tutar, bu yüzden sertifika ve her imza aynı sürümden gelmelidir.

Adım 2 - Kimse dışa aktaramaz bir anahtar için sertifika oluştur

Bir PDF imzası, doğrulayıcının genel anahtarı bulabilmesi için bir X.509 sertifikası taşır. Dışa aktarılamaz bir anahtarla, sertifika genel yarının etrafında oluşturulur ve Vault tarafından imzalanır.

tbs_certificate = x509.TbsCertificate({...})   # built around the Vault public key

# Hash locally, then have Vault sign the certificate's own digest.
digest = hashlib.sha256(tbs_certificate.dump()).digest()
signature = vault.sign_hash(key_name, key.version, digest, "sha2-256")

certificate = x509.Certificate({
    "tbs_certificate": tbs_certificate,
    "signature_algorithm": algorithm,
    "signature_value": signature,
})

Sertifika kasıtlı olarak bugünden bir gün önce başlar. Bir PDF okuyucu imzalama zamanını bu başlangıç tarihiyle karşılaştırır ve UTC’den iki saat doğuya bir makinede, imzalamadan saniyeler önce oluşturulmuş bir sertifika Adobe Acrobat tarafından süresi dolmuş ya da henüz geçerli değil olarak raporlanır.

Adım 3 - Harici imzalayıcıyla PDF’i imzala

certificate_object = DigitalVerifyOptions(
    certificate_stream=io.BytesIO(certificate)).certificate
digital_signature = DigitalSignature(certificate=certificate_object)
digital_signature.sign_time = datetime.now().astimezone()

options = DigitalSignOptions()
options.signature = digital_signature
options.custom_sign_hash = VaultSigner(vault, KEY_NAME, key.version)
options.hash_algorithm = HashAlgorithm.SHA256
options.reason = "Document signed with HashiCorp Vault Transit"

with gs.Signature(str(input_pdf)) as signature:
    signature.sign(str(output_pdf), options)

İki satır Python’a özeldir. Bağlayıcıda X.509 türü yoktur, bu yüzden sertifika nesnesi DigitalVerifyOptions‘tan dışarı çıkar; DigitalSignOptions‘a bir yol verilirse “Specified certificate doesn’t contain private key” hatası alınır. Ve sign_time kasıtlı olarak saat dilimi farkı içerir, çünkü bir ofsetli değer PDF’e onunla birlikte yazılır.

İmzalcının içinde, özet prehashed = true ve pkcs1v15 ile Vault’a gönderilir. Bu iki alan imzanın geçerli olup olmadığını belirler ve birincisi eksik olduğunda sessizce başarısız olur.

Adım 4 - Hizmetten bir şey çıkmadan önce doğrula

options = DigitalVerifyOptions(certificate_stream=io.BytesIO(certificate))
with gs.Signature(str(signed_pdf)) as signature:
    is_valid = signature.verify(options).is_valid

Aynı çalıştırmada imzalama ve doğrulama, sessiz hata modunu anında bir hataya dönüştürür. Bir belge hattı için bu, bir dosyanın doğrulanamaması durumunda arşive, karşı tarafa ya da müşteri portalına hiç ulaşmayacağı anlamına gelir.

İş Etkisi: Denetim İçin Ne Değişir

Endişe Uygulama sunucusundaki PFX Vault Transit ile İmzalama
Özel anahtar kopyaları her sunucu, imaj, yedek ve dizüstü bilgisayar başına bir tane bir tane, Vault içinde
İmzalama uygulamasının ihtiyaç duyduğu haklar anahtar dosyasına tam erişim anahtarı okuma, transit/sign çağrısı
Bir belgenin imzalandığına dair kanıt uygulama günlükleri, biri eklediğinde imza başına bir Vault denetim kaydı
Şüpheli bir sızıntıya yanıt iptal et, yeniden yayınla, her yerde yeniden dağıt Vault’ta anahtarı döndür, bir kez yeniden yayınla
Adınıza kim imza atabilir dosyayı ve parolayı bilen herkes geçerli bir Vault belirteci tutan herkes

Son satır dürüst olandır. Bu tasarım, gizli bilgiyi ortadan kaldırmak yerine taşır: çalınan bir Vault belirteci hâlâ imza isteyebilir. Fark, belirtecinin kısa ömürlü, tek bir yerde iptal edilebilir, iki işleve sınırlı ve her kullanımı kaydedilmiş olmasıdır. Bu, kopyaları sayısı belirlenemeyen bir dosyadan çok, bir incelemede savunması çok daha kolay bir şeydir.

Gerçek İş Akışı: Bir Hizmet Tarafından İmzalanan Kredi Sözleşmesi

Bir kredi platformu, bir başvuru onaylandığında bir sözleşme PDF’i oluşturur, imzalar ve müşterinin belge kasasına koyar. Bu değişiklikten önce, imzalama hizmeti şirket sertifikasını tutar ve dağıtım çalıştırma kitabı yeni sunuculara PFX kopyalama adımına sahipti. Sonrasında, hizmet iki izne sahip bir AppRole belirteci tutar ve sertifikanın özel anahtarı hiçbir zaman Vault dışına çıkmaz.

Denetçiler, geçen çeyrekte kaç belge imzalandığını ve kim tarafından sorulduğunda, yanıt Vault’un denetim cihazından gelir, uygulama günlüklerini yeniden oluşturmak zorunda kalmazlar. Ekip anahtarı döndürdüğünde, tek bir yerde döndürür ve yeni sürüm için yeni bir sertifika yayınlar.

İlk Olarak Neyi Doğru Yapmalıyım?

Özet (digest) işleme. Yanlış bir algoritma adı yüksek sesle başarısız olur, Vault şu yanıtı verir
500 crypto/rsa: input must be hashed message, ve bir dakikalık bir gecikmeye yol açar. Eksik bir prehashed bayrağı ise hiç hata üretmez: Vault özeti tekrar hash’ler, imza yanlış değeri kapsar ve PDF tamamlanmış gibi görünür. İmzaladığınız her dosyayı doğrulayın; bu başarısızlık artık görünmez olmaz.

Bu Tasarımın Uygun Olduğu Diğer Yerler

Kanca, arkasında ne olduğu hakkında bir fikri yoktur, bu yüzden aynı dört adım bir donanım güvenlik modülü, bir bulut KMS veya bir akıllı kart üzerinde de çalışır. Bu yapıyı .NET kardeşinden Python’a taşıdığımda imzalayıcının yeniden çalışması gerektiğini düşündüm, ancak gerçekten değişen tek bölüm sertifika devriydi; Vault istek gövdesi ve sürüm sabitlemesi aynıydı. Sağlık, hükümet ve sigorta sektörlerindeki ekipler, finansın yaptığı aynı sebeple bunu tercih eder: anahtar, ne için kullanıldığını kanıtlayabilecek bir yerde olmalıdır.

Başlarken

Kaynaklar