HSM imzalama — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Enterprise HSM imzalama yüzeyi için derinlemesine başvurudur. Üç genel türü kapsar. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11Signer, ext-pkcs11 eklentisi aracılığıyla bir PKCS#11 token üzerinden imzalar. NextPDF\Enterprise\Security\Signature\Hsm\OpenSslCliSigner, PHP ext-openssl’in yükleyemediği sağlayıcı veya motor destekli anahtarlar için openssl ikili dosyası aracılığıyla bir alt süreçte imzalar. NextPDF\Enterprise\Security\Signature\Hsm\Provider\HsmSignerProviderAdapter, her iki somut türü de birleşik bir SignerProviderInterface olarak sunar. Her yolda özel anahtar token sınırının içinde kalır; NextPDF imzalanacak baytları teslim eder ve imzayı alır. Kuantum sonrası yol (signPqs) bir önizlemedir: varsayılan olarak devre dışıdır, hiçbir uygunluk iddiası taşımaz ve mevcut PDF doğrulayıcılarında desteklenen bir doğrulama yolu yoktur. NextPDF hiçbir sertifika tutmaz ve hiçbirini vermez; destek uygunluğa eşit değildir ve uygunluk sertifikaya eşit değildir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile birlikte gelir ve bir Enterprise katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Genel API yüzeyi

Üç türün tümü NextPDF\Enterprise\Security\Signature\Hsm içinde yer alır; adaptör onun Provider alt ad alanında bulunur. Her iki imzalayıcı da Core NextPDF\Contracts\HsmSignerInterface sözleşmesini uygular.

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
Pkcs11Signer::__construct()	string $libraryPath, int $slotId, string $pin, string $certLabel, ?string $keyLabel = null, array $chainDer = [], bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = null	Satıcı kütüphanesini açar, yuvaya giriş yapar ve sertifika ile anahtar algoritması meta verisini token’dan yükler	—	ext-pkcs11 yokken veya token erişimi başarısız olduğunda HsmOperationException	İşlem başına ve kütüphane yolu başına bir modül tanıtıcısı önbelleğe alınır; PIN ve etiketler #[SensitiveParameter]’dır
Pkcs11Signer::sign()	string $data, string $algorithm = 'sha256WithRSAEncryption'	Token üzerinde imzalar; ham ECDSA çıktısı DER ECDSA-Sig-Value biçimine dönüştürülür	string ham imza baytları	HsmOperationException (anahtar bulunamadı, token hatası); InvalidArgumentException (eşlenmemiş algoritma); bir uygulayıcı bağlandığında imzalamadan önce FIPS geçidi istisnaları	Kapalı algoritma kümesi; Davranış sözleşmesine bakın
Pkcs11Signer::signPqs()	string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = true	$enablePostQuantum ayarlanmadıkça reddedilir; geçici PKCS#11 PQ mekanizmasını gönderir	string ham imza baytları	HsmOperationException (devre dışı, token hatası, imza uzunluğu uyuşmazlığı); InvalidArgumentException (255 baytın üzerinde bağlam)	Önizleme; uygunluk iddiası yok; mekanizma tanımlayıcıları geçicidir
Pkcs11Signer::isPostQuantumEnabled()	Yok	Yapıcıdaki tercih bayrağını bildirir	bool	Yok	—
Pkcs11Signer::getCertificateDer()	Yok	Token’dan okunan imzalayıcı sertifikasını döndürür	string (DER)	Yok	Yapım sırasında bir kez yüklenir
Pkcs11Signer::getCertificateChainDer()	Yok	Yapıcıya verilen ara sertifikaları döndürür	array<string> (DER)	Yok	İmzalayıcı sertifikasını hariç tutar
OpenSslCliSigner::__construct()	string $keyUri, string $certPath, string $pin, array $extraCertPaths = [], OpenSslCliBackend $backend = OpenSslCliBackend::Auto, string $opensslBinary = 'openssl', int $timeoutSeconds = 30, ?string $modulePath = null, ?string $configPath = null, bool $legacyPinDelivery = false, ?FipsSignatureEnforcer $fipsEnforcer = null	proc_open’i doğrular, ikili dosyayı ve sürümü yoklar, arka ucu çözer ve sertifikaları yükler	—	HsmOperationException (proc_open devre dışı, eksik modül/yapılandırma/sertifika dosyası, ikili dosya hatası, arka uç yok); InvalidArgumentException ($keyUri içinde pin-value)	OpenSslCliBackend::Auto önce OpenSSL 3.x sağlayıcısını, ardından motoru tercih eder
OpenSslCliSigner::sign()	string $data, string $algorithm = 'sha256WithRSAEncryption'	Bir alt süreçte openssl dgst çalıştırır; PIN varsayılan olarak geçici bir 0600 pin-source dosyası üzerinden taşınır	string ham imza baytları	HsmOperationException (zaman aşımı, PIN reddedildi, anahtar bulunamadı, modül yükleme hatası, boş çıktı, pin dosyası hatası); InvalidArgumentException (eşlenmemiş algoritma); imzalamadan önce FIPS geçidi istisnaları	Alt süreç $timeoutSeconds sonrasında sonlandırılır; stderr, mesajlara ulaşmadan önce sansürlenir
OpenSslCliSigner erişimci yüzeyi	Yok	Salt okunur yapım sonuçları	string / array<string> / OpenSslCliBackend	Yok	getCertificateDer, getCertificateChainDer, getPublicKeyAlgorithm, getCertificatePem, getResolvedBackend, getOpensslVersion
HsmSignerProviderAdapter::__construct()	HsmSignerInterface $hsm, string $providerId, SignatureAlgorithm $algorithm = SignatureAlgorithm::Pkcs1v15	Bir HSM somut türünü SignerProviderInterface olarak sarmalar	—	Yok	Sağlayıcı kimliği kuralları: pkcs11-{module-id}, openssl-cli
HsmSignerProviderAdapter::providerId()	Yok	Yapıcıya verilen kimliği döndürür	non-empty-string	Yok	—
HsmSignerProviderAdapter::supportsAlgorithm()	SignatureAlgorithm $algo	Enum’u OpenSSL tarzı bir ada eşler, ardından arka ucun izin kümesiyle kesişir	bool	Yok	Yalnızca özet algoritmalarını reddeder; openssl-engine kimlikleri hiçbir şey duyurmaz
HsmSignerProviderAdapter::sign()	string $data, ?string $keyVersion = null	Yapılandırılmış algoritmayla sarmalanan imzalayıcı üzerinden gönderir	non-empty-string	KeyManagementException (null olmayan $keyVersion); SignatureFailedException (eşlenemeyen algoritma, sürücü hatası, boş imza)	Fail-closed SPI sözleşmesi; her sürücü hatası türlenmiş olarak yüzeye çıkar

public function __construct(private readonly string $libraryPath, private readonly int $slotId, #[SensitiveParameter] private readonly string $pin, #[SensitiveParameter] private readonly string $certLabel, #[SensitiveParameter] private readonly ?string $keyLabel = null, array $chainDer = [], private readonly bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = null)
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public function signPqs(string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = true): string
public function isPostQuantumEnabled(): bool
public function getCertificateDer(): string
public function getCertificateChainDer(): array

public function __construct(private string $keyUri, string $certPath, #[SensitiveParameter] private string $pin, array $extraCertPaths = [], private OpenSslCliBackend $backend = OpenSslCliBackend::Auto, private string $opensslBinary = 'openssl', private int $timeoutSeconds = 30, private ?string $modulePath = null, private ?string $configPath = null, private bool $legacyPinDelivery = false, private ?FipsSignatureEnforcer $fipsEnforcer = null)
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public function getCertificateDer(): string
public function getCertificateChainDer(): array
public function getPublicKeyAlgorithm(): string
public function getCertificatePem(): string
public function getResolvedBackend(): OpenSslCliBackend
public function getOpensslVersion(): string

public function __construct(private HsmSignerInterface $hsm, private string $providerId, private SignatureAlgorithm $algorithm = SignatureAlgorithm::Pkcs1v15)
public function providerId(): string
public function supportsAlgorithm(SignatureAlgorithm $algo): bool
public function sign(string $data, ?string $keyVersion = null): string

Davranış sözleşmesi

• Anahtar muhafazası. Özel anahtar token sınırından asla çıkmaz. Pkcs11Signer işlemi token’a devreder; OpenSslCliSigner, openssl alt sürecine bir anahtar referansı — bir PKCS#11 URI’si — geçirir. Hiçbir imzalayıcı anahtarı dışa aktaramaz.
• Oturum ve giriş. Pkcs11Signer, işlem başına ve kütüphane yolu başına bir PKCS#11 modül tanıtıcısını önbelleğe alır; çünkü token arabirimi işlem başına tam olarak bir kez başlatılmalıdır. Her işlem bir oturum açar ve PIN ile giriş yapar; giriş, herhangi bir özel anahtar kullanımından önce kullanıcının kimliğini doğrular (PKCS#11 v3.1 §5.6.8). Yuva mevcut bir giriş bildirdiğinde, imzalayıcı çıkış yapar ve yeniden giriş yapar; böylece işlem başına yeni bir PIN talep eden token’lar bunu alır.
• Algoritma kümesi (kapalı). Her iki imzalayıcı da tam olarak şunları kabul eder: sha256WithRSAEncryption, sha384WithRSAEncryption, sha512WithRSAEncryption; RSASSA-PSS, RSASSA-PSS-SHA256, RSASSA-PSS-SHA384, RSASSA-PSS-SHA512; ecdsa-with-SHA256, ecdsa-with-SHA384, ecdsa-with-SHA512. Pkcs11Signer ek olarak ecdsa-raw’ı kabul eder. Başka herhangi bir tanımlayıcı InvalidArgumentException fırlatır — hiçbir zaman yerine geçen bir algoritma imzalanmaz.
• PSS tuz bağlaması. Her PSS varyantı için tuz uzunluğu özet uzunluğuna eşittir — 32, 48 veya 64 bayt — ve hash ile MGF parametreleri seçilen özetle eşleşir. Bu, tuz uzunluğunun tipik olarak mesaj özetinin uzunluğu olduğu PSS mekanizma parametresi yapısını izler (PKCS#11 v3.1 §6.1.9). Her iki imzalayıcı da aynı eşleştirmeyi uygular; böylece bir arka uçta geçerli olan bir yapılandırma diğerinde de geçerlidir.
• ECDSA dönüşümü. Bir token, ECDSA imzasını r ve s’in ham, sıfır dolgulu birleşimi olarak döndürür (PKCS#11 v3.1 §6.3.1). Pkcs11Signer::sign(), bu çıktıyı PDF doğrulayıcılarının ve OpenSSL’in beklediği DER kodlu ECDSA-Sig-Value biçimine dönüştürür. Çağıran taraf ham biçimle asla ilgilenmez.
• PIN teslimi (CLI yolu). Güvenli varsayılanda, PIN yalnızca sahibe özel izinlerle oluşturulan geçici bir dosyaya yazılır, PKCS#11 URI pin-source özniteliği üzerinden referans verilir ve alt süreç çıktıktan sonra bağlantısı kaldırılır. Bu modda PIN, komut satırına yerleştirilmez ve alt süreç ortamına aktarılmaz. $legacyPinDelivery = true ile PIN, URI içine pin-value olarak gömülür ve bu, süreç komut satırında gözlemlenebilir; bu mod yalnızca tercihe bağlıdır.
• Alt süreç disiplini. OpenSslCliSigner, ikili dosyayı bir argüman dizisiyle başlatır — kabuk enterpolasyonu yoktur — $timeoutSeconds’i uygular, süre dolduğunda alt süreci sonlandırır ve stderr’i türlenmiş hatalara sınıflandırır. Bir istisna mesajında alıntılanmadan önce stderr’den gizli bilgiler sansürlenir.
• Adaptör anlamları. Bir HSM token’ının yönetilen bir anahtar sürümü kavramı yoktur; token üzerindeki anahtar, sürümün kendisidir. Bu nedenle HsmSignerProviderAdapter::sign(), null olmayan herhangi bir $keyVersion’ı yok saymak yerine KeyManagementException ile reddeder. supportsAlgorithm(), enum eşlemesini sarmalanan arka ucun kabul ettiği kümeyle kesiştirir; böylece adaptör, arka ucun imzalama sırasında reddedeceği bir mekanizmayı asla duyurmaz. Sürücüden gelen boş bir imza SignatureFailedException fırlatır.
• Kuantum sonrası önizleme. signPqs(), $enablePostQuantum yapıcı bayrağının arkasında geçitlenir ve aksi hâlde çalışmayı reddeder. Bağlam dizesi, ML-DSA bağlam sınırıyla eşleşecek şekilde 255 baytla sınırlıdır (FIPS 204). Döndürülen imza, seçilen Pkcs11PqsAlgorithm parametre kümesinin tam bayt uzunluğuyla eşleşmelidir, aksi hâlde çağrı başarısız olur. Mekanizma tanımlayıcıları geçici bir PKCS#11 PQ uzantısını izler ve nihai değildir. PAdES profilleri kuantum sonrası paketleri tanımaz, çoğu PDF doğrulayıcısı bu tür imzaları reddeder ve NextPDF bunlar için hiçbir doğrulama yolu sağlamaz. Hiçbir uygunluk iddia edilmez.

Kenar durumlar ve hata modları

• Pkcs11Signer’ı ext-pkcs11 olmadan oluşturmak hemen HsmOperationException fırlatır; eklenti standart PHP dağıtımlarıyla birlikte gelmez.
• Token’da hiçbir nesneyle eşleşmeyen bir sertifika veya özel anahtar etiketi, eksik nesne sınıfını adlandıran HsmOperationException fırlatır. Anahtar etiketi bazı token’larda sertifika etiketinden meşru şekilde farklı olabilir.
• Tekrarlanan başarısız girişler PIN’i token’da kilitleyebilir; bu politikayı NextPDF değil token uygular. Anahtarları her kullanımda kimlik doğrulaması gerektiren token’lar, çıkış-ve-yeniden-deneme yolu aracılığıyla yeni bir giriş alır (PKCS#11 v3.1, always-authenticate anlamları).
• OpenSslCliSigner, yapım sırasında zaten pin-value içeren bir $keyUri’yi fail-closed olarak reddeder; çünkü bu teslim, güvenli PIN yolunu atlardı.
• Windows’ta güvenli pin dosyası modu HsmOperationException ile fail-closed olur: dosya izin bitleri orada ACL okuma izinlerini kısıtlayamaz; bu nedenle imzalayıcı, geçici dizin ACL’sinde düz metin bir PIN bırakmayı reddeder. Eski PIN teslimi, güvenilir Windows ana makineleri için belgelenmiş, tercihe bağlı alternatiftir.
• Arka uç otomatik algılaması, sağlayıcı yolu için OpenSSL 3.x gerektirir; LibreSSL asla sağlayıcıya çözümlenmez. Ne bir sağlayıcı ne de bir motor yoklaması başarılı olduğunda, yapım hatayı imzalama zamanına ertelemek yerine HsmOperationException ile başarısız olur.
• $timeoutSeconds’i aşan bir alt süreç sonlandırılır ve zaman aşımı olarak bildirilir; boş çıktıyla temiz şekilde çıkan bir alt süreç, boş imza hatası olarak bildirilir. Hiçbir koşul kısmen imzalanmış bir belge üretemez.
• Bayt uzunluğu seçilen parametre kümesiyle eşleşmeyen bir kuantum sonrası imza, CMS kodlamasına ulaşamadan reddedilir.
• Kullanımdan kaldırılmış openssl-engine sağlayıcı kimliğine sahip HsmSignerProviderAdapter hiçbir algoritma duyurmaz; böylece eski bir yapılandırma, imzalama zamanında değil sağlayıcı seçiminde başarısız olur.

FIPS modu davranışı

Her iki imzalayıcı da isteğe bağlı bir FipsSignatureEnforcer kabul eder. Biri bağlandığında, o imzalayıcı için FIPS modu etkindir: sign(), herhangi bir token veya alt süreç imzalaması gerçekleşmeden önce izin verilmeyen bir imza algoritmasını veya taban altı bir anahtarı reddeder. Tabanlar imza üretim tablosunu izler — 2048 bitin altındaki RSA modülleri ve 224 bitin altındaki ECDSA dereceleri izin verilmez (NIST SP 800-131A Rev.2 §3 Table 2). Uygulayıcı yokken davranış değişmez. Geçit yalnızca klasik sign() yolunu kapsar; signPqs() kendi önizleme bayrağıyla yönetilir. Bunlar NextPDF koduna ilişkin yetenek iddialarıdır: FIPS 140-3 doğrulaması, bir kriptografik modüle CMVP aracılığıyla bağlanır; bu dağıtımda bu modül, operatörün HSM’i veya sağlayıcısıdır — NextPDF doğrulanmış bir modül değildir, hiçbir sertifika tutmaz ve hiçbirini vermez.

Uygunluk

İddia	Standart	Madde
Giriş, özel anahtar işlemlerinden önce kullanıcının kimliğini token’a doğrular; yanlış bir PIN erişimi reddeder.	PKCS#11 v3.1	§5.6.8
Always-authenticate anahtarları her kullanımda yeni bir giriş gerektirir; tekrarlanan başarısız yeniden kimlik doğrulama PIN’i kilitleyebilir.	PKCS#11 v3.1	CKA_ALWAYS_AUTHENTICATE re-authentication
Bir token ECDSA imzası ham r‖s birleşimidir; imzalayıcı bunu PDF birlikte çalışabilirliği için DER’e dönüştürür.	PKCS#11 v3.1	§6.3.1
PSS parametreleri hash, MGF ve tuz uzunluğunu bağlar; imzalayıcılar tuzu özet uzunluğuna eşit ayarlar.	PKCS#11 v3.1	§6.1.9
FIPS geçidi, 2048 bitin altındaki RSA veya 224 bitin altındaki ECDSA derecesiyle imza üretimini reddeder.	NIST SP 800-131A Rev.2	§3 Table 2
Kuantum sonrası bağlam dizesi 255 baytla sınırlıdır.	FIPS 204	HashML-DSA context handling
FIPS 140-3 doğrulaması, kriptografik modüllere CMVP aracılığıyla bağlanır.	FIPS 140-3	CMVP program scope

Tüm maddeler açımlanmıştır; hiçbir normatif metin yeniden üretilmemiştir. NextPDF hiçbir sertifika iddiasında bulunmaz. İmzalayıcılar, davranışlarını bir yetenek olarak alıntılanan maddelerle uyumlu hâle getirir. Üretilen bir imzanın doğrulanıp doğrulanmadığı, doğrulayıcının kendi güven çıpalarına karşı verdiği bir karardır; anahtar güvenliği yalnızca NextPDF’e değil, token’a, HSM’e ve operatöre bağlıdır.

Geliştirme notları

• PIN teslim mekanizması, PKCS#11 URI pin-source kuralını izler (RFC 7512); bu RFC alıntılanan külliyatın dışındadır, bu nedenle yukarıdaki davranış bir spesifikasyon alıntısına değil ürün kaynağına dayandırılmıştır.

• Pkcs11Signer’ı oluşturmadan önce çalışma zamanının ext-pkcs11’i yüklediğini doğrulayın; eklenti yokken yapım hızlıca başarısız olur. CLI imzalayıcısı, etkinleştirilmiş proc_open ile bir PKCS#11 sağlayıcısı veya motoru kurulu bir openssl ikili dosyasına ihtiyaç duyar.

• PIN, sertifika etiketi ve anahtar etiketi #[SensitiveParameter]’dır, bu nedenle yığın izlerinden hariç tutulur. PIN’i bir gizli bilgi yöneticisinden sağlayın; asla kaynağa, sürüm denetimine işlenmiş yapılandırmaya veya günlüklere yazmayın.

• Yapım, her iki imzalayıcıda da pahalı adımdır: PKCS#11 yolu giriş yapıp sertifikayı okur, CLI yolu ise ikili dosyayı ve arka ucu yoklar. Bir kez oluşturun ve örneği yeniden kullanın; kütüphane başına modül önbelleği, aynı kütüphaneye karşı tekrarlanan yapımı güvenli kılar.

• Çağıran taraf SignerProviderInterface üzerinden çalıştığında bir imzalayıcıyı HsmSignerProviderAdapter içine sarın. Sarmalanan sınıf için kurallı sağlayıcı kimliğini geçirin — pkcs11-{module-id} veya openssl-cli — böylece yetenek denetimleri doğru arka uç izin kümesini kullanır.

• Kuantum sonrası önizlemeyi etkinleştirmeden önce, token donanım yazılımının mekanizma tanımlayıcılarını NextPDF’in kaydettiği geçici değerlere karşı doğrulayın; bir uyuşmazlık imzalama zamanında başarısız olur. Önizlemeyi üretim PAdES çıktısı için etkinleştirmeyin.

• getResolvedBackend() ve getOpensslVersion(), kanıt kaydı için mevcuttur; uygunluk programınız yeniden üretilebilirlik gerektirdiğinde bunları imzalama kanıtıyla birlikte kalıcılaştırın.

Ayrıca bakınız

• Donanım güvenlik modülü imzalama (PKCS#11) — kurulum, yapılandırma ve doğrulama adımlarını içeren yetenek sayfası.
• Güvenlik — derinlemesine başvuru — birleşik Enterprise güvenlik yüzeyi.
• İmza — derinlemesine başvuru — PAdES B-LT / B-LTA uzun vadeli üretici.
• FIPS 140 — derinlemesine başvuru — kripto politikası, otomatik test bataryası ve FipsSignatureEnforcer geçidi.
• PQC önizleme — derinlemesine başvuru — kuantum sonrası önizleme yüzeyi ve sınırları.
• Güvenlik / İmzalama (Core) — Core CMS imzalayıcısı ve imzalama sözleşmeleri.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalışma kılavuzu dosya adları ve bilet önekleri kapsam dışıdır.