TPDFlibCSCClient

安全與簽章

描述

為 Cloud Signature Consortium 的憑證、授權與摘要簽署端點提供同步用戶端

用戶端從 credentials/info 取得簽署憑證與支援的演算法 OID、從 credentials/authorize 取得簽章啟用資料，並把一或多個已算好的摘要送交 signatures/signHash

SignDigest 實作了 TPDFlibExternalDigestSignEvent，可直接指派給 TPDFlib.OnExternalDigestSign，PDF ByteRange 的建立、CMS authenticated attributes、預留位置大小與回傳簽章的驗證都留在程式庫內

單位

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 公開，其他憑證透過 CertificateChainCount 與 GetCertificateChainDER，遠端批次上限則透過 MaxBatchSizeAuthorizationFunction 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;對於具備 GetCertificateChainDER 的憑證，摘要陣列為必填，且必須正好含 MaxBatchSize 個值預取的 SAD 會檢查到期與雜湊綁定，且只會被消耗一次

簽署

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_PKCS1PDF_EXTERNAL_SIGNATURE_ECDSA_DER

參數

ServiceURL	/csc/<version> 之前的基礎服務 URL
APIVersion	Endpoint version segment, default `v1`
CredentialID	Vendor-defined credential identifier
OAuthToken	加到每個預設傳輸請求的唯寫 bearer token
TimeoutMS	Request timeout, default 300000 milliseconds
MaxResponseBytes	Maximum accepted response size, default 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