KMS sağlayıcısı sözleşmesi

Bir bakışta

HsmSignerInterface, üçüncü tarafın NextPDF’e anahtar koruması sağlamak için uyguladığı genel sözleşmedir. Sağlayıcınız, özel anahtarın korumasını üstlenir. Motor, Şifreleme Mesajı Söz Dizimi (CMS) yapısını oluşturur.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

NextPDF, imza oluşturma işlemini anahtar korumasından ayırır. Motor, bayt aralığını hazırlar ve CMS SignedData yapısını bir araya getirir. Özel anahtarı tutmaz. Bunun yerine, anahtar korumasını genel bir sözleşme aracılığıyla imzalama arka ucuna devreder.

Üç genel sözleşmeden birini uygularsınız:

• SignerInterface. Temel sözleşmedir. Sağlanan veriler için bir SignatureResult döndürür, zaman damgası uygular ve uzun vadeli doğrulama desteğini bildirir. İmzalama mantığı süreç içinde çalışıyorsa bu sözleşmeyi kullanın.
• HsmSignerInterface. Anahtar koruması sözleşmesidir. Uygulama, imzalamayı donanım sınırı içinde gerçekleştirmelidir. Özel anahtar bu sınırın dışına çıkmamalıdır. Bir anahtar yönetim sistemi sağlayıcısı bu sözleşmeyi uygular.
• DeferredSignerInterface. Eşzamansız arka uçlar için SignerInterface arabiriminin uzantısıdır. Çağıran taraf veriyi gönderir, bir iş tanımlayıcısı alır ve sonucu daha sonra getirir.

Bu sayfa genel sözleşmeyi tanımlar. Dahili herhangi bir NextPDF Pro veya NextPDF Enterprise uygulamasını açıklamaz. Ücretli bir sürüm, bu sözleşmenin desteklenen bir uygulamasını sağlayabilir. Bağımlılığınız uygulamaya değil, sözleşmeyedir.

Anahtar koruması gereksinimi

Sözleşme, özel anahtarın güvenli sınırın dışına asla çıkmamasını gerektirir. Yerleşik anahtar yönetimi uygulaması bu gereksinimi destekler. National Institute of Standards and Technology (NIST) SP 800-57 Part 1 Revision 5, anahtar yönetimini güvenli üretim, depolama, dağıtım, kullanım ve imha süreçlerini kapsayan yaşam döngüsü yönetimi olarak ele alır. Public-Key Cryptography Standards #11 (PKCS#11) v3.1 bu sınırı uygulanabilir kılar. Özel anahtar nesnesinde CKA_SENSITIVE true veya CKA_EXTRACTABLE false olarak ayarlandığında, belirteç anahtar değerini belirtecin dışında düz metin olarak açığa çıkarmamalıdır.

Bu gereksinimi karşılamak uygulamanızın sorumluluğundadır. Motor bunu sizin yerinize zorlayamaz. sign() yönteminiz ham anahtar baytlarını süreç belleğine okuyabiliyorsa, sözleşmenin güvenlik özelliği ortadan kalkar.

API yüzeyi

NextPDF\Contracts\HsmSignerInterface (kararlı, 1.0.0 sürümünden beri):

Yöntem	Döndürür	Amaç
sign(string $data, string $algorithm)	string	Verileri donanım sınırı içinde imzalayın. Ham imza baytlarını döndürün. Başarısızlık durumunda RuntimeException fırlatın.
getCertificateDer()	string	İmzalayanın X.509 sertifikasını Distinguished Encoding Rules (DER) biçiminde döndürün.
getCertificateChainDer()	array<string>	İmzalayan sertifikası hariç, ara sertifikaları veren makamdan köke doğru döndürün.
getPublicKeyAlgorithm()	string	Genel anahtar algoritması tanımlayıcısını döndürün.

NextPDF\Contracts\SignerInterface (kararlı, 1.0.0 sürümünden beri):

Yöntem	Döndürür	Amaç
sign(string $data)	SignatureResult	DER kodlu CMS SignedData yapısını döndürün.
timestamp(string $signatureValue)	string	DER kodlu bir Request for Comments (RFC) 3161 zaman damgası belirteci döndürün.
supportsLtv()	bool	Uzun vadeli doğrulama (LTV) verilerinin gömülüp gömülemeyeceğini bildirin.

NextPDF\Contracts\DeferredSignerInterface (deneysel, 3.0.0 sürümünden beri), eşzamansız arka uçlar için SignerInterface arabirimini submitForSigning(), retrieveSignature() ve isComplete() yöntemleriyle genişletir.

Motorun ürettiği imza düzeyleri, PDF Advanced Electronic Signatures (PAdES) profillerini izler. European Telecommunications Standards Institute (ETSI) EN 319 142-2, EN 319 142-1’deki temel yapı taşları üzerine inşa edilen genişletilmiş PAdES profillerini tanımlar. Motor; B-B, B-T, B-LT ve B-LTA düzeylerini bu yapı taşlarına eşler. İmzalayanınız, motorun ihtiyaç duyduğu şifreleme işlemini ve sertifika malzemesini sağlar.

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

Bu en basit PKCS#11 tarzı sağlayıcı, imzalama işini belirtece devreder. PHP, anahtar değerini hiçbir zaman okumaz.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

final class TokenSigner implements HsmSignerInterface
{
    public function __construct(private readonly TokenSession $session) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        // The token computes the signature. The key stays inside the token.
        return $this->session->c_sign($data, $algorithm);
    }

    public function getCertificateDer(): string
    {
        return $this->session->readCertificate();
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->session->readChain();
    }

    public function getPublicKeyAlgorithm(): string
    {
        return 'rsaEncryption';
    }
}

Kod örneği — Üretim

Üretim ortamındaki bir sağlayıcı girdileri doğrular, belirteç hatasında güvenli biçimde kapanır ve anahtar veya imza malzemesini hiçbir zaman günlüğe kaydetmez.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;
use Psr\Log\LoggerInterface;
use RuntimeException;

final class KmsSigner implements HsmSignerInterface
{
    public function __construct(
        private readonly RemoteKmsClient $kms,
        private readonly string $keyId,
        private readonly LoggerInterface $logger,
    ) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        if ($data === '') {
            throw new RuntimeException('Refusing to sign empty data');
        }

        try {
            // The KMS performs the operation. The key never reaches this process.
            return $this->kms->sign($this->keyId, $data, $algorithm);
        } catch (\Throwable $error) {
            // Fail closed. Do not log key material or signature bytes.
            $this->logger->error('kms.sign.failed', ['key' => $this->keyId]);

            throw new RuntimeException('KMS signing failed', previous: $error);
        }
    }

    public function getCertificateDer(): string
    {
        return $this->kms->certificate($this->keyId);
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->kms->chain($this->keyId);
    }

    public function getPublicKeyAlgorithm(): string
    {
        return $this->kms->algorithm($this->keyId);
    }
}

Uç durumlar ve dikkat edilecekler

• İmza bayt biçimi. Ham imza baytlarını döndürün. Rivest-Shamir-Adleman (RSA) için baytlar DER’dir. Elliptic Curve Digital Signature Algorithm (ECDSA) için baytlar, ham r değerinden ve ardından gelen s değerinden oluşur.
• Zincir sırası. getCertificateChainDer() imzalayan sertifikasını hariç tutar. Ara sertifikaları veren makamdan köke doğru sıralayın.
• Algoritma tanımlayıcıları. sign() OpenSSL tarzı tanımlayıcılar kullanır. getPublicKeyAlgorithm() X.509 algoritma adını döndürür.
• Başarısızlıkta güvenli kapanma. Herhangi bir belirteç veya KMS hatasında RuntimeException fırlatın. Kısmi veya boş bir imza döndürmeyin.
• Anahtar imhası. Bir anahtar şifreleme döneminin sonuna ulaştığında, anahtarı anahtar yönetim prosedürünüze göre imha edin. NIST SP 800-57 Part 1 Revision 5 §8.2.1.2, bir anahtarın artık gerekli olmadığı anda imha edilmesi gerektiğini belirtir. İmha işlemi §8.3.4 hükmünü izler.

Veri yerleşimi ve PII azaltma önlemleri

Sözleşme yalnızca imzalanacak verileri ve sertifika malzemesini aktarır. Belge içeriğini veya kişisel verileri imzalama arka ucuna aktarmaz. Bayt aralığını en aza indirin. İmzalama nedeni veya konum alanlarına kişisel veri yerleştirmeyin. Bu alanlar imzalı dosyada görünür kalır.

Güvenli telemetri ve günlük temizleme

Hiçbir zaman sign() yöntemine geçirilen verileri, döndürülen imza baytlarını, anahtar tanımlayıcısını kurtarılabilir bir biçimde veya sertifikaya ait herhangi bir özel bileşeni günlüğe kaydetmeyin. Yalnızca işlem sonucunu ve geri döndürülemez bir referansı günlüğe kaydedin. Desteklenen denetim çapası, SignatureAppliedEvent kancasıdır. Eylem tetikleyicileri bölümüne bakın.

Tehdit modeli

Varlık	Tehdit	Azaltma önlemi
Özel anahtar	Süreç belleğine sızma	Sözleşme, sınır içinde imzalamayı gerektirir; PKCS#11 CKA_SENSITIVE / CKA_EXTRACTABLE ile çıkarılamazlığı zorunlu kılar
İmzalama oracle’ı	Sınırsız imzalama istekleri	Uygulama, çağıranları hız sınırlamasına tabi tutar ve kimliklerini doğrular
Sertifika zinciri	Değiştirme	Uygulama, güvenilir köke uzanan bir zincir döndürür
İmza baytları	Günlükler aracılığıyla ifşa	Güvenli biçimde kapanan hata yolu; telemetride imza malzemesi yok
Şifreleme dönemini geçmiş anahtar	Sürekli kullanım	NIST SP 800-57 Part 1 Revision 5 §8.2.1.2 uyarınca anahtar imhası

Uygunluk

İmza düzeyleri PAdES profillerine uygundur. ETSI EN 319 142-2 §5.1, EN 319 142-1 temel yapı taşları üzerinde genişletilmiş PAdES profillerini tanımlar. Motor, bu yapı taşlarını imzalayanınızın sağladığı malzemeden bir araya getirir. Anahtar yönetimi, §8.2.1.2 imha gereksinimi dahil olmak üzere NIST SP 800-57 Part 1 Revision 5 yaşam döngüsüyle uyumludur. Donanım anahtar koruması, PKCS#11 v3.1 çıkarılamaz anahtar öznitelikleriyle uyumludur. Atıflar sayfa ön bilgisinde kayıtlıdır.

İhracat kontrolü ve inceleme yönetişimi

Bu sayfa PKCS#11 ve donanım güvenlik modülü (HSM) anahtar korumasını kapsar; bu nedenle ön bilgisinde export_control_class: legal-review-required ayarlanır. Dokümantasyon inceleme politikası uyarınca (plan §17 kapı 6), güvenlik modu, yolu veya PAdES, FIPS, HSM ya da PKCS#11 ile eşleşen içeriği olan herhangi bir sayfa, yayımlanabilmeden önce @nextpdf-labs/crypto-reviewers GitHub ekibinin onayını gerektirir. Bu CODEOWNERS onayı, kesin bir birleştirme kapısıdır: sayfa publish: false olarak kalır; bu durum hem yasal ihracat kontrolü incelemesi hem de @nextpdf-labs/crypto-reviewers incelemesi tamamlanana kadar sürer.

Ticari bağlam

NextPDF Enterprise, anahtar yönetim sistemi koruması, sertifika zinciri derlemesi ve denetim entegrasyonu ile bu sözleşmenin desteklenen bir uygulamasını sağlar. HsmSignerInterface arabirimini Core içinde kendiniz uygulayabilir veya Enterprise uygulamasını kod değişikliği olmadan aynı genel sözleşme aracılığıyla kullanabilirsiniz.

Ayrıca bakınız

• Uzantı geliştirme genel bakışı
• SPI kararlılık kuralları
• Eylem tetikleyicileri ve olay dinleyicileri

İlgili sözleşmeler ve modüller

• İmzalama sözleşmeleri referansı — SignerInterface, HsmSignerInterface, DeferredSignerInterface ve zaman damgası sağlayıcısı.
• Güvenlik politikası sözleşmesi referansı — güvenlik açısından hassas kardeş Service Provider Interface (SPI) yüzeyi.
• SPI kararlılık kuralları — stable imzalama sözleşmelerinin arkasındaki arabirim taahhüdü.
• Eylem tetikleyicileri ve olay dinleyicileri — desteklenen denetim çapası olan SignatureAppliedEvent.
• Uzantı geliştirme genel bakışı — eksiksiz genel SPI yüzeyi.

Sözlük, anahtar yönetim sistemi, şifreleme dönemi ve HSM terimlerini tanımlar; her birinin standart tanımı için yayımlanan sözlüğe bakın.