Penandatanganan Cloud KMS (AWS KMS, Azure Key Vault, GCP KMS)

Sekilas pandang

NextPDF Pro menandatangani PDF dengan kunci yang disimpan di layanan manajemen kunci cloud (KMS). Penyedia yang didukung adalah Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault, dan Google Cloud Platform (GCP) Cloud KMS. Setiap penyedia mengimplementasikan satu kontrak penandatanganan, sehingga aplikasi Anda bergantung pada kontrak tersebut, bukan pada kelas penyedia. Hanya digest atribut-tertanda yang dikirim ke penyedia; dokumen tidak pernah meninggalkan host Anda untuk operasi penandatanganan. Halaman ini berada di tingkat perilaku: halaman ini menyatakan apa yang dikirim dan diterima setiap penyedia, bagaimana versi kunci diselesaikan, dan di mana kustodi kunci berhenti menjadi tanggung jawab NextPDF.

Kontrak ini memperluas kontrak penanda tangan perangkat-keras-dan-cloud Core, sehingga strategi cloud-KMS terhubung ke jalur penandatanganan yang sama dengan yang digunakan penanda tangan Core.

Prasyarat dinyatakan dalam front matter dan diulang pada Prasyarat.

Edisi dan pelisensian

Strategi penandatanganan cloud-KMS dikirimkan dalam paket nextpdf/pro dan digerbang oleh flag fitur lisensi pro. NextPDF Core mengirimkan penanda tangan CMS perangkat lunak; NextPDF Enterprise menambahkan kustodi kunci perangkat keras melalui PKCS#11. Penandatanganan cloud-KMS adalah kapabilitas Pro dan juga dapat dijangkau di Enterprise, karena Enterprise bergantung pada Pro. Penerapan tanpa hak Pro yang aktif tidak memuat kelas-kelas strategi ini; kontrak penandatanganan Core terus berfungsi tanpa perubahan. Bandingkan edisi.

Yang dilakukan kapabilitas ini

Setiap penanda tangan cloud-KMS mengimplementasikan satu kontrak penyedia yang memperluas kontrak penanda tangan Core. Kontrak ini menambahkan tiga hal: pengenal penyedia yang stabil untuk pencarian registry, metode penandatanganan yang sadar versi-kunci, dan deskripsi-diri algoritma yang didukung penyedia sehingga orkestrator dapat memilih penyedia yang kompatibel sebelum penandatanganan.

Alur penandatanganan menjaga dokumen tetap di host Anda:

1. Sesi penandatanganan Pro menghitung digest dokumen dan membangun atribut-tertanda CMS.
2. Sesi melakukan hash terhadap atribut-tertanda dan mengirim hanya digest tersebut ke penyedia. Layanan penandatanganan eksternal yang menerima message-digest yang disuplai pemanggil dan mengembalikan tanda tangan adalah pola yang telah mapan untuk menjaga dokumen tetap berada di dalam batas Anda, sebagaimana dijelaskan dalam kerangka acuan EU Digital Signature Service (DSS).
3. Penyedia menandatangani digest dengan versi kunci yang diselesaikannya dan mengembalikan tanda tangan mentah.
4. Sesi merakit CMS SignedData dan menyematkannya dalam PDF.

Penyedia diimplementasikan di atas panggilan Hypertext Transfer Protocol (HTTP) PSR-18 murni — tanpa dependensi software development kit (SDK) vendor cloud. Autentikasi didelegasikan ke aplikasi Anda: Anda menyuplai bearer token (AWS, GCP) atau token atau kredensial service-principal (Azure). Setiap penyedia menormalkan keluarannya untuk CMS: AWS dan GCP mengembalikan tanda tangan Rivest–Shamir–Adleman (RSA) dalam bentuk DER yang siap untuk CMS; tanda tangan Elliptic Curve Digital Signature Algorithm (ECDSA) yang dikembalikan penyedia sebagai pasangan integer mentah (Azure) dikonversi ke bentuk ber-encoding DER, sedangkan GCP mengembalikan ECDSA yang sudah ber-encoding DER. Kurva ECDSA dan digest dipasangkan secara konvensional — P-256 dengan SHA-256, P-384 dengan SHA-384, P-521 dengan SHA-512 — sesuai pemasangan yang direkomendasikan dalam RFC 5480.

Registry PSR-11 menyelesaikan penyedia berdasarkan pengenal dan mendukung pabrik lazy. Pelanggan self-host Enterprise mendaftarkan driver HSM atau KMS proprietary dengan mengimplementasikan kontrak penyedia dan mengikatnya di registry — tanpa fork NextPDF Pro.

Semantik versi-kunci per-penyedia

Penyedia memaparkan primitif “active version” yang berbeda, sehingga perilaku versi-kunci baku berbeda:

• AWS KMS — versi kunci null menggunakan alias kunci, yang AWS selesaikan menjadi versi kunci saat ini di sisi penyedia.
• Azure Key Vault — versi kunci null menggunakan URL kunci tanpa versi, yang Azure selesaikan menjadi versi terbaru yang diaktifkan. Penggantian eksplisit harus berupa pengenal heksadesimal 32 karakter; nilai lain mana pun ditolak untuk mencegah injeksi segmen-URL.
• GCP Cloud KMS — endpoint asymmetric-sign beroperasi hanya pada versi crypto-key tertentu; tidak ada “active version” di sisi server. Anda harus menyematkan versi dalam konfigurasi atau memberikannya secara eksplisit. Tanpa keduanya disetel, penanda tangan memunculkan galat manajemen-kunci alih-alih menebak.

Dokumentasikan mode mana yang digunakan penerapan Anda agar perilakunya deterministik.

Prasyarat

1. Pasang NextPDF Core dan paket Pro, serta miliki lisensi Pro yang aktif.
2. Sediakan kunci penandatanganan di penyedia pilihan Anda dan catat pengenalnya (alias kunci atau Amazon Resource Name untuk AWS; vault dan nama kunci untuk Azure; project, location, key ring, crypto key, dan version untuk GCP).
3. Sediakan klien HTTP PSR-18 serta pabrik request dan stream PSR-17.
4. Peroleh kredensial penyedia di aplikasi Anda: bearer token untuk AWS atau GCP, atau token yang sudah diperoleh sebelumnya atau kredensial service-principal untuk Azure. Akuisisi token adalah tanggung jawab aplikasi Anda; suplai rahasia dari secret manager Anda, jangan pernah dari kode sumber.

Konfigurasi

Setiap penyedia memiliki objek konfigurasi imutabel yang dibangun dari pengenal dan kredensial Anda. Hal-hal konfigurasi yang umum:

• Pengenal penyedia — aws-kms, azure-keyvault, atau gcp-kms, digunakan sebagai kunci pencarian registry.
• Algoritma — dipilih per panggilan dari nama algoritma yang dilewatkan sesi penandatanganan Anda; penyedia menolak algoritma yang tidak didukungnya.
• Versi kunci — disematkan dalam konfigurasi atau dilewatkan per panggilan, dengan semantik per-penyedia yang dijelaskan di atas.
• Kredensial — bearer token atau kredensial service-principal yang disuplai aplikasi Anda dari secret manager-nya.

Langkah demi langkah

1. Bangun konfigurasi penyedia dari pengenal Anda dan kredensial yang dibaca dari secret manager Anda.
2. Konstruksi penanda tangan penyedia dengan konfigurasi, sertifikat penanda tangan dalam bentuk DER, rantai sertifikat, klien PSR-18, dan pabrik PSR-17.
3. Opsional, daftarkan penyedia di registry PSR-11 dengan pengenalnya sehingga orkestrator menyelesaikannya berdasarkan nama.
4. Jalankan sesi penandatanganan Pro: ia menghitung digest, membangun atribut-tertanda, dan memanggil penyedia hanya dengan digest.
5. Tangkap kegagalan yang paling spesifik — key-management, unsupported-algorithm, atau signature-failed — catat pesan struktural tanpa rahasia, lalu lempar ulang.

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;
        }
    }
}

Verifikasi

1. Pastikan penyedia mendeskripsikan-diri algoritma yang ingin Anda gunakan sebelum penandatanganan, sehingga algoritma yang tidak didukung tertangkap saat pemilihan alih-alih saat panggilan penyedia.
2. Pastikan hanya digest yang ditransmisikan: byte dokumen tidak boleh muncul di body permintaan penyedia. Permintaan membawa digest ber-encoding base64, bukan berkasnya.
3. Untuk ECDSA, pastikan tanda tangan yang disematkan ber-encoding DER — penanda tangan mengonversi tanda tangan pasangan-integer mentah untuk Anda.
4. Buka PDF yang sudah ditandatangani di validator yang dikonfigurasi dengan trust anchor Anda dan pastikan tanda tangan dilaporkan utuh secara kriptografis. Tanda tangan yang dihasilkan bukanlah tanda tangan yang terverifikasi; keputusan kepercayaan adalah milik verifikator.
5. Pastikan tidak ada token, kredensial, atau material kunci yang muncul di log aplikasi Anda.

Keamanan dan kepatuhan

• Kunci tetap berada di penyedia. Strategi cloud-KMS adalah titik integrasi, bukan penyimpan kunci. NextPDF Pro tidak menyimpan kunci privat untuk strategi KMS.
• Hanya digest yang melintasi batas. Sesi mengirim digest atribut-tertanda ke penyedia, bukan dokumen — pola message-digest-input yang dijelaskan dalam kerangka acuan EU DSS.
• Byte range dihitung oleh mesin. Byte range tidak pernah diterima dari pemanggil.
• Fail-closed. Kegagalan penyedia, jaringan, versi-kunci, atau algoritma-tak-didukung memunculkan eksepsi bertipe. Sesi tidak diam-diam menghasilkan dokumen yang tidak ditandatangani dan tidak pernah mengganti dengan algoritma yang lebih lemah.
• Kredensial adalah rahasia. Token dan kredensial service-principal berasal dari secret manager Anda dan dikecualikan dari log.

Halaman ini berkaitan dengan penandatanganan kriptografis. Setiap sumber normatif diparafrasakan; tidak ada teks normatif yang direproduksi. ### Batas kustodi kunci

Perlindungan kunci bergantung pada penanganan kunci, KMS yang dikonfigurasi, dan penerapan. NextPDF Pro menyediakan integrasi KMS, bukan penyimpan kunci. NextPDF Pro kompatibel dengan FIPS hanya ketika dikonfigurasi terhadap KMS atau HSM tervalidasi FIPS; ia bukan modul kriptografi tervalidasi FIPS dan tidak membuat klaim sertifikasi FIPS apa pun.

Penanganan kegagalan

• Versi kunci tidak dikenal atau dinonaktifkan. Penyedia memetakan respons not-found atau versi-dinonaktifkan ke eksepsi manajemen-kunci yang menyebutkan penyedia dan kunci.
• GCP tanpa versi yang disematkan. Penanda tangan GCP memunculkan galat manajemen-kunci ketika baik konfigurasi maupun panggilan tidak menyuplai versi, karena endpoint asymmetric-sign hanya beroperasi pada versi tertentu.
• Algoritma tidak didukung. Meminta algoritma yang tidak didukung penyedia memunculkan eksepsi algoritma-tak-didukung sebelum panggilan jaringan apa pun.
• Kegagalan transport. Galat klien PSR-18 dipetakan ke eksepsi signature-failed; sesi tidak menghasilkan hasil parsial.
• Kredensial hilang. Penanda tangan tanpa token dan tanpa kredensial service-principal memunculkan galat bertipe alih-alih memanggil penyedia tanpa autentikasi.

Lihat juga

• Security — NextPDF Pro — penyamaran, deteksi PII, dan keseluruhan permukaan penandatanganan Pro.
• HSM signing — NextPDF Enterprise — kustodi kunci perangkat keras PKCS#11.
• Signature — NextPDF Enterprise — produser jangka-panjang PAdES B-LT dan B-LTA.
• Security / Signing (Core) — penanda tangan CMS Core dan kontrak strategi-penandatanganan.
• KMS · CMS · ECDSA · HSM — istilah glosarium.