TPDFlibCSCClient

安全和签名

描述

为 Cloud Signature Consortium 凭据、授权和摘要签名端点提供同步客户端

客户端从 credentials/info 检索签名证书和支持的算法 OID，从 credentials/authorize 获取签名激活数据，并将一个或多个已计算摘要提交至 signatures/signHash

SignDigest 实现 TPDFlibExternalDigestSignEvent，可直接分配给 TPDFlib.OnExternalDigestSign，将 PDF ByteRange 创建、CMS 已认证属性、占位符大小调整和返回签名验证保留在库内

单元

PDFlibCSC

构造

Constructor TPDFlibCSCClient.Create;
Destructor TPDFlibCSCClient.Destroy;

凭据发现

Function TPDFlibCSCClient.RefreshCredentialInfo: Boolean;
Function TPDFlibCSCClient.SupportsAlgorithm(DigestAlgorithm, SignatureAlgorithm: Integer): Boolean;
Function TPDFlibCSCClient.GetCertificateChainDER(Index: Integer): AnsiString;
Function TPDFlibCSCClient.GetSupportedAlgorithmOID(Index: Integer): AnsiString;
Procedure TPDFlibCSCClient.ClearCredentialInfo;

直接授权或批量签名调用前，RefreshCredentialInfo 必须成功

签名证书通过 SigningCertificateDER 提供，附加证书通过 CertificateChainCount 和 GetCertificateChainDER 提供，远程批处理上限通过 MaxBatchSize 提供

授权

Function TPDFlibCSCClient.Authorize(NumSignatures: Integer; Const Digests: TPDFlibCSCByteArray; Const PIN, OTP, Description, ClientData: WideString; Out SAD: AnsiString): Boolean;
Function TPDFlibCSCClient.PrefetchAuthorization(NumSignatures: Integer; Const Digests: TPDFlibCSCByteArray; Const PIN, OTP, Description, ClientData: WideString): Boolean;
Function TPDFlibCSCClient.SetPrefetchedSAD(Const SAD: AnsiString; ExpiresInSeconds: Integer; Const PinnedDigests: TPDFlibCSCByteArray): Boolean;
Procedure TPDFlibCSCClient.ClearSAD;
Procedure TPDFlibCSCClient.ClearAuthorizationSecrets;

对于 HashPinningRequired=True 的凭据，摘要数组是必需的，且必须恰好包含 NumSignatures 个值

会检查预取的 SAD 是否过期及其哈希绑定，并且仅消耗一次

签名

Function TPDFlibCSCClient.SignHashes(Const Digests: TPDFlibCSCByteArray; DigestAlgorithm, SignatureAlgorithm: Integer; Const SAD: AnsiString; Out Signatures: TPDFlibCSCByteArray): Boolean;
Function TPDFlibCSCClient.SignAuthorizedHashes(Const Digests: TPDFlibCSCByteArray; DigestAlgorithm, SignatureAlgorithm: Integer; Out Signatures: TPDFlibCSCByteArray): Boolean;
Function TPDFlibCSCClient.SignDigest(Sender: TObject; SignProcessID: Integer; Const Digest: AnsiString; DigestAlgorithm, SignatureAlgorithm: Integer; Var Signature: AnsiString): Boolean;

批次中的每个摘要都必须使用相同算法，并具有 DigestAlgorithm 所指定的确切长度

SignatureAlgorithm 支持 PDF_EXTERNAL_SIGNATURE_RSA_PKCS1 和 PDF_EXTERNAL_SIGNATURE_ECDSA_DER；CSC ECDSA 签名采用 DER 编码，因此不会推断 P1363 输出

参数

ServiceURL	`/csc/<version>` 之前的基础服务 URL
APIVersion	端点版本段，默认为 `v1`
CredentialID	供应商定义的凭据标识符
OAuthToken	添加到每个默认传输请求的只写承载令牌
TimeoutMS	请求超时，默认值为 300000 毫秒
MaxResponseBytes	最大接受响应大小，默认 8 MiB
ClientData	随签名请求发送的可选供应商定义值
AuthorizationPIN	供自动回调授权使用的只写 PIN
AuthorizationOTP	回调授权后擦除的仅写一次性密码
AuthorizationDescription	用于自动回调授权的可选说明
OnTransport	适用于 mTLS、代理、供应商特定或确定性测试集成的可选传输回调

状态属性

CredentialLoaded、SigningCertificateDER、CertificateChainCount、SupportedAlgorithmCount、MaxBatchSize、HashPinningRequired、LastAuthorizationExpiresAt、LastHTTPStatus 和 LastError 会公开当前状态，但不会返回 OAuth、PIN、OTP 或 SAD 机密

示例

var
  CSC: TPDFlibCSCClient;
  ProcessID: Integer;
begin
  CSC:= TPDFlibCSCClient.Create;
  try
    CSC.ServiceURL:= 'https://sign.example.com';
    CSC.CredentialID:= 'account/signing-key';
    CSC.OAuthToken:= AccessToken;
    CSC.AuthorizationPIN:= UserPIN;
    CSC.AuthorizationOTP:= CurrentOTP;
    if not CSC.RefreshCredentialInfo then
      raise Exception.Create(String(CSC.LastError));

    PDF.OnExternalDigestSign:= CSC.SignDigest;
    ProcessID:= PDF.NewSignProcessFromFile(InputFile, '');
    PDF.SetSignProcessField(ProcessID, 'Approval');
    PDF.SetSignProcessDigestAlgorithm(ProcessID, 2);
    PDF.SetSignProcessExternalDigestSigner(ProcessID,
      CSC.SigningCertificateDER, PDF_EXTERNAL_SIGNATURE_RSA_PKCS1, 512);
    PDF.EndSignProcessToFile(ProcessID, OutputFile);
  finally
    CSC.Free;
  end;
end;

失败行为

配置、传输、JSON、Base64、X.509、算法、批次、激活或响应计数验证失败时，方法返回 False 并设置 LastError

外部摘要签名路径会在接受 PDF 前，根据 SigningCertificateDER 独立验证每个返回的原始签名

另请参阅

OnExternalDigestSign、SetSignProcessExternalDigestSigner、SetSignProcessDigestAlgorithm