TPDFlibCSCClient

Segurança e assinaturas

Descrição

Fornece um cliente síncrono para os pontos finais de credenciais, autorização e assinatura de resumos do Cloud Signature Consortium

O cliente obtém o certificado de assinatura e os OIDs dos algoritmos suportados em credentials/info, obtém os dados de ativação da assinatura em credentials/authorize e envia um ou mais resumos já calculados para signatures/signHash

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

Unit

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 tem de ser concluído com êxito antes das chamadas de autorização direta ou assinatura em lote

O certificado de assinatura é exposto através de SigningCertificateDER, os certificados adicionais através de CertificateChainCount e GetCertificateChainDER, e o limite de lote remoto através de MaxBatchSize

Autorização

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;

Para credenciais com HashPinningRequired=True, a matriz de resumos é obrigatória e tem de conter exatamente NumSignatures valores

O SAD pré-obtido é verificado quanto à expiração e vinculação 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;

Todos os resumos dum lote têm de utilizar o mesmo algoritmo e ter o comprimento exato implícito em DigestAlgorithm

SignatureAlgorithm suporta PDF_EXTERNAL_SIGNATURE_RSA_PKCS1 e PDF_EXTERNAL_SIGNATURE_ECDSA_DER; as assinaturas CSC ECDSA são codificadas em DER, pelo que a saída P1363 não é inferida

Parâmetros

ServiceURL	URL base do serviço antes de `/csc/<version>`
APIVersion	Segmento da versão do ponto final, predefinição `v1`
CredentialID	Identificador de credencial definido pelo fornecedor
OAuthToken	Token de portador só de escrita, adicionado a todos os pedidos do transporte predefinido
TimeoutMS	Tempo limite do pedido, 300000 milissegundos por predefinição
MaxResponseBytes	Tamanho máximo de resposta aceite, predefinição de 8 MiB
ClientData	Valor opcional definido pelo fornecedor enviado com os pedidos de assinatura
AuthorizationPIN	PIN só de escrita utilizado pela autorização automática de chamadas de retorno
AuthorizationOTP	Palavra-passe de utilização única só de escrita, eliminada após a autorização da chamada de retorno
AuthorizationDescription	Descrição opcional utilizada pela autorização automática da chamada de retorno
OnTransport	Chamada de retorno opcional de transporte para mTLS, proxy, integração específica do fornecedor ou testes determinísticos

Propriedades de estado

CredentialLoaded, SigningCertificateDER, CertificateChainCount, SupportedAlgorithmCount, MaxBatchSize, HashPinningRequired, LastAuthorizationExpiresAt, LastHTTPStatus e LastError expõem o estado atual sem devolver segredos 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

Os métodos devolvem False e definem LastError quando falha a validação da configuração, transporte, JSON, Base64, X.509, algoritmo, lote, ativação ou número de respostas

O caminho de assinatura de resumos externos verifica de forma independente cada assinatura em bruto devolvida face a SigningCertificateDER antes de aceitar o PDF

Consulte também

OnExternalDigestSign, SetSignProcessExternalDigestSigner, SetSignProcessDigestAlgorithm