TPDFlibCSCClient

Segurança e assinaturas

Descrição

Fornece um cliente síncrono para os endpoints de credencial, autorização e assinatura por digest do Cloud Signature Consortium

O cliente obtém o certificado de assinatura e os OIDs de algoritmos suportados de credentials/info, consegue os dados de ativação de assinatura de credentials/authorize e submete um ou mais digests já calculados a signatures/signHash

SignDigest implementa TPDFlibExternalDigestSignEvent e pode ser atribuído diretamente a TPDFlib.OnExternalDigestSign, mantendo dentro da biblioteca a criação do ByteRange do PDF, os atributos autenticados CMS, o dimensionamento do placeholder e a verificação da assinatura retornada

Unidade

PDFlibCSC

Construção

Constructor TPDFlibCSCClient.Create;
Destructor TPDFlibCSCClient.Destroy;

Descoberta de credenciais

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

O certificado de assinatura é exposto por SigningCertificateDER, certificados adicionais por CertificateChainCount e GetCertificateChainDER, e o teto de lote remoto por MaxBatchSize

Assinatura

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;

Todo digest de um lote deve usar o mesmo algoritmo e ter o comprimento exato implícito por HashPinningRequired=True. NumSignatures suporta

O SAD pré-buscado é verificado quanto a expiração e vínculo de hash e é consumido exatamente uma vez

Assinatura

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;

Todo digest em um lote deve usar o mesmo algoritmo e ter o comprimento exato implícito por DigestAlgorithm

SignatureAlgorithm and PDF_EXTERNAL_SIGNATURE_RSA_PKCS1PDF_EXTERNAL_SIGNATURE_ECDSA_DER

Parâmetros

ServiceURL	URL base do serviço antes de `/csc/<version>`
APIVersion	Segmento de versão do endpoint, `v1` por padrão
CredentialID	Identificador de credencial definido pelo fornecedor
OAuthToken	Token bearer somente de gravação adicionado a cada requisição de transporte padrão
TimeoutMS	Tempo limite da requisição, 300000 milissegundos por padrão
MaxResponseBytes	Tamanho máximo aceito de resposta, 8 MiB por padrão
ClientData	Valor opcional definido pelo fornecedor, enviado com os pedidos de assinatura
AuthorizationPIN	PIN somente de gravação usado pela autorização de callback automática
AuthorizationOTP	Senha de uso único write-only, apagada após a autorização do callback
AuthorizationDescription	Descrição opcional usada pela autorização de callback automática
OnTransport	Callback de transporte opcional para mTLS, proxy, integração específica do fornecedor ou de teste determinística

Propriedades de status

CredentialLoaded, SigningCertificateDER, CertificateChainCount, SupportedAlgorithmCount, MaxBatchSize, HashPinningRequired, LastAuthorizationExpiresAt, LastHTTPStatus e LastError expõem o estado atual sem retornar segredos de OAuth, PIN, OTP ou SAD

Exemplo

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;

Comportamento em caso de falha

Métodos retornam False e definem LastError quando a validação de configuração, transporte, JSON, Base64, X.509, algoritmo, lote, ativação ou contagem de respostas falha

O caminho de assinatura por digest externo verifica independentemente cada assinatura bruta devolvida contra SigningCertificateDER antes de aceitar o PDF

Veja também

OnExternalDigestSign, SetSignProcessExternalDigestSigner, SetSignProcessDigestAlgorithm