TPDFlibCSCClient

Security and signatures

Description

Provides a synchronous client for the Cloud Signature Consortium credential, authorisation, and digest-signing endpoints

The client retrieves the signing certificate and supported algorithm OIDs from credentials/info, obtains signature activation data from credentials/authorize, and submits one or more already-computed digests to signatures/signHash

SignDigest implements TPDFlibExternalDigestSignEvent and can be assigned directly to TPDFlib.OnExternalDigestSign, keeping PDF ByteRange creation, CMS authenticated attributes, placeholder sizing, and returned-signature verification inside the library

Unit

PDFlibCSC

Construction

Constructor TPDFlibCSCClient.Create;
Destructor TPDFlibCSCClient.Destroy;

Credential discovery

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 must succeed before direct authorisation or batch signing calls

The signing certificate is exposed through SigningCertificateDER, additional certificates through CertificateChainCount and GetCertificateChainDER, and the remote batch ceiling through MaxBatchSize

Authorisation

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;

For credentials with HashPinningRequired=True, the digest array is mandatory and must contain exactly NumSignatures values

Prefetched SAD is checked for expiry and hash binding and is consumed exactly once

Signing

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;

Every digest in a batch must use the same algorithm and have the exact length implied by DigestAlgorithm

SignatureAlgorithm supports PDF_EXTERNAL_SIGNATURE_RSA_PKCS1 and PDF_EXTERNAL_SIGNATURE_ECDSA_DER; CSC ECDSA signatures are DER encoded, so P1363 output is not inferred

Configuration properties

ServiceURL	Base service URL before `/csc/<version>`
APIVersion	Endpoint version segment, default `v1`
CredentialID	Vendor-defined credential identifier
OAuthToken	Write-only bearer token added to every default transport request
TimeoutMS	Request timeout, default 300000 milliseconds
MaxResponseBytes	Maximum accepted response size, default 8 MiB
ClientData	Optional vendor-defined value sent with signing requests
AuthorizationPIN	Write-only PIN used by automatic callback authorisation
AuthorizationOTP	Write-only one-time password erased after callback authorisation
AuthorizationDescription	Optional description used by automatic callback authorisation
OnTransport	Optional transport callback for mTLS, proxy, vendor-specific, or deterministic test integration

Status properties

CredentialLoaded, SigningCertificateDER, CertificateChainCount, SupportedAlgorithmCount, MaxBatchSize, HashPinningRequired, LastAuthorizationExpiresAt, LastHTTPStatus, and LastError expose the current state without returning OAuth, PIN, OTP, or SAD secrets

Example

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;

Failure behaviour

Methods return False and set LastError when configuration, transport, JSON, Base64, X.509, algorithm, batch, activation, or response-count validation fails

The external digest signing path independently verifies each returned raw signature against SigningCertificateDER before accepting the PDF