Ký bằng Cloud KMS — Tài liệu tham chiếu chuyên sâu

Nhìn tổng quan

Trang này là tham chiếu ở cấp hợp đồng cho bề mặt ký bằng cloud-KMS của NextPDF Pro. Bề mặt này gồm một Service Provider Interface, NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface, và ba provider signer: AwsKmsSigner, AzureKeyVaultSigner và GcpKmsSigner. Hai adapter, AwsKmsSigningStrategy và AzureKeyVaultSigningStrategy, bắc cầu một signer sang hợp đồng SigningStrategy của Pro. Mỗi signer chỉ gửi một message digest đến nhà cung cấp của nó qua HTTP PSR-18. Khóa riêng và tài liệu không bao giờ vượt qua ranh giới. Trang này nêu API công khai, hợp đồng hành vi có thể quan sát được, và các chế độ lỗi có kiểu. Điều phối phiên (RemoteSigningSession, SequentialSigner) và đóng dấu thời gian (PadesBtTimestamper) nằm ở các trang riêng của chúng.

Khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một envelope giấy phép cấp Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Bề mặt API công khai

Symbol	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
KmsSignerInterface	—	Mở rộng hợp đồng Core HsmSignerInterface	—	—	SPI cho driver KMS và HSM; các id built-in được dành riêng: aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli
KmsSignerInterface::providerId()	không có	Khóa tra cứu registry ổn định	non-empty-string	—	Driver bên thứ ba phải đặt namespace cho định danh của mình
KmsSignerInterface::signWithVersion()	$data, $algorithm = 'sha256WithRSAEncryption', $keyVersion = null	Phiên bản khóa null quay về mặc định của nhà cung cấp	Các octet chữ ký string: RSA như nhà cung cấp trả về (đặt trực tiếp vào SignerInfo.signature), ECDSA dưới dạng DER ECDSA-Sig-Value theo quy tắc CMS	KeyManagementException, UnsupportedAlgorithmException, SignatureFailedException	Ngữ nghĩa null khác nhau theo từng nhà cung cấp; xem hợp đồng hành vi
KmsSignerInterface::supportsAlgorithm()	string $algorithm	Thăm dò năng lực; không thực hiện I/O	bool	—	Được gọi trước khi chọn nhà cung cấp
KmsSignerInterface::supportedAlgorithms()	không có	Liệt kê các tên kiểu OpenSSL mà nhà cung cấp chấp nhận	list<non-empty-string>	—	—
AwsKmsSigner	constructor: AwsKmsConfig, cert DER, chain DER, PSR-18 client, PSR-17 factory, PSR-3 logger	Thuật toán mặc định là KmsSigningAlgorithm::RsaPkcs1Sha256	—	xem các phương thức	final; PROVIDER_ID = 'aws-kms'
AwsKmsSigner::create()	key id, cert DER, phụ thuộc PSR, chain tùy chọn, config, logger	Dựng AwsKmsConfig::fromEnvironment($keyId) khi $config là null	self	—	Đọc các biến môi trường AWS_* chuẩn
AwsKmsSigner::withAlgorithm()	KmsSigningAlgorithm $algorithm	Trả về một bản sao đã sửa đổi	self	—	Phải khớp với loại khóa được cấp trong AWS KMS
AwsKmsSigner::sign()	$data, $algorithm = 'sha256WithRSAEncryption'	Ủy quyền cho signWithVersion($data, $algorithm, null)	string	như signWithVersion()	Đường dẫn hợp đồng Core hai tham số kế thừa
AzureKeyVaultSigner	constructor: AzureKeyVaultConfig, cert DER, chain DER, PSR-18 client, PSR-17 factory, PSR-3 logger	Thuật toán mặc định là AzureSigningAlgorithm::Rs256; một access token trong config gieo giá trị bearer token	—	xem các phương thức	final; PROVIDER_ID = 'azure-keyvault'
AzureKeyVaultSigner::create()	vault name, key name, cert DER, phụ thuộc PSR, chain tùy chọn, config, logger	Dựng AzureKeyVaultConfig::fromEnvironment() khi $config là null	self	—	Hỗ trợ token lấy sẵn hoặc thông tin xác thực service-principal
AzureKeyVaultSigner::withAlgorithm()	AzureSigningAlgorithm $algorithm	Trả về một bản sao đã sửa đổi	self	—	Khóa RSA dùng giá trị RS/PS; khóa EC dùng giá trị ES
GcpKmsSigner	constructor: GcpKmsConfig, cert DER, chain DER, PSR-18 client, PSR-17 factory, PSR-3 logger	Thuật toán mặc định là GcpKmsSigningAlgorithm::RsaSignPkcs1_2048Sha256	—	xem các phương thức	final; PROVIDER_ID = 'gcp-kms', API_VERSION = 'v1'
GcpKmsSigner::create()	project id, location, key ring, crypto key, cert DER, phụ thuộc PSR, chain tùy chọn, config, logger	Dựng GcpKmsConfig::fromEnvironment() khi $config là null	self	—	Việc lấy bearer-token được ủy quyền cho bên gọi
GcpKmsSigner::withAlgorithm()	GcpKmsSigningAlgorithm $algorithm	Chỉ là bản xem trước ở thời điểm config; tên wire theo từng lệnh gọi thắng tại thời điểm ký	self	—	Kích thước khóa cố định theo CryptoKeyVersion đã được cấp
AwsKmsSigningStrategy	constructor: AwsKmsSigner $signer	Đồng bộ; isAsync() trả về false	—	Truyền tiếp các exception của signer được bọc	Adapter cho RemoteSigningSession::complete()
AzureKeyVaultSigningStrategy	constructor: AzureKeyVaultSigner $signer	Đồng bộ; isAsync() trả về false	—	Truyền tiếp các exception của signer được bọc	Adapter cho RemoteSigningSession::complete()
KmsSigningAlgorithm	enum, 9 trường hợp (RSA PKCS#1, RSA-PSS, ECDSA; SHA-256/384/512)	—	Giá trị wire SigningAlgorithm của AWS KMS	InvalidArgumentException từ fromOpenSslName()	resolveForWireName() giữ nguyên digest PSS đã cấu hình
AzureSigningAlgorithm	enum, 9 trường hợp (RS256…ES512)	—	Giá trị kiểu JWA của Azure Key Vault	InvalidArgumentException từ fromOpenSslName()	isEcdsa() đánh dấu các giá trị mà đầu ra cần chuyển đổi DER
GcpKmsSigningAlgorithm	enum, 10 trường hợp (EC P-256/P-384, RSA PKCS#1, RSA-PSS)	—	Giá trị thuật toán CryptoKeyVersion của GCP	UnsupportedAlgorithmException từ fromOpenSslName()	Phân giải tên wire chọn kích thước khóa khớp nhỏ nhất

Chữ ký các entry-point

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

Hợp đồng hành vi

Phân giải hợp đồng

KmsSignerInterface mở rộng hợp đồng Core HsmSignerInterface. Nó bổ sung providerId(), signWithVersion() nhận biết phiên bản khóa, và các thăm dò năng lực supportsAlgorithm() và supportedAlgorithms(). Phương thức sign() hai tham số được kế thừa ủy quyền cho signWithVersion() với phiên bản khóa null trên cả ba signer. getCertificateDer(), getCertificateChainDer() và getPublicKeyAlgorithm() được hiện thực từ vật liệu do constructor cung cấp. Các thăm dò năng lực không thực hiện I/O. Mỗi signer cũng phơi bày các accessor getSigningAlgorithm() và getConfig() để kiểm tra.

Truyền chỉ digest

Mỗi signer băm $data cục bộ bằng digest của thuật toán đã phân giải và chỉ truyền đi digest đó. AWS nhận một digest base64 với MessageType: DIGEST. Azure nhận một digest base64url trong thân yêu cầu ký. GCP nhận một digest base64 trong trường digest theo từng thuật toán. Các byte tài liệu không bao giờ xuất hiện trong một yêu cầu tới nhà cung cấp. Mọi vận chuyển dùng một HTTP client PSR-18 chuẩn qua endpoint HTTPS của nhà cung cấp; không có SDK của nhà cung cấp cloud nào tham gia.

Phân giải phiên bản khóa

signWithVersion() xác thực đối số phiên bản khóa theo kiểu fail-closed trước khi bất kỳ yêu cầu nào được dựng. Một giá trị không đạt grammar của nhà cung cấp sẽ nêu KeyManagementException và ngăn chặn việc chèn phân đoạn URL hoặc chèn KeyId.

Nhà cung cấp	Phiên bản khóa null	Chuỗi rỗng	Grammar ghi đè
AwsKmsSigner	Dùng AwsKmsConfig::$keyId; một alias hoặc ARN phân giải về khóa hiện hành ở phía nhà cung cấp	Bị từ chối	UUID (có hoặc không có dấu gạch), alias/<name>, hoặc một KMS key/alias ARN
AzureKeyVaultSigner	Dùng phiên bản khóa đã cấu hình; một giá trị config rỗng chọn phiên bản mới nhất được bật ở phía máy chủ	Bị từ chối	Định danh thập lục phân 32 ký tự
GcpKmsSigner	Dùng phiên bản được ghim trong GcpKmsConfig; nếu không ghim phiên bản nào, nêu KeyManagementException	Bị từ chối	Id CryptoKeyVersion thập phân, chỉ gồm chữ số

GCP không có primitive “phiên bản đang hoạt động” ở phía máy chủ. Endpoint asymmetric-sign chỉ vận hành trên một tài nguyên cryptoKeyVersions/{n} cụ thể, nên một phiên bản phải luôn phân giải được.

Phân giải thuật toán

Lớp strategy chuyển tiếp một tên wire kiểu OpenSSL. AWS và Azure chấp nhận bảy tên wire (PKCS#1 và ECDSA ở SHA-256/384/512, cộng thêm RSASSA-PSS). GCP chấp nhận năm tên (sha256WithRSAEncryption, sha512WithRSAEncryption, RSASSA-PSS, ecdsa-with-SHA256, ecdsa-with-SHA384). Tên wire RSASSA-PSS không mã hóa một digest, nên nó là nhập nhằng-digest. AwsKmsSigner phân giải nó qua KmsSigningAlgorithm::resolveForWireName(), vốn giữ nguyên digest của biến thể PSS đã cấu hình. AzureKeyVaultSigner tin tưởng biến thể PSS đã cấu hình cho tên nhập nhằng. Nó nêu UnsupportedAlgorithmException nếu một digest PSS đã phân giải khác với digest đã cấu hình. GcpKmsSigner phân giải lại enum từ tên wire trong mỗi lệnh gọi; withAlgorithm() trên GCP là một bản xem trước ở thời điểm config và không thay đổi hành vi ở thời điểm ký. Một tên wire không được hỗ trợ sẽ nêu UnsupportedAlgorithmException trước bất kỳ lệnh gọi mạng nào. Trên AwsKmsSigner và GcpKmsSigner, một lệnh gọi ký cập nhật giá trị được getSigningAlgorithm() báo cáo sau đó thành thuật toán theo-từng-lệnh-gọi đã phân giải. Trên AzureKeyVaultSigner, việc phân giải là cục bộ theo lệnh gọi và giá trị đã cấu hình vẫn là nguồn quyền uy.

Chuẩn hóa chữ ký

AWS và GCP trả về chữ ký ở dạng mà CMS tiêu thụ: các octet chữ ký RSA đi vào SignerInfo.signature không thay đổi, và ECDSA đến ở dạng mã hóa DER. Azure trả về ECDSA ở dạng IEEE P1363 thô (r||s), mà signer chuyển đổi thành một DER ECDSA-Sig-Value trước khi trả về.

Tích hợp CMS và tính lân cận

Một adapter SigningStrategy ký các signed attributes được mã hóa DER do phiên cung cấp. Khi có signed attributes hiện diện, đầu vào chữ ký CMS là digest của toàn bộ mã hóa DER của giá trị SignedAttrs — RFC 5652 §5.4. Các phương thức getSignatureAlgorithmOid() và getDigestAlgorithm() của adapter cấp cho các trường signatureAlgorithm và digestAlgorithm của SignerInfo — RFC 5652 §5.3. Các byte trả về trở thành OCTET STRING chữ ký của SignerInfo — RFC 5652 §5.5. Việc lắp ráp CMS, xử lý ByteRange và vòng đời phiên thuộc về RemoteSigningSession; các luồng đa bên thuộc về SequentialSigner. Một signature-time-stamp PAdES B-T, mà messageImprint của nó băm giá trị chữ ký của SignerInfo — RFC 3161 Appendix A — được áp dụng bởi PadesBtTimestamper, không phải bởi các signer này. Cả ba đều được ghi tài liệu trên tham chiếu chuyên sâu về bảo mật của Pro.

Trường hợp biên & chế độ lỗi

• Một phiên bản khóa là chuỗi rỗng bị từ chối trên cả ba nhà cung cấp. Truyền null để kế thừa mặc định đã cấu hình.
• Một phiên bản khóa sai định dạng bị từ chối trước khi bất kỳ yêu cầu nào được dựng, với giá trị vi phạm được nêu tên trong exception.
• AwsKmsSigner với một AwsKmsConfig::$keyId rỗng và một phiên bản khóa null sẽ nêu KeyManagementException.
• Các phản hồi từ nhà cung cấp báo hiệu một thất bại quản lý khóa ánh xạ sang KeyManagementException: AWS NotFoundException, DisabledException, KeyUnavailableException, InvalidKeyUsageException, hoặc HTTP 404; Azure HTTP 404, KeyNotFound, KeyDisabled, hoặc KeyNotActive; GCP HTTP 404 hoặc 409, NOT_FOUND, FAILED_PRECONDITION, hoặc một HTTP 400 mà thông điệp của nó nêu tên một phiên bản.
• Các phản hồi khác không-200 từ nhà cung cấp nêu SignatureFailedException trên AWS và GCP, và AzureKeyVaultException trên Azure.
• Một thất bại vận chuyển PSR-18 trong lúc ký ánh xạ sang SignatureFailedException với client exception được giữ lại làm throwable trước đó.
• AzureKeyVaultSigner không có access token và không có thông tin xác thực service-principal sẽ nêu AzureKeyVaultException trước bất kỳ lệnh gọi vault nào. Một lần lấy token Azure AD thất bại cũng nêu AzureKeyVaultException.
• AzureKeyVaultSigner xác thực vault name, key name, key version và tenant id đối chiếu với các grammar được Azure công bố tại chốt chặn yêu cầu. Một giá trị mang ký tự cấu trúc-URL thất bại theo kiểu fail-closed với AzureKeyVaultException.
• GcpKmsSigner không có OAuth2 bearer token sẽ nêu SignatureFailedException; việc lấy token là trách nhiệm của bên gọi.
• Một phản hồi từ nhà cung cấp không phải JSON hợp lệ, hoặc thiếu trường chữ ký, sẽ nêu SignatureFailedException (Azure: một trường value bị thiếu sẽ nêu AzureKeyVaultException).
• Một trường chữ ký từ nhà cung cấp thất bại giải mã base64 sẽ nêu SignatureFailedException trên AWS và GCP, và AzureKeyVaultException trên Azure.
• Không có adapter SigningStrategy cho GcpKmsSigner được cung cấp trong 3.1.0. Signer GCP được tiêu thụ trực tiếp qua hợp đồng KmsSignerInterface.

Hành vi ở chế độ FIPS

AwsKmsConfig::withFipsEndpoint() định tuyến các yêu cầu đến endpoint kms-fips của khu vực. Trạng thái xác thực FIPS của endpoint đó là một thuộc tính của AWS, không phải của NextPDF. AzureKeyVaultConfig và GcpKmsConfig không phơi bày helper endpoint FIPS chuyên biệt nào trong 3.1.0. Việc tính digest chạy trong tiến trình với hàm PHP hash() và bản thân nó không phải một module đã được xác thực. NextPDF Pro có thể vận hành đối chiếu với một ranh giới KMS hoặc HSM đã được xác thực FIPS, nhưng NextPDF không phải một module mật mã đã được xác thực FIPS và không đưa ra tuyên bố chứng nhận FIPS nào.

Tuân thủ

Tuyên bố	Chuẩn	Điều khoản
Strategy ký các signed attributes được mã hóa DER; digest đầu vào chữ ký CMS bao phủ toàn bộ mã hóa DER của SignedAttrs.	RFC 5652	§5.4
SignedAttributes được mã hóa DER và mang tối thiểu content-type và message-digest; signatureAlgorithm định danh thuật toán của signer.	RFC 5652	§5.3
Các byte chữ ký trả về được mã hóa dưới dạng OCTET STRING và mang trong trường chữ ký của SignerInfo.	RFC 5652	§5.5
Một signature time-stamp có messageImprint băm giá trị chữ ký của SignerInfo (bề mặt B-T lân cận, không phải các signer này).	RFC 3161	Appendix A

Mọi điều khoản đều được diễn giải; NextPDF không tái tạo văn bản quy phạm. Đây là những tuyên bố năng lực, không phải chứng nhận. NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào. Việc một chữ ký được tạo ra có xác minh được hay không là quyết định của bên xác minh đối chiếu với các trust anchor và chính sách của riêng nó; các signer trả về các byte chữ ký và không khẳng định bất kỳ kết quả tin cậy nào. Việc lưu giữ khóa, bảo vệ khóa và xác thực thuật toán ở phía nhà cung cấp là các thuộc tính của KMS đã cấu hình, không phải của NextPDF.

Ghi chú phát triển

• Tính khả dụng trong gói Pro: AwsKmsSigner từ 1.9.0, AzureKeyVaultSigner từ 2.0.0, GcpKmsSigner và KmsSignerInterface từ 2.1.0. Tất cả đều hiện hành trong nextpdf/pro 3.1.0.
• Các signer chỉ phụ thuộc vào PSR-18, PSR-17 và PSR-3. Không có SDK của AWS, Azure hay Google được yêu cầu hoặc đóng gói kèm.
• Thăm dò supportsAlgorithm() trước khi ký để một nhà cung cấp không tương thích bị từ chối tại thời điểm chọn, không phải giữa phiên.
• Các trường thông tin xác thực được tiêm qua constructor và được đánh dấu là tham số nhạy cảm. Các thông điệp log chỉ mang các trường cấu trúc; không có thông tin xác thực, token hay nội dung tài liệu nào được ghi vào log.
• Ghim phiên bản khóa một cách rõ ràng trong các triển khai được quản lý. Các mặc định phân giải-alias (AWS) và mới-nhất-được-bật (Azure) tiện lợi nhưng không có tính xác định qua các lần xoay khóa.
• Driver bên thứ ba hiện thực KmsSignerInterface và phải đặt namespace cho providerId() của mình để tránh xung đột với các định danh built-in được dành riêng.

Xem thêm

• Ký bằng Cloud KMS (năng lực) — trang hướng dẫn: thiết lập, cấu hình và ranh giới lưu giữ khóa.
• Bảo mật — tham chiếu chuyên sâu — RemoteSigningSession, SequentialSigner, bề mặt PAdES B-B/B-T, và hợp đồng SigningStrategy.
• Chữ ký — tham chiếu chuyên sâu (Enterprise) — ranh giới producer dài hạn B-LT/B-LTA.
• Bảo mật / Ký (Core) — signer CMS của Core và các hợp đồng mà bề mặt này mở rộng.

Ranh giới xuất bản

Trang này chỉ ghi tài liệu hành vi có thể quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp helper, bảng cơ chế, tên tệp runbook và tiền tố ticket nằm ngoài phạm vi.