TPDFlibCSCClient

Seguridad y firmas

Descripción

Proporciona un cliente síncrono para los puntos de conexión de credenciales, autorización y firma de resúmenes de Cloud Signature Consortium

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

SignDigest implementa TPDFlibExternalDigestSignEvent y puede asignarse directamente a TPDFlib.OnExternalDigestSign, manteniendo dentro de la biblioteca la creación de ByteRange de PDF, los atributos autenticados de CMS, el dimensionamiento del marcador de posición 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 de lote remoto 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

Se comprueba la caducidad y la vinculación del hash del SAD precargado, que 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;

Todos los resúmenes de un lote deben utilizar 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 están codificadas en DER, por lo que no se infiere una salida P1363

Parámetros

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

Propiedades de estado

CredentialLoaded, SigningCertificateDER, CertificateChainCount, SupportedAlgorithmCount, MaxBatchSize, HashPinningRequired, LastAuthorizationExpiresAt, LastHTTPStatus y LastError exponen estado sin secretos OAuth, PIN, OTP o 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 fallos

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 número de respuestas

La ruta de firma de 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