Pro phiên bản

Ký bằng Cloud KMS (AWS KMS, Azure Key Vault, GCP KMS)

Tổng quan nhanh

NextPDF Pro ký một PDF bằng khóa được giữ trong một dịch vụ quản lý khóa trên đám mây (KMS). Các nhà cung cấp được hỗ trợ là Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault, và Google Cloud Platform (GCP) Cloud KMS. Mỗi nhà cung cấp hiện thực một hợp đồng ký, nên ứng dụng của bạn phụ thuộc vào hợp đồng chứ không phụ thuộc vào một lớp nhà cung cấp. Chỉ digest của các thuộc tính đã ký được gửi đến nhà cung cấp; tài liệu không bao giờ rời khỏi máy chủ của bạn trong thao tác ký. Trang này ở mức hành vi: nó nêu rõ mỗi nhà cung cấp gửi và nhận những gì, cách các phiên bản khóa được phân giải, và nơi việc giám hộ khóa không còn là trách nhiệm của NextPDF.

Hợp đồng này mở rộng hợp đồng trình ký phần cứng và đám mây của Core, nên một chiến lược cloud-KMS có thể cắm vào cùng đường dẫn ký mà trình ký Core sử dụng.

Các điều kiện tiên quyết được nêu trong phần frontmatter và được lặp lại trong Điều kiện tiên quyết.

Phiên bản và cấp phép

Các chiến lược ký cloud-KMS đi kèm trong gói nextpdf/pro và được kiểm soát bởi cờ tính năng giấy phép pro. NextPDF Core đi kèm một trình ký CMS phần mềm; NextPDF Enterprise bổ sung việc giám hộ khóa bằng phần cứng thông qua PKCS#11. Ký cloud-KMS là một năng lực của Pro và cũng đạt được trong Enterprise, vì Enterprise phụ thuộc vào Pro. Một triển khai không có quyền Pro đang hoạt động sẽ không nạp các lớp chiến lược này; hợp đồng ký của Core vẫn tiếp tục hoạt động không thay đổi. So sánh các phiên bản.

Năng lực này làm gì

Mỗi trình ký cloud-KMS hiện thực một hợp đồng nhà cung cấp mở rộng hợp đồng trình ký của Core. Hợp đồng bổ sung ba thứ: một định danh nhà cung cấp ổn định để tra cứu trong registry, một phương thức ký nhận biết phiên bản khóa, và việc tự mô tả các thuật toán mà một nhà cung cấp hỗ trợ để bộ điều phối có thể chọn một nhà cung cấp tương thích trước khi ký.

Luồng ký giữ tài liệu trên máy chủ của bạn:

Phiên ký Pro tính digest của tài liệu và dựng các thuộc tính đã ký CMS.
Phiên băm các thuộc tính đã ký và chỉ gửi digest đó đến nhà cung cấp. Một dịch vụ ký bên ngoài chấp nhận một message-digest do bên gọi cung cấp và trả về chữ ký là khuôn mẫu đã được thiết lập để giữ tài liệu bên trong ranh giới của bạn, như được mô tả trong khung tham chiếu EU Digital Signature Service (DSS).
Nhà cung cấp ký digest bằng phiên bản khóa mà nó phân giải và trả về chữ ký thô.
Phiên lắp ráp CMS SignedData và nhúng nó vào PDF.

Các nhà cung cấp được hiện thực qua các lời gọi Hypertext Transfer Protocol (HTTP) thuần PSR-18 — không phụ thuộc vào software development kit (SDK) của nhà cung cấp đám mây. Việc xác thực được ủy thác cho ứng dụng của bạn: bạn cung cấp một bearer token (AWS, GCP) hoặc một token hay thông tin xác thực service-principal (Azure). Mỗi nhà cung cấp chuẩn hóa kết quả của mình cho CMS: AWS và GCP trả về chữ ký Rivest–Shamir–Adleman (RSA) ở dạng DER sẵn sàng cho CMS; một chữ ký Elliptic Curve Digital Signature Algorithm (ECDSA) mà một nhà cung cấp trả về dưới dạng một cặp số nguyên thô (Azure) được chuyển sang dạng mã hóa DER, trong khi GCP trả về ECDSA đã được mã hóa DER. Đường cong ECDSA và digest được ghép theo quy ước — P-256 với SHA-256, P-384 với SHA-384, P-521 với SHA-512 — theo cặp được khuyến nghị trong RFC 5480.

Một registry PSR-11 phân giải các nhà cung cấp theo định danh và hỗ trợ factory khởi tạo trễ. Khách hàng tự lưu trữ Enterprise đăng ký một driver HSM hoặc KMS độc quyền bằng cách hiện thực hợp đồng nhà cung cấp và ràng buộc nó trong registry — mà không cần fork NextPDF Pro.

Ngữ nghĩa phiên bản khóa theo từng nhà cung cấp

Các nhà cung cấp phơi bày những primitive “phiên bản đang hoạt động” khác nhau, nên hành vi phiên bản khóa mặc định khác nhau:

AWS KMS — một phiên bản khóa null sử dụng key alias, mà AWS phân giải thành phiên bản khóa hiện tại ở phía nhà cung cấp.
Azure Key Vault — một phiên bản khóa null sử dụng key URL không có phiên bản, mà Azure phân giải thành phiên bản đã bật mới nhất. Một giá trị ghi đè tường minh phải là một định danh thập lục phân 32 ký tự; bất kỳ giá trị nào khác đều bị từ chối để ngăn việc tiêm vào URL-segment.
GCP Cloud KMS — endpoint asymmetric-sign chỉ vận hành trên một phiên bản crypto-key cụ thể; không có “phiên bản đang hoạt động” ở phía máy chủ. Bạn phải ghim một phiên bản trong cấu hình hoặc truyền vào một phiên bản tường minh. Nếu không đặt cả hai, trình ký phát sinh một lỗi quản lý khóa thay vì đoán.

Hãy ghi lại chế độ mà triển khai của bạn dùng để hành vi mang tính tất định.

Điều kiện tiên quyết

Cài đặt NextPDF Core và gói Pro, và sở hữu một giấy phép Pro đang hoạt động.
Cấp phát một khóa ký trong nhà cung cấp bạn chọn và ghi lại các định danh của nó (key alias hoặc Amazon Resource Name cho AWS; vault và key name cho Azure; project, location, key ring, crypto key, và version cho GCP).
Cung cấp một HTTP client PSR-18 và các factory request và stream PSR-17.
Lấy thông tin xác thực của nhà cung cấp trong ứng dụng của bạn: một bearer token cho AWS hoặc GCP, hoặc một token đã lấy sẵn hay thông tin xác thực service-principal cho Azure. Việc lấy token là trách nhiệm của ứng dụng của bạn; hãy cung cấp các bí mật từ secret manager của bạn, không bao giờ từ mã nguồn.

Cấu hình

Mỗi nhà cung cấp có một đối tượng cấu hình bất biến được dựng từ các định danh và thông tin xác thực của bạn. Những mối quan tâm cấu hình chung:

Định danh nhà cung cấp — aws-kms, azure-keyvault, hoặc gcp-kms, dùng làm khóa tra cứu trong registry.
Thuật toán — được chọn theo từng lời gọi từ tên thuật toán mà phiên ký của bạn truyền vào; nhà cung cấp từ chối một thuật toán mà nó không hỗ trợ.
Phiên bản khóa — được ghim trong cấu hình hoặc truyền theo từng lời gọi, với ngữ nghĩa theo từng nhà cung cấp được mô tả ở trên.
Thông tin xác thực — một bearer token hoặc thông tin xác thực service-principal mà ứng dụng của bạn cung cấp từ secret manager của nó.

Từng bước

Dựng cấu hình nhà cung cấp từ các định danh của bạn và một thông tin xác thực được đọc từ secret manager của bạn.
Khởi tạo trình ký nhà cung cấp với cấu hình, chứng chỉ của bên ký ở dạng DER, chuỗi, HTTP client PSR-18, và các factory PSR-17.
Tùy chọn đăng ký nhà cung cấp trong registry PSR-11 dưới định danh của nó để bộ điều phối phân giải nó theo tên.
Chạy phiên ký Pro: nó tính digest, dựng các thuộc tính đã ký, và gọi nhà cung cấp chỉ với digest.
Bắt lỗi cụ thể nhất — quản lý khóa, thuật toán không được hỗ trợ, hoặc ký thất bại — ghi nhật ký một thông báo có cấu trúc không kèm bí mật, rồi ném lại.

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

Kiểm chứng

Xác nhận nhà cung cấp tự mô tả thuật toán bạn định dùng trước khi ký, để một thuật toán không được hỗ trợ bị bắt ngay khi chọn chứ không phải tại lời gọi nhà cung cấp.
Xác nhận chỉ digest được truyền đi: các byte của tài liệu không được xuất hiện trong thân request gửi đến nhà cung cấp. Request mang theo một digest mã hóa base64, không phải tệp.
Đối với ECDSA, xác nhận chữ ký được nhúng đã được mã hóa DER — trình ký chuyển đổi một chữ ký cặp số nguyên thô giúp bạn.
Mở PDF đã ký trong một trình xác thực được cấu hình với các trust anchor của bạn và xác nhận chữ ký được báo cáo là toàn vẹn về mặt mật mã. Một chữ ký đã tạo không phải là một chữ ký đã được xác minh; quyết định tin cậy thuộc về bên xác minh.
Xác nhận không có token, thông tin xác thực, hay vật liệu khóa nào xuất hiện trong nhật ký ứng dụng của bạn.

Bảo mật và tuân thủ

Khóa nằm lại trong nhà cung cấp. Một chiến lược cloud-KMS là một điểm tích hợp, không phải một kho khóa. NextPDF Pro không giữ khóa riêng cho một chiến lược KMS.
Chỉ digest vượt qua ranh giới. Phiên gửi digest của các thuộc tính đã ký đến nhà cung cấp, không phải tài liệu — khuôn mẫu message-digest-input được mô tả trong khung tham chiếu EU DSS.
Byte range được tính bởi engine. Nó không bao giờ được chấp nhận từ bên gọi.
Fail-closed. Một lỗi của nhà cung cấp, mạng, phiên bản khóa, hoặc thuật toán không được hỗ trợ sẽ phát sinh một ngoại lệ có kiểu. Phiên không âm thầm tạo ra một tài liệu chưa ký và không bao giờ thay thế bằng một thuật toán yếu hơn.
Thông tin xác thực là bí mật. Token và thông tin xác thực service-principal đến từ secret manager của bạn và bị loại trừ khỏi nhật ký.

Trang này liên quan đến việc ký mã hóa. Mọi nguồn quy phạm đều được diễn giải lại; không có văn bản quy phạm nào được sao chép nguyên văn. ### Ranh giới giám hộ khóa

Việc bảo vệ khóa phụ thuộc vào cách xử lý khóa, KMS đã cấu hình, và triển khai. NextPDF Pro cung cấp tích hợp KMS, không phải kho khóa. NextPDF Pro chỉ tương thích FIPS khi được cấu hình với một KMS hoặc HSM đã được thẩm định theo FIPS; bản thân nó không phải là một module mật mã đã được thẩm định theo FIPS và không đưa ra tuyên bố chứng nhận FIPS nào.

Xử lý lỗi

Phiên bản khóa không xác định hoặc bị vô hiệu. Nhà cung cấp ánh xạ một phản hồi không-tìm-thấy hoặc phiên-bản-bị-vô-hiệu thành một ngoại lệ quản lý khóa nêu tên nhà cung cấp và khóa.
GCP không có phiên bản được ghim. Trình ký GCP phát sinh một lỗi quản lý khóa khi cả cấu hình lẫn lời gọi đều không cung cấp một phiên bản, vì endpoint asymmetric-sign chỉ vận hành trên một phiên bản cụ thể.
Thuật toán không được hỗ trợ. Việc yêu cầu một thuật toán mà nhà cung cấp không hỗ trợ sẽ phát sinh một ngoại lệ thuật toán không được hỗ trợ trước bất kỳ lời gọi mạng nào.
Lỗi truyền tải. Một lỗi client PSR-18 được ánh xạ thành một ngoại lệ ký thất bại; phiên không tạo ra một kết quả một phần.
Thiếu thông tin xác thực. Một trình ký không có token và không có thông tin xác thực service-principal sẽ phát sinh một lỗi có kiểu thay vì gọi nhà cung cấp ở trạng thái chưa xác thực.

Xem thêm

Bảo mật — NextPDF Pro — che dữ liệu, phát hiện PII, và toàn bộ bề mặt ký của Pro.
Ký HSM — NextPDF Enterprise — giám hộ khóa phần cứng PKCS#11.
Chữ ký — NextPDF Enterprise — trình tạo dài hạn PAdES B-LT và B-LTA.
Bảo mật / Ký (Core) — trình ký CMS của Core và hợp đồng chiến lược ký.
KMS · CMS · ECDSA · HSM — các thuật ngữ bảng chú giải.