Artículo técnico

Firma PAdES remota en PDFium VCL: HSM y claves en la nube

Un marcador de posición de firma PAdES de 16.384 bytes aparece en el archivo como 32.768 ceros ASCII entre ángulos, y cada byte del PDF fuera de esa tanda ya está cubierto por el hash que el firmante va a aprobar. Esa es la parte incómoda de firmar con una clave que no podéis tocar: el documento tiene que comprometerse a su disposición final antes de que exista el CMS, y luego esperar, a veces durante horas, mientras un HSM de red o un servicio de firma en la nube le pide a una persona que confirme en un teléfono. Lo que le pase al archivo durante esa espera decide si la firma valida

¿Por qué una clave remota no puede usar SignPadesBytes?

La llamada ordinaria asume que la clave privada está al alcance dentro de la llamada. SignPadesBytes en PDFium Component construye la actualización incremental, hashea el ByteRange, firma con el certificado nombrado por CertificateThumbprint en el almacén de Windows y escribe el archivo terminado antes de devolver. Para una clave del almacén local, esa es exactamente la forma que queréis

Un dispositivo cualificado de creación de firma operado por un proveedor de servicios de confianza no funciona así. Tampoco una API de firma en la nube con un paso de segundo factor, o un HSM que vive detrás de una cola. El intercambio es una conversación: enviáis un resumen, algo fuera de vuestro proceso autentica a un humano, y un CMS llega más tarde, en otro hilo, en otro manejador de peticiones, quizá en otro servidor. Una llamada síncrona solo puede modelar eso bloqueando un hilo en el teléfono de alguien

Así que la ruta remota se parte en dos llamadas. PreparePadesRemoteSignature produce el PDF preparado y un pequeño record de petición. CompletePadesRemoteSignature toma el PDF preparado, el record y el CMS DER devuelto, y escribe el archivo firmado. Nada ata las dos llamadas al mismo proceso

Preparar el documento con PreparePadesRemoteSignature

PreparePadesRemoteSignature lee el PDF de origen, añade una actualización incremental con un widget de firma invisible en la primera página y escribe un diccionario de firma con /Filter /Adobe.PPKLite y /SubFilter /ETSI.CAdES.detached. La entrada /Contents se rellena con ceros de ancho fijo, los cuatro números del ByteRange se parchean alrededor y el SHA-256 sobre esos dos rangos se convierte en Request.DocumentDigest. Los bytes originales del archivo de origen quedan intactos; la actualización solo añade

El record de salida, TPadesRemoteSigningRequest, tiene seis campos: FormatVersion, PreparedFingerprint (SHA-256 del archivo preparado entero), DocumentDigest, el ByteRange de cuatro elementos, ContentsHexOffset (dónde empiezan los dígitos hexadecimales) y ContentsSize. Solo el resumen viaja al servicio de firma. El resto existe para que la segunda llamada pueda demostrar que está completando los mismos bytes de los que salió el resumen

Tres reglas de opciones afectan al archivo preparado, y una cuarta a vuestra compilación. Cuando CommitmentTypeOid está fijado, el diccionario no lleva /Reason, porque ETSI EN 319 142-1 trata el tipo de compromiso del CMS y la razón del PDF como alternativas; el servicio de firma tiene entonces que escribir la commitment-type-indication dentro de los atributos firmados del CMS. SigningTimeUtc se convierte en la entrada /M. Los orígenes cifrados se rechazan sin más, así que descidad primero. Las funciones remotas pertenecen a la edición Enterprise: la unidad FPdfPadesRemote tiene que estar enlazada, de lo contrario los puntos de entrada de FPdfPades lanzan EPdfEnterpriseRequired

Flujo en dos fases de firma PAdES remota con PDFium en Delphi donde PreparePadesRemoteSignature reserva el hueco del CMS y entrega el resumen del documento a un HSM o servicio en la nube, y CompletePadesRemoteSignature incrusta el CMS devuelto en cualquier proceso o máquina más tarde
La fase uno reserva el hueco del CMS y entrega el resumen del documento; la fase dos incrusta el CMS que vuelve del HSM o de la clave en la nube
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // enlaza la implementación Enterprise

var
  Options: TPadesRemoteSignOptions;
  Request: TPadesRemoteSigningRequest;
  Source, Prepared, Session: TFileStream;
begin
  Options := TPadesRemoteSignOptions.Default;   // ContentsSize = 16384
  Options.Reason := 'Approved by finance';
  Options.Location := 'Lisbon';
  Options.Name := 'A. Moreira';
  Options.SigningTimeUtc := TTimeZone.Local.ToUniversalTime(Now);

  Source := TFileStream.Create('contract.pdf', fmOpenRead or fmShareDenyWrite);
  Prepared := TFileStream.Create('contract.prepared.pdf', fmCreate);
  try
    PreparePadesRemoteSignature(Source, Prepared, Options, Request);
  finally
    Prepared.Free;
    Source.Free;
  end;

  Session := TFileStream.Create('contract.signreq', fmCreate);
  try
    SavePadesRemoteSigningRequest(Session, Request);
  finally
    Session.Free;
  end;

  // Código vuestro: entregar el resumen de 32 bytes al HSM o a la API de firma
  SendDigestToSigningService(Request.DocumentDigest);
end;

Si el documento ya está abierto en un componente TPdf, TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) guarda el estado actual y prepara a partir de él, y devuelve False cuando no hay ningún documento activo. La finalización y los ayudantes de sesión son también métodos de clase sobre TPdf, así que la segunda fase no necesita ningún documento cargado

Lo que el servicio de firma tiene que devolver

Los 32 bytes de DocumentDigest son el valor que el CMS tiene que llevar en su atributo firmado message-digest. Normalmente no son los bytes que firma la clave privada. RFC 5652 §5.4 dice que cuando hay atributos firmados, la firma se calcula sobre la codificación DER del conjunto de atributos, así que un servicio que devuelve un CMS completo hace ese paso por su cuenta, mientras que un HSM desnudo que solo firma hashes os lo deja a vosotros. En el segundo caso vuestro código construye los SignedAttributes (content-type, message-digest, signing-certificate-v2), los codifica en DER como un SET OF con miembros ordenados, hashea eso y le pide al HSM que firme el hash. Equivocarse en el orden de ordenación produce un CMS que parece correcto y falla la verificación criptográfica; la ordenación DER SET OF en atributos firmados CMS recorre esa trampa

Quienquiera que ensamble el CMS, la finalización acepta una forma concreta: un SignedData con exactamente un SignerInfo, detached (sin contenido encapsulado), con atributos firmados content-type y message-digest, un algoritmo de resumen distinto de MD5 o SHA-1, y un atributo signing-certificate-v2 válido. Eso coincide con lo que exigen las firmas baseline PAdES bajo ETSI EN 319 142-1, así que un servicio que ya produce salida CAdES compatible con PAdES encaja sin trabajo extra

¿Qué rechaza CompletePadesRemoteSignature?

CompletePadesRemoteSignature ejecuta todas las comprobaciones antes de escribir un solo byte en el flujo de destino, y cada rechazo lanza EPadesCrypto con un mensaje que nombra la comprobación fallida. El propio record de petición se comprueba primero: versión de formato 1, huella y resumen de 32 bytes, una ContentsSize entre 1024 bytes y 64 MiB, un offset hexadecimal positivo. Luego el archivo preparado:

  1. los offsets registrados deben caer dentro del archivo, y el ByteRange debe alinearse exactamente con el marcador de posición y la longitud del archivo
  2. el < y el > alrededor de /Contents deben seguir en su sitio, y cada dígito hexadecimal entre ellos debe seguir siendo 0
  3. el SHA-256 del archivo entero debe igualar PreparedFingerprint, y el hash del ByteRange debe igualar DocumentDigest

Luego el CMS: debe ser un único valor DER exacto sin bytes de sobra, de longitud no mayor que ContentsSize, de la forma de SignedData soportada, con signing-certificate-v2 presente, y por último su atributo message-digest debe igualar DocumentDigest

Un archivo preparado regenerado entre fases cambia la huella aunque se vea idéntico en un visor. Un test de todo-ceros sobre el marcador de posición caza la doble finalización, donde un reintento escribe un segundo CMS encima de una firma que ya está ahí. La comparación del message-digest caza el caso más sucio: un CMS correctamente formado con vuestro propio certificado, firmado sobre un documento distinto porque una cola intercambió dos sesiones concurrentes. Ese archivo abriría bien y llevaría una aprobación destinada a otro contrato

La comprobación signing-certificate-v2 va más de conformidad que de integridad. Un CMS sin ella puede verificar criptográficamente y aun así suspender un validador PAdES, y rechazarla en la finalización mueve ese descubrimiento del informe de validación de un cliente a vuestros propios logs. Por qué los validadores rechazan firmas PAdES cubre los demás atributos que buscan los validadores

Diagrama de compuerta de validación de finalización para firma PAdES remota con PDFium en Delphi donde CompletePadesRemoteSignature comprueba la integridad del archivo, la forma del CMS y la conformidad PAdES, y solo escribe el PDF firmado cuando todas las comprobaciones pasan
CompletePadesRemoteSignature valida integridad, forma del CMS y conformidad PAdES antes de escribir un solo byte
var
  Request: TPadesRemoteSigningRequest;
  Session, Prepared, Dest: TFileStream;
  CmsDer: TBytes;
begin
  Session := TFileStream.Create('contract.signreq', fmOpenRead);
  try
    Request := LoadPadesRemoteSigningRequest(Session);
  finally
    Session.Free;
  end;

  CmsDer := FetchDetachedCmsFromService;   // código vuestro: bytes DER, no Base64

  Prepared := TFileStream.Create('contract.prepared.pdf', fmOpenRead);
  try
    Dest := TFileStream.Create('contract.signed.pdf', fmCreate);
    try
      try
        CompletePadesRemoteSignature(Prepared, Dest, Request, CmsDer);
      except
        on E: EPadesCrypto do
          FailSession(E.Message);   // código vuestro: conservar el mensaje exacto
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Muchas APIs de firma devuelven el CMS como Base64 dentro de JSON, a veces con cabeceras PEM alrededor. Pasad solo el DER decodificado. Un salto de línea final o un byte de cabecera sobrante falla la comprobación de un-único-valor-DER-exacto, que es el resultado pretendido: la alternativa es un CMS que parsea con basura detrás

Archivos de sesión entre procesos y máquinas

SavePadesRemoteSigningRequest escribe un record binario fijo de 120 bytes: una magia PDRSIG01 de 8 bytes, la versión de formato, el offset hexadecimal, ContentsSize, los cuatro valores del ByteRange y luego el resumen y la huella. LoadPadesRemoteSigningRequest rechaza cualquier cosa con tamaño equivocado, magia equivocada, datos sobrantes o una versión de formato distinta de 1. El record no guarda material de claves ni contenido del documento, así que almacenarlo junto al PDF preparado en una fila de base de datos o en un object store está bien

Eso hace que el caso de la aplicación web sea directo. Un manejador de peticiones prepara el archivo y guarda los dos artefactos, el navegador o una app de teléfono aprueba el resumen, y un manejador de callback en otro nodo carga la sesión y la completa. La restricción está en el PDF preparado: tiene que volver byte por byte. Volver a guardarlo con una biblioteca PDF, pasarlo por un optimizador o dejar que una capa de transporte toque los fines de línea cambian la huella

Un servicio de firma cualificada de pago por operación cobra por cada operación, así que conviene comprobar el archivo almacenado antes de pedir una firma siquiera. El esbozo de abajo compara el hash del archivo con PreparedFingerprint usando el System.Hash de la RTL de Delphi; es una comprobación que añadís vosotros, y la finalización la repite de todas formas

uses
  System.SysUtils, System.Classes, System.Hash,
  FPdfPades, FPdfPadesRemote;

// Comprobación preflight sugerida que añadís vosotros; no forma parte del componente
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // La sobrecarga sobre TStream de GetHashBytes necesita un System.Hash de Delphi reciente;
    // Lazarus no tiene System.Hash, así que allí llamad a vuestra propia rutina SHA-256
    H := THashSHA2.GetHashBytes(S);   // SHA-256 por defecto
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

Dimensionar ContentsSize antes de que exista el CMS

ContentsSize cuenta bytes de CMS DER. El marcador de posición en el archivo lleva el doble de caracteres hexadecimales, que es por qué el valor por defecto de 16384 produce los 32.768 ceros del párrafo inicial. Los valores por debajo de 1024 se elevan a 1024, un valor por encima de 64 MiB se rechaza en la preparación, y la finalización rechaza cualquier CMS de más de ContentsSize bytes

Demasiado pequeño es el error caro: el servicio ya ha firmado, la operación está gastada y el único camino adelante es preparar de nuevo con un hueco mayor y volver a firmar. Demasiado grande solo cuesta relleno en cada archivo firmado. Inclináos hacia el lado grande. Suponed que vuestro servicio devuelve un CMS de unos 7.000 bytes con una cadena de tres certificados; el valor por defecto todavía deja libre más de la mitad del hueco. Si el servicio además incrusta un token de sello de tiempo de firma o datos de revocación como atributos no firmados, esos caen dentro del mismo CMS y cargan contra el mismo límite, así que medid una respuesta real de vuestra cadena de producción y dimensionad a partir de ella, con margen para una cadena intermedia más larga más adelante

Tras la finalización: B-B, luego LTV y verificación

Una firma remota completada es PAdES B-B. La validación a largo plazo añade un sello de tiempo de documento y material de validación en una actualización incremental posterior con un DSS y sus diccionarios VRI por firma, descrita en firmas a largo plazo con sellos de tiempo RFC 3161 y DSS. Ese paso corre en local porque los certificados, las respuestas OCSP y las CRL no necesitan la clave privada

Verificad la salida con la misma ruta que tomaría un tercero que confía en la firma, como cubre la inspección de firmas digitales y niveles PAdES. En un pipeline remoto el código que construye el CMS vive en el servidor de otro, y el primer sitio donde su salida se encuentra con un validador de verdad debería ser vuestra propia compilación, por delante de vuestros clientes

Las llamadas de firma remota se entregan con la edición Enterprise de PDFium Component para Delphi y Lazarus, junto con el código nativo Pascal de firma, sellado de tiempo y validación PAdES. La referencia de la API y las descargas de prueba están en la página del producto PDFium Component