Pro 版本

雲端 KMS 簽署（AWS KMS、Azure Key Vault、GCP KMS）

速覽

NextPDF Pro 會使用保存在雲端金鑰管理服務（KMS）中的金鑰為 PDF 簽署。支援的供應商為 Amazon Web Services（AWS）KMS、Microsoft Azure Key Vault，以及 Google Cloud Platform（GCP）Cloud KMS。每個供應商都實作同一份簽署合約，因此你的應用程式依賴的是合約，而不是某個供應商類別。只有已簽署屬性摘要會送往供應商；文件本身在簽署作業期間絕不離開你的主機。本頁從行為層級說明各供應商會送出與接收什麼、金鑰版本如何解析，以及金鑰保管在哪裡不再是 NextPDF 的責任。

該合約擴充自 Core 的硬體與雲端簽署器合約，因此雲端 KMS 策略會接到 Core 簽署器所使用的同一條簽署路徑上。

先決條件已列於 front matter，並在先決條件一節重述。

版本與授權

雲端 KMS 簽署策略隨附於 nextpdf/pro 套件，並由 pro 授權功能旗標閘控。NextPDF Core 隨附軟體 CMS 簽署器；NextPDF Enterprise 則透過 PKCS#11 加入硬體金鑰保管。雲端 KMS 簽署是 Pro 功能，且因為 Enterprise 依賴 Pro，所以在 Enterprise 中也可使用。未啟用 Pro 權益的部署不會載入這些策略類別；Core 簽署合約則維持原狀繼續運作。比較各版本。

此功能的作用

每個雲端 KMS 簽署器都實作一份擴充自 Core 簽署器合約的供應商合約。該合約加入三項東西：供註冊表查詢用的穩定供應商識別碼、一個能感知金鑰版本的簽署方法，以及供應商所支援演算法的自我描述，讓協調器能在簽署前挑選相容的供應商。

簽署流程會讓文件留在你的主機上：

Pro 簽署工作階段會計算文件摘要，並建構 CMS 已簽署屬性。
工作階段會對已簽署屬性進行雜湊，並只將該摘要送往供應商。如同 EU Digital Signature Service（DSS）參考框架所述，一個接受呼叫端提供的 message-digest 並回傳簽章的外部簽署服務，正是讓文件留在你邊界之內的既定模式。
供應商會以它所解析的金鑰版本為摘要簽署，並回傳原始簽章。
工作階段會組裝 CMS SignedData 並將其嵌入 PDF。

這些供應商以純 PSR-18 Hypertext Transfer Protocol（HTTP）呼叫實作——不依賴任何雲端供應商的 software development kit（SDK）。驗證則委派給你的應用程式：你提供 bearer token（AWS、GCP），或一個 token 或 service-principal 憑證（Azure）。每個供應商都會為 CMS 正規化其輸出：AWS 與 GCP 會回傳已是 DER 形式、可直接用於 CMS 的 Rivest–Shamir–Adleman（RSA）簽章；供應商以原始整數對形式回傳的 Elliptic Curve Digital Signature Algorithm（ECDSA）簽章（Azure）會被轉換為 DER 編碼形式，而 GCP 回傳的 ECDSA 則已是 DER 編碼。ECDSA 曲線與摘要依慣例配對——P-256 配 SHA-256、P-384 配 SHA-384、P-521 配 SHA-512——依照 RFC 5480 的建議配對。

一個 PSR-11 註冊表會依識別碼解析供應商，並支援惰性工廠。Enterprise 自架客戶只要實作供應商合約並將其綁入註冊表，即可註冊專屬的 HSM 或 KMS 驅動程式——無須 fork NextPDF Pro。

各供應商的金鑰版本語意

各供應商揭露的「有效版本」原語不同，因此預設的金鑰版本行為也不同：

AWS KMS — null 金鑰版本會使用金鑰別名，AWS 會在供應商端將其解析為當前的金鑰版本。
Azure Key Vault — null 金鑰版本會使用未帶版本的金鑰 URL，Azure 會將其解析為最新的已啟用版本。明確覆寫值必須是 32 字元的十六進位識別碼；任何其他值都會被拒絕，以防止 URL 區段注入。
GCP Cloud KMS — asymmetric-sign 端點只在特定的 crypto-key 版本上運作；不存在伺服器端的「有效版本」。你必須在組態中釘選一個版本，或明確傳入一個版本。若兩者皆未設定，簽署器會引發金鑰管理錯誤，而不是憑空猜測。

請記錄你的部署使用哪一種模式，以使行為具有確定性。

先決條件

安裝 NextPDF Core 與 Pro 套件，並持有有效的 Pro 授權。
在你選定的供應商中佈建一個簽署金鑰，並記下其識別碼（AWS 為金鑰別名或 Amazon Resource Name；Azure 為 vault 與金鑰名稱；GCP 為 project、location、key ring、crypto key 與 version）。
提供一個 PSR-18 HTTP 用戶端，以及 PSR-17 request 與 stream 工廠。
在你的應用程式中取得供應商憑證：AWS 或 GCP 用 bearer token，Azure 用預先取得的 token 或 service-principal 憑證。Token 的取得是你應用程式的責任；請從你的祕密管理員提供祕密，絕不要從原始碼提供。

組態

每個供應商都有一個由你的識別碼與憑證所建構的不可變組態物件。常見的組態考量：

供應商識別碼 — aws-kms、azure-keyvault 或 gcp-kms，作為註冊表查詢鍵。
演算法 — 依你簽署工作階段傳入的演算法名稱逐次呼叫選定；供應商會拒絕它不支援的演算法。
金鑰版本 — 在組態中釘選，或逐次呼叫傳入，並具備上述各供應商的語意。
憑證 — 由你的應用程式從其祕密管理員提供的 bearer token 或 service-principal 憑證。

逐步操作

從你的識別碼與一個自祕密管理員讀取的憑證，建構供應商組態。
以該組態、DER 形式的簽署者憑證、憑證鏈、PSR-18 用戶端與 PSR-17 工廠，建構供應商簽署器。
選擇性地將供應商以其識別碼註冊到 PSR-11 註冊表，讓協調器能依名稱解析它。
執行 Pro 簽署工作階段：它會計算摘要、建構已簽署屬性，並只以摘要呼叫供應商。
攔截最具體的失敗——金鑰管理、不支援的演算法或簽署失敗——記錄一則不含祕密的結構性訊息，並重新拋出。

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

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

驗證

在簽署前確認供應商會自我描述你打算使用的演算法，這樣不支援的演算法會在選擇時就被攔截，而不是到呼叫供應商時才被攔截。
確認只有摘要被傳輸：文件位元組絕不能出現在供應商請求主體中。請求承載的是 base64 編碼的摘要，而非檔案。
對 ECDSA 而言，確認嵌入的簽章是 DER 編碼的——簽署器會為你轉換原始整數對簽章。
在一個以你的信任錨點設定好的驗證器中開啟已簽署的 PDF，並確認簽章被回報為密碼學上完整。產生出的簽章不等於已驗證的簽章；信任決定屬於驗證器。
確認你的應用程式日誌中不會出現任何 token、憑證或金鑰素材。

安全與合規

金鑰留在供應商中。 雲端 KMS 策略是一個整合點，而非金鑰儲存區。NextPDF Pro 不為 KMS 策略保管私鑰。
只有摘要會跨越邊界。 工作階段送往供應商的是已簽署屬性摘要，而非文件——即 EU DSS 參考框架所述的 message-digest-input 模式。
位元組範圍由引擎計算。 它絕不會從呼叫端接收。
Fail-closed。 供應商、網路、金鑰版本或不支援演算法的失敗都會引發一個具型別的例外。工作階段不會默默產生未簽署的文件，也絕不會替換為較弱的演算法。
憑證即祕密。 Token 與 service-principal 憑證來自你的祕密管理員，並排除於日誌之外。

本頁涉及密碼學簽署。每一份規範性來源皆為改寫；不重製任何規範性文字。### 金鑰保管邊界

金鑰保護取決於金鑰處理方式、所設定的 KMS，以及部署環境。NextPDF Pro 提供的是 KMS 整合，而非金鑰儲存區。NextPDF Pro 只有在搭配通過 FIPS 驗證的 KMS 或 HSM 設定時才具備 FIPS 相容性；它本身並不是一個通過 FIPS 驗證的密碼學模組，也不做任何 FIPS 認證聲明。

失敗處理

未知或已停用的金鑰版本。 供應商會將找不到或版本已停用的回應，對應為一個指名供應商與金鑰的金鑰管理例外。
GCP 未釘選版本。 當組態與呼叫皆未提供版本時，GCP 簽署器會引發金鑰管理錯誤，因為 asymmetric-sign 端點只在特定版本上運作。
不支援的演算法。 請求供應商不支援的演算法，會在任何網路呼叫之前引發不支援演算法例外。
傳輸失敗。 PSR-18 用戶端錯誤會被對應為簽署失敗例外；工作階段不會產生部分結果。
缺少憑證。 一個既無 token、也無 service-principal 憑證的簽署器，會引發具型別錯誤，而不是在未驗證的情況下呼叫供應商。

另請參閱

安全——NextPDF Pro — 遮蔽、PII 偵測，以及完整的 Pro 簽署介面。
HSM 簽署——NextPDF Enterprise — PKCS#11 硬體金鑰保管。
簽章——NextPDF Enterprise — PAdES B-LT 與 B-LTA 長期保存產生器。
安全 / 簽署（Core） — Core CMS 簽署器與簽署策略合約。
KMS · CMS · ECDSA · HSM — 詞彙表條目。