Bulut KMS imzalama (AWS KMS, Azure Key Vault, GCP KMS)

Bir bakışta

NextPDF Pro, bir PDF’i bir bulut anahtar yönetimi hizmetinde (KMS) tutulan bir anahtarla imzalar. Desteklenen sağlayıcılar Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault ve Google Cloud Platform (GCP) Cloud KMS’tir. Her sağlayıcı tek bir imzalama sözleşmesini uygular; böylece uygulamanız bir sağlayıcı sınıfına değil, sözleşmeye bağımlı olur. Sağlayıcıya yalnızca imzalanmış öznitelik özeti gönderilir; belge, imzalama işlemi için ana makinenizden asla ayrılmaz. Bu sayfa davranış düzeyindedir: her sağlayıcının ne gönderip ne aldığını, anahtar sürümlerinin nasıl çözümlendiğini ve anahtar muhafazasının NextPDF’in sorumluluğu olmaktan nerede çıktığını belirtir.

Sözleşme, Core’un donanım ve bulut imzalayıcı sözleşmesini genişletir; böylece bir bulut KMS stratejisi, Core imzalayıcısının kullandığı aynı imzalama yoluna takılır.

Ön koşullar ön bilgide belirtilir ve Ön koşullar bölümünde yinelenir.

Sürüm ve lisanslama

Bulut KMS imzalama stratejileri nextpdf/pro paketinde sunulur ve pro lisans özellik bayrağıyla kapılanır. NextPDF Core bir yazılım CMS imzalayıcısı sunar; NextPDF Enterprise, PKCS#11 üzerinden donanım anahtar muhafazası ekler. Bulut KMS imzalama bir Pro yeteneğidir ve Enterprise, Pro’ya bağımlı olduğundan Enterprise’da da erişilebilir. Etkin bir Pro hakkı olmayan bir dağıtım, bu strateji sınıflarını yüklemez; Core imzalama sözleşmesi değişmeden çalışmaya devam eder. Sürümleri karşılaştırın.

Bu yetenek ne yapar

Her bulut KMS imzalayıcısı, Core imzalayıcı sözleşmesini genişleten tek bir sağlayıcı sözleşmesini uygular. Sözleşme üç şey ekler: kayıt defteri araması için kararlı bir sağlayıcı tanımlayıcısı, anahtar sürümünden haberdar bir imzalama yöntemi ve bir sağlayıcının desteklediği algoritmaların kendini tanımlaması; böylece düzenleyici, imzalamadan önce uyumlu bir sağlayıcı seçebilir.

İmzalama akışı belgeyi ana makinenizde tutar:

1. Pro imzalama oturumu, belge özetini hesaplar ve CMS imzalanmış özniteliklerini oluşturur.
2. Oturum, imzalanmış öznitelikleri özetler ve sağlayıcıya yalnızca bu özeti gönderir. Çağıran tarafından sağlanan bir ileti özetini kabul eden ve imzayı döndüren harici bir imzalama hizmeti, belgeyi sınırınızın içinde tutmanın yerleşik yöntemidir; bu, EU Digital Signature Service (DSS) referans çerçevesinde açıklanmıştır.
3. Sağlayıcı, özeti çözümlediği anahtar sürümüyle imzalar ve ham imzayı döndürür.
4. Oturum, CMS SignedData’yı bir araya getirir ve PDF’e gömer.

Sağlayıcılar saf PSR-18 Hypertext Transfer Protocol (HTTP) çağrıları üzerinden uygulanır — herhangi bir bulut satıcısı yazılım geliştirme kiti (SDK) bağımlılığı yoktur. Kimlik doğrulama uygulamanıza devredilir: bir taşıyıcı belirteç (AWS, GCP) ya da bir belirteç veya hizmet ilkesi kimlik bilgisi (Azure) sağlarsınız. Her sağlayıcı çıktısını CMS için normalize eder: AWS ve GCP, Rivest–Shamir–Adleman (RSA) imzalarını CMS için hazır DER biçiminde döndürür; bir sağlayıcının ham tamsayı çifti olarak döndürdüğü bir Elliptic Curve Digital Signature Algorithm (ECDSA) imzası (Azure) DER kodlu biçime dönüştürülürken, GCP ECDSA’yı zaten DER kodlu döndürür. ECDSA eğrisi ve özeti geleneksel olarak eşlenir — P-256 ile SHA-256, P-384 ile SHA-384, P-521 ile SHA-512 — RFC 5480’deki önerilen eşleşmeye göre.

Bir PSR-11 kayıt defteri, sağlayıcıları tanımlayıcıya göre çözümler ve geç bağlanan fabrikaları destekler. Enterprise kendi kendine barındıran müşteriler, sağlayıcı sözleşmesini uygulayıp kayıt defterinde bağlayarak — NextPDF Pro’yu çatallamadan — özel bir HSM veya KMS sürücüsü kaydeder.

Sağlayıcı başına anahtar sürümü semantiği

Sağlayıcılar farklı “etkin sürüm” temel öğeleri sunar; bu nedenle varsayılan anahtar sürümü davranışı farklılık gösterir:

• AWS KMS — null bir anahtar sürümü, AWS’nin sağlayıcı tarafında geçerli anahtar sürümüne çözümlediği anahtar takma adını kullanır.
• Azure Key Vault — null bir anahtar sürümü, Azure’un en son etkin sürüme çözümlediği sürümsüz anahtar URL’sini kullanır. Açık bir geçersiz kılma, 32 karakterli bir onaltılık tanımlayıcı olmalıdır; başka herhangi bir değer, URL-segment enjeksiyonunu önlemek için reddedilir.
• GCP Cloud KMS — asimetrik imzalama uç noktası yalnızca belirli bir kripto anahtarı sürümü üzerinde çalışır; sunucu tarafında bir “etkin sürüm” yoktur. Yapılandırmada bir sürüm sabitlemeniz veya açıkça bir sürüm geçirmeniz gerekir. İkisi de ayarlanmadığında, imzalayıcı tahmin etmek yerine bir anahtar yönetimi hatası oluşturur.

Davranışın belirleyici olması için dağıtımınızın hangi modu kullandığını belgeleyin.

Ön koşullar

1. NextPDF Core’u ve Pro paketini yükleyin ve etkin bir Pro lisansına sahip olun.
2. Seçtiğiniz sağlayıcıda bir imzalama anahtarı sağlayın ve tanımlayıcılarını not edin (AWS için anahtar takma adı veya Amazon Resource Name; Azure için kasa ve anahtar adı; GCP için proje, konum, anahtar halkası, kripto anahtarı ve sürüm).
3. Bir PSR-18 HTTP istemcisi ve PSR-17 istek ve akış fabrikaları sağlayın.
4. Sağlayıcı kimlik bilgisini uygulamanızda edinin: AWS veya GCP için bir taşıyıcı belirteç ya da Azure için önceden edinilmiş bir belirteç veya hizmet ilkesi kimlik bilgileri. Belirteç edinimi uygulamanızın sorumluluğundadır; gizli dizileri kaynaktan değil, gizli dizi yöneticinizden sağlayın.

Yapılandırma

Her sağlayıcının, tanımlayıcılarınızdan ve kimlik bilgilerinizden oluşturulan değişmez bir yapılandırma nesnesi vardır. Ortak yapılandırma konuları:

• Sağlayıcı tanımlayıcısı — kayıt defteri arama anahtarı olarak kullanılan aws-kms, azure-keyvault veya gcp-kms.
• Algoritma — imzalama oturumunuzun geçirdiği algoritma adından çağrı başına seçilir; sağlayıcı, desteklemediği bir algoritmayı reddeder.
• Anahtar sürümü — yapılandırmada sabitlenir veya çağrı başına geçirilir; yukarıda açıklanan sağlayıcı başına semantiğe sahiptir.
• Kimlik bilgisi — uygulamanızın gizli dizi yöneticisinden sağladığı bir taşıyıcı belirteç veya hizmet ilkesi kimlik bilgileri.

Adım adım

1. Sağlayıcı yapılandırmasını, tanımlayıcılarınızdan ve gizli dizi yöneticinizden okunan bir kimlik bilgisinden oluşturun.
2. Sağlayıcı imzalayıcısını yapılandırmayla, DER biçimindeki imzalayıcı sertifikasıyla, zincirle, PSR-18 istemcisiyle ve PSR-17 fabrikalarıyla oluşturun.
3. İsteğe bağlı olarak, düzenleyicinin sağlayıcıyı ada göre çözümlemesi için sağlayıcıyı PSR-11 kayıt defterinde kendi tanımlayıcısı altında kaydedin.
4. Pro imzalama oturumunu çalıştırın: özeti hesaplar, imzalanmış öznitelikleri oluşturur ve sağlayıcıyı yalnızca özetle çağırır.
5. En özgül arızayı yakalayın — anahtar yönetimi, desteklenmeyen algoritma veya imza arızası — gizli dizi içermeyen yapısal bir mesaj günlüğe kaydedin ve yeniden fırlatın.

examples/pro/kms-provider-registry.php

<?php

declare(strict_types=1);

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

use NextPDF\Pro\Security\Signing\Kms\KeyManagementProviderRegistry;
use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;

/**
 * Register cloud-KMS providers behind one registry resolved by identifier.
 *
 * Each provider is supplied as a lazy factory so a provider is only
 * constructed when first resolved. The caller depends on the registry and
 * the provider contract, not on a concrete provider class.
 *
 * @param array<non-empty-string, callable(): KmsSignerInterface> $factories
 *        Provider factories keyed by provider identifier.
 *
 * @return KeyManagementProviderRegistry The populated registry.
 */
function buildKmsRegistry(array $factories): KeyManagementProviderRegistry
{
    $registry = new KeyManagementProviderRegistry();

    foreach ($factories as $providerId => $factory) {
        $registry->registerFactory($providerId, $factory);
    }

    return $registry;
}

examples/pro/kms-sign-guarded.php

<?php

declare(strict_types=1);

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

use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;
use NextPDF\Pro\Security\Exception\KeyManagementException;
use NextPDF\Pro\Security\Exception\SignatureFailedException;
use NextPDF\Pro\Security\Exception\UnsupportedAlgorithmException;
use Psr\Log\LoggerInterface;

final readonly class KmsSigningService
{
    public function __construct(
        private KmsSignerInterface $provider,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign a signed-attributes digest with a pinned key version.
     *
     * Only the digest is sent to the provider; the document stays on the
     * host. Each failure mode is caught as its most specific type so the
     * caller can distinguish a key-version problem from a transport failure.
     *
     * @param string      $digest     The signed-attributes digest to sign.
     * @param string      $algorithm  The OpenSSL-style algorithm name.
     * @param string|null $keyVersion The pinned key version, or null for the
     *                                 provider default (per-provider semantics).
     *
     * @throws KeyManagementException        When the key version is unknown or required and absent.
     * @throws UnsupportedAlgorithmException When the provider does not support the algorithm.
     * @throws SignatureFailedException      When the provider sign operation fails.
     *
     * @return string The raw signature bytes (DER for RSA and ECDSA per CMS rules).
     */
    public function sign(string $digest, string $algorithm, ?string $keyVersion): string
    {
        try {
            return $this->provider->signWithVersion($digest, $algorithm, $keyVersion);
        } catch (KeyManagementException | UnsupportedAlgorithmException | SignatureFailedException $e) {
            $this->logger->error('KMS signing failed', [
                'provider' => $this->provider->providerId(),
                'reason'   => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

Doğrulama

1. Desteklenmeyen bir algoritmanın sağlayıcı çağrısında değil seçim aşamasında yakalanması için, sağlayıcının kullanmayı düşündüğünüz algoritmayı imzalamadan önce kendisinin tanımladığını doğrulayın.
2. Yalnızca özetin iletildiğini doğrulayın: belge baytları sağlayıcı istek gövdesinde görünmemelidir. İstek, dosyayı değil, base64 kodlu bir özet taşır.
3. ECDSA için, gömülü imzanın DER kodlu olduğunu doğrulayın — imzalayıcı, ham tamsayı çiftli bir imzayı sizin için dönüştürür.
4. İmzalanmış PDF’i, güven çapalarınızla yapılandırılmış bir doğrulayıcıda açın ve imzanın kriptografik olarak sağlam raporlandığını doğrulayın. Üretilen bir imza, doğrulanmış bir imza değildir; güven kararı doğrulayıcıya aittir.
5. Uygulama günlüklerinizde hiçbir belirteç, kimlik bilgisi veya anahtar malzemesinin görünmediğini doğrulayın.

Güvenlik ve uyumluluk

• Anahtar sağlayıcıda kalır. Bir bulut KMS stratejisi bir tümleştirme noktasıdır, bir anahtar deposu değildir. NextPDF Pro, bir KMS stratejisi için özel anahtarı tutmaz.
• Sınırı yalnızca özet geçer. Oturum, sağlayıcıya belgeyi değil, imzalanmış öznitelik özetini gönderir — EU DSS referans çerçevesinde açıklanan ileti özeti girdisi yöntemi.
• Bayt aralığı motor tarafından hesaplanır. Çağıran taraftan asla kabul edilmez.
• Kapalı arızalama. Bir sağlayıcı, ağ, anahtar sürümü veya desteklenmeyen algoritma arızası, türlenmiş bir istisna oluşturur. Oturum, sessizce imzasız bir belge üretmez ve hiçbir zaman daha zayıf bir algoritma ile değiştirmez.
• Kimlik bilgileri gizli dizilerdir. Belirteçler ve hizmet ilkesi kimlik bilgileri gizli dizi yöneticinizden gelir ve günlüklerden hariç tutulur.

Bu sayfa kriptografik imzalama ile ilgilidir. Her normatif kaynak başka sözcüklerle ifade edilmiştir; hiçbir normatif metin yeniden üretilmemiştir. ### Anahtar muhafaza sınırı

Anahtar koruması; anahtar işlemeye, yapılandırılan KMS’ye ve dağıtıma bağlıdır. NextPDF Pro, anahtar deposunu değil, KMS tümleştirmesini sağlar. NextPDF Pro yalnızca FIPS tarafından doğrulanmış bir KMS veya HSM ile yapılandırıldığında FIPS uyumludur; kendisi FIPS tarafından doğrulanmış bir kriptografik modül değildir ve hiçbir FIPS sertifikasyon iddiasında bulunmaz.

Arıza işleme

• Bilinmeyen veya devre dışı anahtar sürümü. Sağlayıcı, bulunamayan veya devre dışı sürüm yanıtını, sağlayıcıyı ve anahtarı adlandıran bir anahtar yönetimi istisnasına eşler.
• Sabitlenmiş sürüm olmadan GCP. Asimetrik imzalama uç noktası yalnızca belirli bir sürüm üzerinde çalıştığından, ne yapılandırma ne de çağrı bir sürüm sağladığında GCP imzalayıcısı bir anahtar yönetimi hatası oluşturur.
• Desteklenmeyen algoritma. Sağlayıcının desteklemediği bir algoritmayı istemek, herhangi bir ağ çağrısından önce bir desteklenmeyen algoritma istisnası oluşturur.
• Aktarım arızası. Bir PSR-18 istemci hatası, bir imza arızası istisnasına eşlenir; oturum, kısmi bir sonuç üretmez.
• Eksik kimlik bilgisi. Belirteci ve hizmet ilkesi kimlik bilgileri olmayan bir imzalayıcı, sağlayıcıyı kimliği doğrulanmadan çağırmak yerine türlenmiş bir hata oluşturur.

Ayrıca bkz.

• Güvenlik — NextPDF Pro — maskeleme, PII algılama ve tüm Pro imzalama yüzeyi.
• HSM imzalama — NextPDF Enterprise — PKCS#11 donanım anahtar muhafazası.
• İmza — NextPDF Enterprise — PAdES B-LT ve B-LTA uzun vadeli üreticisi.
• Güvenlik / İmzalama (Core) — Core CMS imzalayıcısı ve imzalama stratejisi sözleşmesi.
• KMS · CMS · ECDSA · HSM — sözlük terimleri.