Donanım güvenlik modülü imzalama (PKCS#11)

Bir bakışta

NextPDF Enterprise, bir PDF’i bir donanım güvenlik modülü (HSM) içinde tutulan bir anahtarla imzalar. İmzalayıcıyı bir PKCS#11 belirtecine — bir akıllı kart, bir Evrensel Seri Veri Yolu (USB) belirteci veya ağa bağlı bir HSM — yönlendirirsiniz ve imzalama işlemi cihazda çalışır. Özel anahtar, belirteç sınırını asla terk etmez. Bu sayfa davranış düzeyindedir: imzalayıcının ne yaptığını, neyi sağladığınızı ve anahtar muhafazasının nerede NextPDF’in sorumluluğu olmaktan çıktığını belirtir.

HSM imzalayıcısı, Core imzalayıcı sözleşmesi aracılığıyla çözümlenir; böylece uygulamanız somut Enterprise türüne değil, sözleşmeye bağımlı olur. Core’un kullandığı aynı Cryptographic Message Syntax (CMS) imzalama yolunu genişletir; tek fark, kriptografik işlemin belirtece devredilmesidir.

Ön koşullar ön bilgide belirtilmiş ve görev ortasında şaşırmamanız için Ön koşullar altında yinelenmiştir.

Sürüm ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) içinde sunulur ve bir Enterprise-katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye 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.

NextPDF Core, anahtarı süreç içinde tutan veya Core imzalama-stratejisi sözleşmesi aracılığıyla bir anahtar kabul eden bir yazılım CMS imzalayıcısı sunar; NextPDF Pro, uzak ve bulut anahtar-yönetim-hizmeti (KMS) imzalama stratejileri ekler. PKCS#11 aracılığıyla donanım anahtar muhafazası bir Enterprise yeteneğidir ve Core veya Pro tarafından sağlanmaz.

Bu yetenek ne yapar

Bir PKCS#11 belirteci, kriptografik nesneleri — sertifikalar ve özel anahtarlar — bir satıcı paylaşılan kitaplığının arkasında açığa çıkarır. Enterprise imzalayıcısı o kitaplığı uyarlar:

1. PKCS#11, modülün süreç başına tam olarak bir kez başlatılmasını gerektirdiğinden belirtecin paylaşılan kitaplığını süreç başına bir kez açar ve modül tutamacını önbelleğe alır.
2. Yapılandırılmış yuvada bir oturum açar ve sağlanan PIN ile oturum açar. Oturum açma, herhangi bir özel-anahtar işleminden önce kullanıcının kimliğini doğrular — PKCS#11 v3.1 §5.6.8.
3. İmzalama sertifikasını belirteçte etikete göre bulur, sertifikayı Ayırt Edici Kodlama Kuralları (DER) biçiminde okur ve genel anahtar algoritmasını algılar.
4. İmzalama sırasında özel anahtarı etikete göre bulur — bu, bazı belirteçlerde sertifika etiketinden farklı olabilir — ve belirteçten imzayı hesaplamasını ister. İmzalanacak veri içeri geçirilir; anahtar cihazda kalır.

İmzalayıcı; PKCS#1 v1.5 dolgulu RSA (SHA-256, SHA-384, SHA-512), tuz uzunluğunun özet uzunluğuna eşit olduğu Olasılıksal İmza Şeması (PSS) dolgulu RSA ve SHA-256, SHA-384 ve SHA-512 ile Eliptik Eğri Dijital İmza Algoritması (ECDSA) destekler. ECDSA eğrisi ve özet, geleneksel olarak eşleştirilir — P-256 ile SHA-256, P-384 ile SHA-384, P-521 ile SHA-512 — ve RFC 5480 içindeki önerilen eşleştirmeyi izler. Bir belirteç, bir ECDSA imzasını iki tam sayının ham bir birleştirmesi olarak döndürür; imzalayıcı bunu, PDF ve OpenSSL’in beklediği DER ile kodlanmış biçime dönüştürür.

İmza üretimi için, NIST SP 800-131A Rev.2 §3 uyarınca en az 2048 bitlik bir RSA anahtarı ve en az 224 bitlik bir ECDSA eğri mertebesi kabul edilebilir minimumlardır. Belirteç anahtarınızı bu boyutlarda veya üzerinde sağlayın.

Motor destekli belirteçler için alternatif bir OpenSSL-motoru yolu vardır. OpenSSL 3.x üzerinde PHP OpenSSL uzantısı motor uygulama programlama arayüzünü (API) açığa çıkarmaz; bu nedenle motor sınıfı kullanımdan kaldırılmıştır; desteklenen motor destekli yol, OpenSSL komut satırı ikilisini çalıştırır. Belirtecinizin bir PKCS#11 kitaplığı olduğu yerde doğrudan PKCS#11 yolunu tercih edin.

Neden bu şekilde çalışır

Yük taşıyan karar, özel anahtarın belirteci asla terk etmemesidir. Bu nedenle imzalayıcı, kriptografik işlemi cihaza devreder ve PKCS#11 dikişi boyunca yalnızca imzalanacak-veriyi taşır. Anahtar materyalini PHP belleğinde asla okumaz veya yeniden oluşturmaz. Somut bir Enterprise türü yerine Core HsmSignerInterface sözleşmesi aracılığıyla çözümlenir; böylece imzalama kodu, anahtar ister yazılımda, ister bir bulut KMS’sinde, ister bir donanım belirtecinde bulunsun aynıdır. PKCS#11 her modülü süreç başına tam olarak bir kez başlattığından modül tutamacını süreç başına bir kez önbelleğe alır, ardından belirtecin ham ECDSA çıktısını DER’e dönüştürür; böylece doğrulayıcılar bekledikleri kodlamayı görür. Biçimi kolaylık değil, muhafaza belirler: güven sınırı cihaz kenarında kalır.

Tasarım arka planı: HSM destekli imzalama.

Ön koşullar

Bir HSM ile imzalamadan önce her ögeyi doğrulayın:

1. NextPDF Core’u ve Enterprise paketini kurun: composer require nextpdf/core:^3 ve composer require nextpdf/enterprise.
2. Etkin bir NextPDF Enterprise lisansına sahip olun; paketi Private Packagist’te lisans kimlik bilgilerinizle çözümleyin.
3. Belirteç satıcısının PKCS#11 paylaşılan kitaplığını ana makineye kurun (örneğin Linux’ta bir .so veya Windows’ta bir .dll) ve mutlak yolunu, yuva numarasını ve nesne etiketlerini not edin.
4. ext-pkcs11 PHP uzantısını yükleyin. Standart PHP ile birlikte gelmez ve ayrıca kurulmalıdır. Uzantı bulunmadığında imzalayıcı yapıcısı türlenmiş bir işlem hatası yükseltir.

Yapılandırma

İmzalayıcıya şu girdileri sağlayın:

• Kitaplık yolu — satıcı PKCS#11 paylaşılan kitaplığının mutlak yolu.
• Yuva tanımlayıcısı — belirteç yuva numarası, genellikle 0.
• PIN — belirteç PIN’i. Bunu bir gizli olarak ele alın: onu asla kaynaktan veya günlüklerden değil, gizli yöneticinizden sağlayın. İmzalayıcı, PIN parametresini hassas olarak işaretler; böylece yığın izlerinin ve serileştirmenin dışında tutulur.
• Sertifika etiketi — belirteçteki sertifika nesnesinin etiketi.
• Anahtar etiketi — özel-anahtar nesnesinin etiketi, sertifika etiketinden farklı olduğunda.
• Zincir — belirteç bunları tutmadığında, DER biçiminde isteğe bağlı ara sertifikalar.

İmzalayıcıyı oluşturmadan önce belirteç kullanılabilirliğini denetleyin. Oluşturma, sertifikayı belirteçten okur; böylece yanlış yapılandırılmış bir yuva veya etiket, imzalama sırasında değil, türlenmiş bir hatayla hızlıca başarısız olur.

Adım adım

1. Uzantı kullanılabilirliğini denetleyerek çalışma zamanının PKCS#11’i desteklediğini doğrulayın. Uzantı bulunmadığında imzalayıcıyı oluşturmayın.
2. PIN’i gizli yöneticinizden asla günlüğe kaydedilmeyen bir değişkene okuyun.
3. HSM imzalayıcısını kitaplık yolu, yuva, PIN ve etiketlerle oluşturun. Oluşturma, oturum açar ve sertifikayı okur.
4. İmzalayıcıyı HsmSignerInterface aracılığıyla Core imzalama düzenleyicisine geçirin. Düzenleyici, bayt aralığını hesaplar, CMS imzalı özniteliklerini oluşturur, veriyi belirtece teslim eder ve imzalı PDF’i birleştirir.
5. En özgül hatayı yakalayın, PIN olmadan yapısal bir mesaj günlüğe kaydedin ve yeniden fırlatın.

examples/contracts/hsm-signer-availability.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Build a hardware-token signer only when the runtime supports it.
 *
 * The concrete PKCS#11 signer is resolved through the Core contract so the
 * caller depends on the interface, not the Enterprise implementation type.
 * The PIN arrives from a secret resolver; it is never written to source.
 *
 * @param callable(): bool                $pkcs11Available Reports ext-pkcs11 availability.
 * @param callable(): HsmSignerInterface  $signerFactory   Builds the configured token signer.
 *
 * @throws \RuntimeException When the PKCS#11 extension is not loaded.
 *
 * @return HsmSignerInterface The token signer, ready for the Core orchestrator.
 */
function resolveHsmSigner(callable $pkcs11Available, callable $signerFactory): HsmSignerInterface
{
    if ($pkcs11Available() !== true) {
        throw new \RuntimeException(
            'PKCS#11 signing requires the ext-pkcs11 extension; install it before signing.',
        );
    }

    return $signerFactory();
}

Üretim bağlantısı — tam yapıcı bağımsız değişken listesi ve türlenmiş istisna türleri — HSM derinlemesine referansında belgelenmiştir.

examples/contracts/hsm-sign-guarded.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class HsmSigningService
{
    public function __construct(
        private HsmSignerInterface $signer,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign data on the token through the Core HSM contract.
     *
     * The byte range is computed by the engine, never accepted from the
     * caller. The token performs the signing operation; the private key
     * does not leave the device.
     *
     * @param string $data      The bytes the orchestrator hands to the token.
     * @param string $algorithm The OpenSSL-style signing algorithm identifier.
     *
     * @throws NextPdfException When the token operation fails.
     *
     * @return string The raw signature bytes returned by the token.
     */
    public function sign(string $data, string $algorithm): string
    {
        try {
            return $this->signer->sign($data, $algorithm);
        } catch (NextPdfException $e) {
            // Structural message only — never the PIN or key material.
            $this->logger->error('HSM signing failed', ['reason' => $e->getMessage()]);

            throw $e;
        }
    }
}

Doğrulama

Sonucu bir doğrulayıcının yapacağı gibi doğrulayın:

1. İmzalayıcı sertifikasını ve zincirini imzalayıcıdan DER biçiminde geri okuyun ve belirteçte sağlanan sertifikayla eşleştiklerini doğrulayın.
2. İmzalı PDF’i güven çıpalarınızla yapılandırılmış bir doğrulayıcıda açın ve imzanın kriptografik olarak bozulmamış olarak bildirildiğini doğrulayın. Üretilen bir imza, doğrulanmış bir imza değildir; güven kararı, üreticiye değil, doğrulayıcıya ve onun güven çıpalarına aittir.
3. Bir ECDSA imzası için, gömülü imzanın DER ile kodlanmış olduğunu doğrulayın — imzalayıcı, belirtecin ham çıktısını sizin için dönüştürür; böylece ham birleştirilmiş biçimi reddeden bir doğrulayıcı yine de gömülü imzayı kabul etmelidir.
4. Hiçbir PIN, belirteç etiketi veya anahtar materyalinin uygulama günlüklerinizde görünmediğini doğrulayın.

Güvenlik ve uyumluluk

• Anahtar belirteçte kalır. İmzalanacak veri belirtece teslim edilir; imzalama işlemi belirteç sınırı içinde çalışır. Özel anahtar asla PHP belleğine yüklenmez.
• PIN bir gizlidir. Hassas bir yapıcı parametresidir, günlüklerin ve serileştirmenin dışında tutulur. Onu bir gizli yöneticiden sağlayın. Tekrarlanan başarısız yeniden kimlik doğrulaması, PIN’i belirteçte kilitleyebilir; o politikayı NextPDF değil, belirteç zorunlu kılar.
• Fail-closed. Bir belirteç veya HSM hatası türlenmiş bir istisna yükseltir. İmzalayıcı, imzalanmamış veya kısmen imzalanmış bir sonuç üretmez ve asla daha zayıf bir algoritmayı ikame etmez.
• Algoritma gücü. NIST SP 800-131A Rev.2 §3 uyarınca imza üretimi için kabul edilebilir minimumlar olan en az 2048 bitlik RSA anahtarları ve en az 224 bit mertebesinde ECDSA eğrileri sağlayın.
• Kuantum sonrası imzalama deneyseldir ve varsayılan olarak kapalıdır. Açık bir katılım bayrağının arkasında bir kuantum sonrası yol bulunur. Standart PDF Advanced Electronic Signatures (PAdES) uzun süreli arşiv profilleri henüz kuantum sonrası takımları tanımaz ve çoğu görüntüleyici bunları doğrulamada reddeder. Üretim PAdES imzaları için bunu etkinleştirmeyin.

Bu sayfa, kriptografik imzalama ve donanım-güvenlik-modülü entegrasyonuyla ilgilidir. Her normatif kaynak başka sözcüklerle ifade edilmiştir; hiçbir normatif metin yeniden üretilmez. ### Anahtar-muhafaza sınırı

NextPDF Enterprise, bir PKCS#11 belirteci veya HSM ile bütünleşir. İmzalama anahtarını saklamaz, üretmez veya güvenliğini garanti etmez. Anahtar güvenliği; belirtece veya HSM’ye, dağıtıma ve operatöre bağlıdır — yalnızca NextPDF Enterprise uygulamasına değil. Belirteç sağlama, PIN işleme, yuva yapılandırması ve ağa bağlı bir HSM’nin ağ korumasından siz sorumlusunuz.

Hata işleme

• Uzantı bulunmuyor. ext-pkcs11 yüklü olmadığında PKCS#11 imzalayıcısını oluşturmak, türlenmiş bir işlem istisnası yükseltir. Önce kullanılabilirliği denetleyin.
• Sertifika veya anahtar etikete göre bulunamadı. Oluşturma veya imzalama, eksik nesneyi adlandıran türlenmiş bir istisna yükseltir. Etiketi ve yuvayı doğrulayın.
• Zaten oturum açılmış. Birkaç imzalayıcı örneği aynı yuva için önbelleğe alınmış bir modülü paylaştığında, imzalayıcı taze bir PIN doğrulaması sağlamak için oturumu kapatır ve yeniden oturum açar — “her seferinde PIN” politikası olan kişisel-kimlik-doğrulama belirteçleri için gereklidir.
• Desteklenmeyen algoritma. İmzalayıcının eşlemediği bir algoritmayı istemek, bir ikame ile imzalamak yerine bir bağımsız değişken hatası yükseltir.
• Ağ HSM’si erişilemiyor. Bir ağ veya cihaz hatası türlenmiş bir istisna yükseltir; imzalayıcı asla sessizce imzalanmamış bir belge üretmez.

Yayımlama sınırı

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

Ayrıca bakınız

• HSM imzalama — referans — PKCS#11 imzalayıcısı için derinlemesine referans.
• Security — NextPDF Enterprise — birleşik Enterprise güvenlik yüzeyi.
• Signature — NextPDF Enterprise — PAdES B-LT ve B-LTA uzun süreli üretici.
• FIPS 140 kriptografik politikası — FIPS modu politikası ve öz-test koruması.
• Cloud KMS signing — NextPDF Pro — AWS, Azure ve GCP anahtar-yönetim-hizmeti stratejileri.
• Security / Signing (Core) — Core CMS imzalayıcısı ve imzalama-stratejisi sözleşmesi.
• HSM · PKCS#11 · CMS · ECDSA — sözlük terimleri.