Cloud KMS imzalama — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Pro cloud-KMS imzalama yüzeyinin sözleşme düzeyindeki referansıdır. Yüzey, bir Service Provider Interface olan NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface’ten ve üç sağlayıcı imzalayıcısından oluşur: AwsKmsSigner, AzureKeyVaultSigner ve GcpKmsSigner. İki adaptör, AwsKmsSigningStrategy ve AzureKeyVaultSigningStrategy, bir imzalayıcıyı Pro SigningStrategy sözleşmesine bağlar. Her imzalayıcı, sağlayıcısına PSR-18 HTTP üzerinden yalnızca bir mesaj özeti gönderir. Özel anahtar ve belge sınırı asla geçmez. Bu sayfa, public API’yi, gözlemlenebilir davranış sözleşmesini ve tipli hata modlarını belirtir. Oturum orkestrasyonu (RemoteSigningSession, SequentialSigner) ve zaman damgalama (PadesBtTimestamper) kendi sayfalarında yer alır.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile gelir ve bir Pro-tier 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.

Public API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
KmsSignerInterface	—	Core HsmSignerInterface sözleşmesini genişletir	—	—	KMS ve HSM sürücüleri için SPI; ayrılmış yerleşik id’ler: aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli
KmsSignerInterface::providerId()	yok	Kararlı registry arama anahtarı	non-empty-string	—	Üçüncü taraf sürücüler tanımlayıcılarını namespace’lemelidir
KmsSignerInterface::signWithVersion()	$data, $algorithm = 'sha256WithRSAEncryption', $keyVersion = null	null anahtar sürümü sağlayıcı varsayılanına geri döner	string imza oktetleri: RSA sağlayıcının döndürdüğü şekliyle (doğrudan SignerInfo.signature içine yerleştirilir), ECDSA ise CMS kurallarına göre DER ECDSA-Sig-Value olarak	KeyManagementException, UnsupportedAlgorithmException, SignatureFailedException	Sağlayıcı başına null anlambilimi farklıdır; davranış sözleşmesine bakın
KmsSignerInterface::supportsAlgorithm()	string $algorithm	Yetenek yoklaması; I/O yapmaz	bool	—	Sağlayıcı seçiminden önce çağrılır
KmsSignerInterface::supportedAlgorithms()	yok	Sağlayıcının kabul ettiği OpenSSL tarzı adları listeler	list<non-empty-string>	—	—
AwsKmsSigner	constructor: AwsKmsConfig, cert DER, chain DER, PSR-18 istemcisi, PSR-17 fabrikaları, PSR-3 logger	Algoritma varsayılanı KmsSigningAlgorithm::RsaPkcs1Sha256	—	metotlara bakın	final; PROVIDER_ID = 'aws-kms'
AwsKmsSigner::create()	anahtar id’si, cert DER, PSR bağımlılıkları, isteğe bağlı chain, config, logger	$config null olduğunda AwsKmsConfig::fromEnvironment($keyId) oluşturur	self	—	Standart AWS_* ortam değişkenlerini okur
AwsKmsSigner::withAlgorithm()	KmsSigningAlgorithm $algorithm	Değiştirilmiş bir klon döndürür	self	—	AWS KMS’te sağlanan anahtar türüyle eşleşmelidir
AwsKmsSigner::sign()	$data, $algorithm = 'sha256WithRSAEncryption'	signWithVersion($data, $algorithm, null)’e devreder	string	signWithVersion() ile aynı	Eski iki argümanlı Core sözleşme yolu
AzureKeyVaultSigner	constructor: AzureKeyVaultConfig, cert DER, chain DER, PSR-18 istemcisi, PSR-17 fabrikaları, PSR-3 logger	Algoritma varsayılanı AzureSigningAlgorithm::Rs256; bir config erişim token’ı bearer token’ı tohumlar	—	metotlara bakın	final; PROVIDER_ID = 'azure-keyvault'
AzureKeyVaultSigner::create()	vault adı, anahtar adı, cert DER, PSR bağımlılıkları, isteğe bağlı chain, config, logger	$config null olduğunda AzureKeyVaultConfig::fromEnvironment() oluşturur	self	—	Önceden elde edilmiş token’ı veya service-principal kimlik bilgilerini destekler
AzureKeyVaultSigner::withAlgorithm()	AzureSigningAlgorithm $algorithm	Değiştirilmiş bir klon döndürür	self	—	RSA anahtarları RS/PS değerlerini, EC anahtarları ES değerlerini kullanır
GcpKmsSigner	constructor: GcpKmsConfig, cert DER, chain DER, PSR-18 istemcisi, PSR-17 fabrikaları, PSR-3 logger	Algoritma varsayılanı GcpKmsSigningAlgorithm::RsaSignPkcs1_2048Sha256	—	metotlara bakın	final; PROVIDER_ID = 'gcp-kms', API_VERSION = 'v1'
GcpKmsSigner::create()	proje id’si, konum, key ring, crypto key, cert DER, PSR bağımlılıkları, isteğe bağlı chain, config, logger	$config null olduğunda GcpKmsConfig::fromEnvironment() oluşturur	self	—	Bearer-token edinimi çağırana devredilir
GcpKmsSigner::withAlgorithm()	GcpKmsSigningAlgorithm $algorithm	Yalnızca config-zamanı önizleme; imza zamanında çağrı başına wire adı kazanır	self	—	Anahtar boyutu sağlanan CryptoKeyVersion tarafından sabitlenir
AwsKmsSigningStrategy	constructor: AwsKmsSigner $signer	Senkron; isAsync() false döndürür	—	Sarmalanan imzalayıcının istisnalarını yayar	RemoteSigningSession::complete() için adaptör
AzureKeyVaultSigningStrategy	constructor: AzureKeyVaultSigner $signer	Senkron; isAsync() false döndürür	—	Sarmalanan imzalayıcının istisnalarını yayar	RemoteSigningSession::complete() için adaptör
KmsSigningAlgorithm	enum, 9 durum (RSA PKCS#1, RSA-PSS, ECDSA; SHA-256/384/512)	—	AWS KMS SigningAlgorithm wire değerleri	fromOpenSslName()’den InvalidArgumentException	resolveForWireName() yapılandırılmış PSS özetini korur
AzureSigningAlgorithm	enum, 9 durum (RS256…ES512)	—	Azure Key Vault JWA tarzı değerler	fromOpenSslName()’den InvalidArgumentException	isEcdsa() çıktısı DER dönüşümü gerektiren değerleri işaretler
GcpKmsSigningAlgorithm	enum, 10 durum (EC P-256/P-384, RSA PKCS#1, RSA-PSS)	—	GCP CryptoKeyVersion algoritma değerleri	fromOpenSslName()’den UnsupportedAlgorithmException	Wire-adı çözümlemesi eşleşen en küçük anahtar boyutunu seçer

Giriş noktası imzaları

public function providerId(): string;

public function signWithVersion(
    string $data,
    string $algorithm = 'sha256WithRSAEncryption',
    ?string $keyVersion = null,
): string;

public function supportsAlgorithm(string $algorithm): bool;

public function supportedAlgorithms(): array;

public static function create(
    string $keyId,
    string $certDer,
    ClientInterface $httpClient,
    RequestFactoryInterface $requestFactory,
    StreamFactoryInterface $streamFactory,
    array $chainDer = [],
    ?AwsKmsConfig $config = null,
    ?LoggerInterface $logger = null,
): self

public function withAlgorithm(KmsSigningAlgorithm $algorithm): self

public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string

public static function create(
    string $vaultName,
    string $keyName,
    string $certDer,
    ClientInterface $httpClient,
    RequestFactoryInterface $requestFactory,
    StreamFactoryInterface $streamFactory,
    array $chainDer = [],
    ?AzureKeyVaultConfig $config = null,
    ?LoggerInterface $logger = null,
): self

public function withAlgorithm(AzureSigningAlgorithm $algorithm): self

public static function create(
    string $projectId,
    string $location,
    string $keyRing,
    string $cryptoKey,
    string $certDer,
    ClientInterface $httpClient,
    RequestFactoryInterface $requestFactory,
    StreamFactoryInterface $streamFactory,
    array $chainDer = [],
    ?GcpKmsConfig $config = null,
    ?LoggerInterface $logger = null,
): self

public function withAlgorithm(GcpKmsSigningAlgorithm $algorithm): self

public function __construct(
    private AwsKmsSigner $signer,
) {}

public function sign(string $signedAttributesDer): string

public function __construct(
    private AzureKeyVaultSigner $signer,
) {}

public function sign(string $signedAttributesDer): string

Davranış sözleşmesi

Sözleşme çözümlemesi

KmsSignerInterface, Core HsmSignerInterface sözleşmesini genişletir. providerId(), anahtar sürümü farkında signWithVersion() ve supportsAlgorithm() ile supportedAlgorithms() yetenek yoklamalarını ekler. Miras alınan iki argümanlı sign(), üç imzalayıcının tümünde null anahtar sürümüyle signWithVersion()’e devreder. getCertificateDer(), getCertificateChainDer() ve getPublicKeyAlgorithm(), constructor tarafından sağlanan materyalden uygulanır. Yetenek yoklamaları I/O yapmaz. Her imzalayıcı ayrıca inceleme için getSigningAlgorithm() ve getConfig() erişimcilerini sunar.

Yalnızca-özet iletimi

Her imzalayıcı, $data’yı çözümlenen algoritmanın özetiyle yerel olarak hash’ler ve yalnızca o özeti iletir. AWS, MessageType: DIGEST ile bir base64 özet alır. Azure, sign istek gövdesinde bir base64url özet alır. GCP, algoritmaya özgü özet alanında bir base64 özet alır. Belge baytları bir sağlayıcı isteğinde asla görünmez. Tüm taşıma, sağlayıcının HTTPS uç noktası üzerinden standart bir PSR-18 HTTP istemcisi kullanır; hiçbir cloud vendor SDK’sı dahil değildir.

Anahtar sürümü çözümlemesi

signWithVersion(), herhangi bir istek oluşturulmadan önce anahtar sürümü argümanını fail-closed doğrular. Sağlayıcı grameriyle başarısız olan bir değer KeyManagementException fırlatır ve URL-segment veya KeyId enjeksiyonunu önler.

Sağlayıcı	null anahtar sürümü	Boş dize	Geçersiz kılma grameri
AwsKmsSigner	AwsKmsConfig::$keyId kullanır; bir alias veya ARN sağlayıcı tarafında geçerli anahtara çözümlenir	Reddedilir	UUID (tireli veya tiresiz), alias/<name> veya bir KMS key/alias ARN’si
AzureKeyVaultSigner	Yapılandırılmış anahtar sürümünü kullanır; boş bir config değeri sunucu tarafında en son etkin sürümü seçer	Reddedilir	32 karakterlik onaltılık tanımlayıcı
GcpKmsSigner	GcpKmsConfig içinde sabitlenen sürümü kullanır; hiçbiri sabitlenmemişse KeyManagementException fırlatır	Reddedilir	Ondalık CryptoKeyVersion id’si, yalnızca rakamlar

GCP’nin sunucu tarafında bir “aktif sürüm” ilkeli yoktur. Asimetrik-sign uç noktası yalnızca belirli bir cryptoKeyVersions/{n} kaynağı üzerinde çalışır, bu nedenle bir sürüm her zaman çözümlenebilir olmalıdır.

Algoritma çözümlemesi

Strateji katmanı bir OpenSSL tarzı wire adı iletir. AWS ve Azure yedi wire adı kabul eder (SHA-256/384/512’de PKCS#1 ve ECDSA, ayrıca RSASSA-PSS). GCP beş kabul eder (sha256WithRSAEncryption, sha512WithRSAEncryption, RSASSA-PSS, ecdsa-with-SHA256, ecdsa-with-SHA384). RSASSA-PSS wire adı bir özet kodlamaz, bu nedenle özet-belirsizdir. AwsKmsSigner bunu, yapılandırılmış PSS varyantının özetini koruyan KmsSigningAlgorithm::resolveForWireName() aracılığıyla çözümler. AzureKeyVaultSigner belirsiz ad için yapılandırılmış PSS varyantına güvenir. Çözümlenen bir PSS özeti yapılandırılmış olandan sapacaksa UnsupportedAlgorithmException fırlatır. GcpKmsSigner her çağrıda enum’u wire adından yeniden çözümler; GCP’de withAlgorithm() bir config-zamanı önizlemedir ve imza-zamanı davranışını değiştirmez. Desteklenmeyen bir wire adı, herhangi bir ağ çağrısından önce UnsupportedAlgorithmException fırlatır. AwsKmsSigner ve GcpKmsSigner’da, bir sign çağrısı getSigningAlgorithm() tarafından daha sonra raporlanan değeri çözümlenen çağrı başına algoritmaya günceller. AzureKeyVaultSigner’da çözümleme çağrı-yereldir ve yapılandırılmış değer yetkili kalır.

İmza normalleştirme

AWS ve GCP, imzaları CMS’in tükettiği biçimde döndürür: RSA imza oktetleri değişmeden SignerInfo.signature içine gider ve ECDSA DER kodlanmış olarak ulaşır. Azure, ECDSA’yı ham IEEE P1363 (r||s) formunda döndürür; imzalayıcı bunu döndürmeden önce bir DER ECDSA-Sig-Value’ya dönüştürür.

CMS entegrasyonu ve bitişiklik

Bir SigningStrategy adaptörü, oturum tarafından sağlanan DER kodlu signed attributes’ı imzalar. Signed attributes mevcut olduğunda, CMS imza girişi SignedAttrs değerinin tam DER kodlamasının özetidir — RFC 5652 §5.4. Adaptörün getSignatureAlgorithmOid() ve getDigestAlgorithm() metotları SignerInfo signatureAlgorithm ve digestAlgorithm alanlarını besler — RFC 5652 §5.3. Döndürülen baytlar SignerInfo imza OCTET STRING’i olur — RFC 5652 §5.5. CMS birleştirme, ByteRange işleme ve oturum yaşam döngüsü RemoteSigningSession’a aittir; çok taraflı akışlar SequentialSigner’a aittir. messageImprint’i SignerInfo imza değerini hash’leyen bir PAdES B-T imza zaman damgası — RFC 3161 Appendix A — bu imzalayıcılar tarafından değil, PadesBtTimestamper tarafından uygulanır. Üçü de Pro güvenlik derin referansında belgelenmiştir.

Uç durumlar ve hata modları

• Boş dize anahtar sürümü üç sağlayıcının tümünde reddedilir. Yapılandırılmış varsayılanı miras almak için null geçirin.
• Hatalı biçimlendirilmiş bir anahtar sürümü, herhangi bir istek oluşturulmadan önce, ihlal eden değer istisnada adlandırılarak reddedilir.
• Boş bir AwsKmsConfig::$keyId ve null anahtar sürümüne sahip AwsKmsSigner, KeyManagementException fırlatır.
• Bir anahtar yönetimi hatasını gösteren sağlayıcı yanıtları KeyManagementException’a eşlenir: AWS NotFoundException, DisabledException, KeyUnavailableException, InvalidKeyUsageException veya HTTP 404; Azure HTTP 404, KeyNotFound, KeyDisabled veya KeyNotActive; GCP HTTP 404 veya 409, NOT_FOUND, FAILED_PRECONDITION veya mesajı bir sürümü adlandıran bir HTTP 400.
• Diğer 200 olmayan sağlayıcı yanıtları AWS ve GCP’de SignatureFailedException, Azure’da AzureKeyVaultException fırlatır.
• İmzalama sırasında bir PSR-18 taşıma hatası, istemci istisnası önceki fırlatılabilir olarak korunarak SignatureFailedException’a eşlenir.
• Erişim token’ı ve service-principal kimlik bilgileri olmayan AzureKeyVaultSigner, herhangi bir vault çağrısından önce AzureKeyVaultException fırlatır. Başarısız bir Azure AD token edinimi de AzureKeyVaultException fırlatır.
• AzureKeyVaultSigner, vault adını, anahtar adını, anahtar sürümünü ve tenant id’sini istek darboğazında Azure’un yayımlanmış gramerlerine karşı doğrular. URL-yapısal karakterler taşıyan bir değer AzureKeyVaultException ile fail-closed olur.
• OAuth2 bearer token’ı olmayan GcpKmsSigner, SignatureFailedException fırlatır; token edinimi çağıranın sorumluluğundadır.
• Geçerli JSON olmayan veya imza alanından yoksun bir sağlayıcı yanıtı SignatureFailedException fırlatır (Azure: eksik bir value alanı AzureKeyVaultException fırlatır).
• base64 kod çözmede başarısız olan bir sağlayıcı imza alanı AWS ve GCP’de SignatureFailedException, Azure’da AzureKeyVaultException fırlatır.
• 3.1.0’da GcpKmsSigner için bir SigningStrategy adaptörü gelmez. GCP imzalayıcısı doğrudan KmsSignerInterface sözleşmesi aracılığıyla tüketilir.

FIPS-modu davranışı

AwsKmsConfig::withFipsEndpoint(), istekleri bölgenin kms-fips uç noktasına yönlendirir. O uç noktanın FIPS doğrulama durumu, NextPDF’in değil AWS’nin bir özelliğidir. AzureKeyVaultConfig ve GcpKmsConfig, 3.1.0’da özel bir FIPS uç noktası yardımcısı sunmaz. Özet hesaplaması, PHP hash() fonksiyonuyla süreç içinde çalışır ve kendisi doğrulanmış bir modül değildir. NextPDF Pro, FIPS-doğrulanmış bir KMS veya HSM sınırına karşı çalışabilir, ancak NextPDF FIPS-doğrulanmış bir kriptografik modül değildir ve hiçbir FIPS sertifikasyon iddiasında bulunmaz.

Uygunluk

İddia	Standart	Madde
Strateji, DER kodlu signed attributes’ı imzalar; CMS imza girişi özeti, SignedAttrs’ın tam DER kodlamasını kapsar.	RFC 5652	§5.4
SignedAttributes DER kodludur ve en azından content-type ile message-digest taşır; signatureAlgorithm imzalayıcının algoritmasını tanımlar.	RFC 5652	§5.3
Döndürülen imza baytları bir OCTET STRING olarak kodlanır ve SignerInfo imza alanında taşınır.	RFC 5652	§5.5
Bir imza zaman damgasının messageImprint’i SignerInfo imza değerini hash’ler (bitişik B-T yüzeyi, bu imzalayıcılar değil).	RFC 3161	Appendix A

Tüm maddeler açımlanmıştır; NextPDF normatif metni yeniden üretmez. Bunlar yetenek beyanlarıdır, sertifikalar değildir. NextPDF hiçbir sertifikaya sahip değildir ve hiçbir sertifika vermez. Üretilen bir imzanın doğrulanıp doğrulanmayacağı, kendi trust anchor’larına ve politikasına karşı doğrulayıcının kararıdır; imzalayıcılar imza baytları döndürür ve güvenilir bir sonuç öne sürmez. Anahtar muhafazası, anahtar koruması ve sağlayıcı tarafı algoritma doğrulaması, NextPDF’in değil yapılandırılmış KMS’in özellikleridir.

Geliştirme notları

• Pro paketi içinde kullanılabilirlik: AwsKmsSigner 1.9.0’dan beri, AzureKeyVaultSigner 2.0.0’dan beri, GcpKmsSigner ve KmsSignerInterface 2.1.0’dan beri. Hepsi nextpdf/pro 3.1.0’da günceldir.
• İmzalayıcılar yalnızca PSR-18, PSR-17 ve PSR-3’e bağımlıdır. Hiçbir AWS, Azure veya Google SDK’sı gerekli değildir veya paketlenmez.
• Uyumsuz bir sağlayıcının oturum ortasında değil seçim zamanında reddedilmesi için imzalamadan önce supportsAlgorithm()’ı yoklayın.
• Kimlik bilgisi alanları constructor ile enjekte edilir ve hassas parametreler olarak işaretlenir. Log mesajları yalnızca yapısal alanlar taşır; loglara hiçbir kimlik bilgisi, token veya belge içeriği yazılmaz.
• Düzenlemeye tabi dağıtımlarda anahtar sürümlerini açıkça sabitleyin. Alias-çözümleme (AWS) ve en-son-etkin (Azure) varsayılanları kullanışlıdır ancak rotasyonlar arasında deterministik değildir.
• Üçüncü taraf sürücüler KmsSignerInterface’i uygular ve ayrılmış yerleşik tanımlayıcılarla çakışmaları önlemek için providerId()’lerini namespace’lemelidir.

Ayrıca bakınız

• Cloud KMS imzalama (yetenek) — nasıl-yapılır sayfası: kurulum, yapılandırma ve anahtar-muhafaza sınırı.
• Güvenlik — derin referans — RemoteSigningSession, SequentialSigner, PAdES B-B/B-T yüzeyi ve SigningStrategy sözleşmesi.
• İmza — derin referans (Enterprise) — B-LT/B-LTA uzun-vadeli üretici sınırı.
• Güvenlik / İmzalama (Core) — Core CMS imzalayıcısı ve bu yüzeyin genişlettiği sözleşmeler.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen public API yüzeyini belgeler. Dahili namespace yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve ticket önekleri kapsam dışıdır.