TPDFlibCSCClient

Seguridad y firmas

Descripción

Proporciona un cliente sincrónico para los puntos de conexión de credenciales, autorización y firma de resúmenes del Cloud Signature Consortium

El cliente recupera el certificado de firma y los OID de algoritmos compatibles desde credentials/info, obtiene los datos de activación de firma desde credentials/authorize y envía uno o más resúmenes ya calculados a signatures/signHash

SignDigest implementa TPDFlibExternalDigestSignEvent y se puede asignar directamente a TPDFlib.OnExternalDigestSign, manteniendo dentro de la biblioteca la creación del PDF ByteRange, los atributos autenticados CMS, el dimensionamiento del espacio reservado y la verificación de la firma devuelta

Unidad

PDFlibCSC

Construcción

Constructor TPDFlibCSCClient.Create;
Destructor TPDFlibCSCClient.Destroy;

Detección de credenciales

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 debe completarse correctamente antes de las llamadas de autorización directa o firma por lotes

El certificado de firma se expone mediante SigningCertificateDER, los certificados adicionales mediante CertificateChainCount y GetCertificateChainDER, y el límite remoto de lote mediante MaxBatchSize

Autorización

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 las credenciales con HashPinningRequired=True, la matriz de resúmenes es obligatoria y debe contener exactamente NumSignatures valores

El SAD precargado se comprueba para verificar vencimiento y vinculación de hash y se consume exactamente una vez

Firma

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;

Cada resumen de un lote debe usar el mismo algoritmo y tener la longitud exacta implícita en DigestAlgorithm

SignatureAlgorithm admite PDF_EXTERNAL_SIGNATURE_RSA_PKCS1 y PDF_EXTERNAL_SIGNATURE_ECDSA_DER; las firmas ECDSA de CSC se codifican en DER, por lo que no se infiere la salida P1363

Parámetros

ServiceURL	URL de servicio base antes de `/csc/<version>`
APIVersion	Segmento de versión del endpoint, `v1` de forma predeterminada
CredentialID	Identificador de credencial definido por el proveedor
OAuthToken	Token de portador de solo escritura que se agrega a cada solicitud de transporte predeterminada
TimeoutMS	Tiempo de espera de la solicitud, valor predeterminado de 300000 milisegundos
MaxResponseBytes	Tamaño máximo de respuesta aceptado, predeterminado: 8 MiB
ClientData	Valor opcional definido por el proveedor que se envía con las solicitudes de firma
AuthorizationPIN	PIN de solo escritura usado por la autorización automática de devolución de llamada
AuthorizationOTP	Contraseña de un solo uso de escritura que se borra después de la autorización de la devolución de llamada
AuthorizationDescription	Descripción opcional usada por la autorización automática de devolución de llamada
OnTransport	Devolución de llamada de transporte opcional para integración de mTLS, proxy, específica de proveedor o pruebas deterministas

Propiedades de estado

CredentialLoaded, SigningCertificateDER, CertificateChainCount, SupportedAlgorithmCount, MaxBatchSize, HashPinningRequired, LastAuthorizationExpiresAt, LastHTTPStatus y LastError exponen el estado actual sin devolver secretos de OAuth, PIN, OTP ni SAD

Ejemplo

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;

Comportamiento ante errores

Los métodos devuelven False y establecen LastError cuando falla la validación de configuración, transporte, JSON, Base64, X.509, algoritmo, lote, activación o cantidad de respuestas

La ruta de firma con resumen externo verifica de forma independiente cada firma sin procesar devuelta con SigningCertificateDER antes de aceptar el PDF

Véase también

OnExternalDigestSign, SetSignProcessExternalDigestSigner, SetSignProcessDigestAlgorithm