NextPDF Connect (Pro) ile bir PDF'ye PAdES dijital imzası uygulayın

Genel bakış

Bir PDF’ye NextPDF Connect üzerinden temel bir PDF Advanced Electronic Signatures (PAdES) dijital imzası uygulayın. Bunun için sign_pdf aracını kullanın: Bu araç, new SignPdfTool() nesnesini kaydeden Pro araç sağlayıcısı üzerinden yeniden doğrulanmıştır ve nesnenin protokol adı sign_pdf’tir. sign_pdf bir Pro katmanı aracıdır. Sunucu, başlatılırken bu aracı class_exists() ile yoklar ve yalnızca Pro paketi kurulu olduğunda kaydeder.

Araç varsayılan olarak PAdES B-B üretir. PAdES B-T (B-B artı bir RFC 3161 signature-time-stamp) ancak ana sistem araca bir zaman damgası sağlayıcısı bağladığında üretilebilir; istek bir Time Stamp Authority (TSA) belirtemez. Uzun vadeli seviyeler (B-LT, B-LTA) ve bunların doğrulama materyali (DSS, VRI, LTV) bu aracın bir parçası değildir ve burada kapsam dışıdır.

U-1 uyarısı. NextPDF, herhangi bir bağımsız ETSI EN 319 142-1 PAdES B-T sertifikasyonu öne sürmez. EN 319 142-1 doğrulama külliyatına dahil değildir. B-T’nin signature-time-stamp gereksinimi şu kaynaklara göre doğrulandı: ETSI EN 319 122-1 §5.3 (EN 319 142-1/-2’nin atıfla içe aktardığı CAdES temeli), ayrıca RFC 3161, RFC 5652, RFC 5816 ve ISO 32000-2 §12.8. B-T profilinin desteklenmesi bir uygunluk veya yasal geçerlilik sertifikasyonu değildir; bu değerlendirmeyi bağımsız bir doğrulayıcı yapar.

Kurulum

composer require nextpdf/server
composer require nextpdf/pro

Bir taşıma katmanı bağlayın, ardından sign_pdf aracının diagnostic.capabilities ile var olduğunu doğrulayın. B-T için ana sistem, aracı bir zaman damgası sağlayıcısıyla oluşturmalıdır. Sağlayıcı olmadan, bir pades_b_t: true isteği sessizce alt seviyeye düşmek yerine türü belirtilmiş bir hatayla başarısız olur.

Kavramsal genel bakış

sign_pdf, imza değeri yer tutucusunu hariç tutarak dosya üzerinde bir byte-range özeti hesaplar (ISO 32000-2 §12.8.1). Ardından, Distinguished Encoding Rules (DER) ile kodlanmış Cryptographic Message Syntax (CMS) SignedData verisini imza sözlüğündeki Contents alanına yazar (ISO 32000-2 §12.8.1). Desteklenen algoritmalar RSA-SHA256 (varsayılan), RSA + SHA-3 (256/384/512) ve Ed25519’dur. Uçtan uca gizlilik sağlamayan taşıma katmanlarında, gelen private_key yükünü isteğe bağlı bir AES-GCM zarfına sarabilirsiniz.

B-T yükseltmesi. pades_b_t: true ve ana sistem tarafından bağlanmış bir zaman damgası sağlayıcısı mevcutken, imza PAdES B-T seviyesine yükseltilir: byte-range özeti bir TSA’ya gönderilir ve bir TimeStampToken gömülür (ISO 32000-2 §12.8.5). B-T, tam olarak B-B artı CMS SignerInfo üzerinde imzasız bir öznitelik olarak taşınan bir RFC 3161 signature-time-stamp’tir (RFC 5652 §5.3). İmzasız öznitelikler imza kapsamında değildir; dolayısıyla B-B imzalı özeti ve onun geçerliliği değişmez (RFC 5652 §5.3). Öznitelik değeri bir SignatureTimeStampToken’dır (ETSI EN 319 122-1 §5.3). B-T, hiçbir Document Security Store (DSS) sözlüğü, hiçbir Validation Related Information (VRI), hiçbir doğrulama materyali ve hiçbir arşiv zaman damgası döngüsü eklemez. Bunlar B-LT/B-LTA için Enterprise’a özgü farklardır ve bu aracın kapsamı dışındadır.

U-1 uyarısı (B-T iddiasında yinelenir). Buradaki B-T desteği bir EN 319 142-1 uygunluğu veya yasal geçerlilik sertifikasyonu değildir; buna bağımsız bir doğrulayıcı karar verir. EN 319 142-1 doğrulama külliyatına dahil değildir. B-T şuna dayanır: ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 ve ISO 32000-2 §12.8.

Aşağıdaki akış, ana sistem tarafından geçit denetimli TSA yolunu (istek bir TSA belirtemez) ve hataya karşı kapalı B-T dalını (asla sessizce daha düşük bir seviyeye düşürme yok) gösterir.

Diagram

API yüzeyi

Araç	Katman	Rol	Risk katmanı
create_pdf, add_text	Core	İçerik oluşturur	Güvenli / Dikkat
sign_pdf	Pro	PAdES B-B (veya ana sistem geçit denetimli B-T) uygular	Onay Gerekli
output_pdf	Core	PDF’yi işle ve döndür	Onay Gerekli / İnceleme (base64)

Araç adları, kayıt defterindeki protokol adlarıdır. Araç kataloğu resmi kayıt kataloğudur. Kullanılabilir araçlar kurulu katmana bağlıdır ve uzun vadeli seviye araçları Pro’da bulunmaz.

Kod örneği — hızlı başlangıç

1. create_pdf → add_text ile içerik oluşturun.
2. sign_pdf: certificate (PEM), private_key (PKCS#8 PEM), isteğe bağlı signer_name, reason ve algorithm ile çağırın. B-B için pades_b_t alanını atlayın (ya da false olarak ayarlayın).
3. output_pdf.

Araç aşağıdaki sonuç zarfını döndürür:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Ana sistem geçit denetimli bir B-T imzası için pades_b_t: true gönderin; level değeri "PAdES-B-T" olur ve timestamped değeri true olur.

Kod örneği — üretim

İmzayı son içerik işlemi olarak uygulayın. Herhangi bir add_text/add_image (sign_pdf işleminden sonra) imzayı geçersiz kılar. Gizlilik sağlamayan bir taşıma katmanında private_key anahtarını AES-GCM transport_encryption zarfına sarın (12 byte’lık nonce; 16/24/32 byte’lık anahtar). Sonuçtaki level değerinin isteğinizle eşleştiğini doğrulayın. Zaman damgası sağlayıcısı olmayan bir araca karşı yapılan pades_b_t: true isteği açıkça başarısız olur. Bu hatayı ele alın ve sessizce B-B olarak yeniden denemeyin.

Uç durumlar & tuzaklar

• Sertifika/anahtar uyuşmazlığı. Araç isteği açık bir hatayla reddeder; özel anahtar, sertifikanın açık anahtarıyla eşleşmelidir.
• Hatalı biçimli PEM / süresi dolmuş sertifika. Araç isteği reddeder; varsayılan olarak ayrıştırılamayan ya da süresi dolmuş bir sertifikayla imzalamaz.
• İmzalamadan sonra içerik. Araç isteği reddeder — en son imzalayın.
• B-T istendi, sağlayıcı yok. Araç türü belirtilmiş bir hata döndürür: imza üretilmez ve sessizce B-B seviyesine düşürülmez.
• Kendinden imzalı sertifika. İmza uygulanır, ancak okuyucular güven durumunu bilinmeyen olarak gösterir. Bu, bir araç kusuru değil, beklenen bir durumdur.
• Pro yok. Yalnızca Core ile, sunucu sign_pdf aracını kaydetmez.

Performans

İmzalama, CMS oluşturmayı ve B-T için bir TSA gidiş-dönüşünü içerir; bütçe her ikisini de kapsar. Profil semantic’tir: bir RFC 3161 belirteci doğası gereği yeniden üretilebilir değildir ve §12.8.1 byte-range özeti imza değerini hariç tutar. Yalnızca bir AST + imza meta verisi karşılaştırması kullanın.

Güvenlik notları

Bir imza, imzalama anahtarına göre bütünlük ve kimlik doğrulama sağlar. Tek başına bir belgeyi “güvenli” veya “yasal olarak geçerli” yapmaz; inkâr edilemezliği de garanti etmez. Bu sonuçlar sertifikaya, sertifikanın güven köküne, anahtar saklamaya ve doğrulayıcının ilkesine bağlıdır; hepsi bu aracın dışındadır. Anahtar yükünü AES-GCM zarfıyla şifrelemek, aktarım sırasında bütünlüğü değil, gizliliği korur. Özel anahtarı bir sır olarak ele alın ve gizlilik sağlamayan herhangi bir kanalda aktarım şifreleme zarfını tercih edin.

Uygunluk

İfade	Belirtim	Madde	reference_id
Byte-range özeti dosyayı kapsar ve imza değerini hariç tutar.	ISO 32000-2	§12.8.1
Contents, DER ile kodlanmış CMS SignedData verisini tutar.	ISO 32000-2	§12.8.1
Bir zaman damgası için, byte-range hash’i bir TSA’ya gider ve belirteç Contents içine yerleştirilir.	ISO 32000-2	§12.8.5
B-T zaman damgası, SignerInfo üzerinde imzasız bir özniteliktir.	RFC 5652	§5.3
İmzasız öznitelikler B-B imzalı digest/validity değerini değiştirmez.	RFC 5652	§5.3
signature-time-stamp değeri bir SignatureTimeStampToken’dır.	ETSI EN 319 122-1	§5.3

NextPDF imza yapısını üretir. Ortaya çıkan herhangi bir imzanın uygun ya da yasal olarak geçerli olduğunu öne sürmez; buna bağımsız bir doğrulayıcı karar verir. Bu araç B-LT/B-LTA üretmez.

Ticari bağlam

sign_pdf bir Pro katmanı aracıdır. Sunucu bu aracı yalnızca Pro paketi sunucu başlatılırken çözümlendiğinde kaydeder. PAdES uzun vadeli seviyeleri (B-LT, B-LTA) ve bunların doğrulama materyali (DSS, VRI, LTV) yalnızca Enterprise’a özeldir ve bu araç ya da bu tarif tarafından sunulmaz.

Veri ikametgâhı & PII azaltımları

Sertifika ve özel anahtar istek üzerinden aktarılır. Uçtan uca gizlilik sağlamayan herhangi bir kanalda AES-GCM transport_encryption zarfını kullanın. İmzalı PDF ve imzalayan kimliği (signer_name, reason) belge içeriğidir; bu nedenle onları veri ikametgâhı sınırınız içinde tutun. Dağıtım düzeyindeki ikametgâhtan entegratör sorumludur.

Güvenli telemetri & günlük temizleme

Şunları asla günlüğe yazmayın: private_key yükü, AES-GCM key/nonce değeri veya onay belirteci. Anahtar materyalini değil; algoritmayı, ortaya çıkan level değerini ve signature_count değerini günlüğe yazın. Araç, sonuçta anahtar baytları yaymaz.

Tehdit modeli

Değerlendirilen tehditler: aktarım sırasında anahtar ifşası (AES-GCM zarfı ve ana sistem tarafından enjekte edilen, istek üzerinden yapılandırılamayan TSA sağlayıcısı ile azaltılır); zaman damgasını rastgele bir uç noktaya yönlendiren bir MCP çağrısı (sağlayıcı ana sistem tarafından enjekte edildiği ve istek üzerinden yapılandırılamadığı için önlenir); ve imzalama sonrası kurcalama (byte-range özeti değişikliği saptar). Bir tehdit modeli, değerlendirilen tehditleri ve azaltımları belgeler; güvenlik açıklarının yokluğunu öne sürmez.

FIPS modu davranışı

Algoritma seçimi (RSA-SHA256, RSA + SHA-3, Ed25519) istek odaklıdır. Kriptografik temel öğeleri ana sistemin OpenSSL’i sağlar. FIPS kısıtlamalı bir dağıtımda, algoritmayı ilke katmanında sınırlayın ve ana sistemin doğrulanmış modülüne güvenin. Bu araç, Federal Information Processing Standards (FIPS) doğrulamasını kendisi öne sürmez.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Evet (Pro)	stdio üzerinde AES-GCM anahtar zarfını kullanın.
REST	Evet (Pro)	TLS artı anahtar zarfını tercih edin.
gRPC	Evet (Pro)	TLS artı anahtar zarfını tercih edin.

HITL risk katmanı

sign_pdf, yıkıcı ve geri alınamaz bir işlem olduğu için Onay Gerekli kapsamındadır; araç yıkıcı bir ipucu bildirir. Onay geçidi, herhangi bir Onay Gerekli araçta olduğu gibi geçerlidir. Bir dosyaya yapılan output_pdf da Onay Gerekli kapsamındadır; base64 modu İnceleme kapsamındadır (HITL risk katmanları).

Onay geçidi JSON zarfı

sign_pdf, geçerli bir belirteç olmadan challenge zarfını döndürür:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Bunu, _confirmation_token değeri belirtece ayarlanmış olarak yeniden çağırın → { "allowed": true }. Tam akış: output-approval.

Ayrıca bakınız

• Metin içeriği çıkarma
• Erişilebilirlik denetimi
• HITL risk katmanları
• Araç kataloğu