Un placeholder 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 corrida 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 puede tocar: el documento tiene que comprometerse a su distribución final antes de que exista el CMS, y luego esperar, a veces horas, mientras un HSM de red o un servicio de firma en la nube le pide a una persona confirmar 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 regresar. Para una clave en el almacén local, esa es exactamente la forma que usted quiere
Un dispositivo calificado 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 queda detrás de una cola. El intercambio es una conversación: usted envía un digest, algo fuera de su 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 divide en dos llamadas. PreparePadesRemoteSignature produce el PDF preparado y un pequeño registro de petición. CompletePadesRemoteSignature toma el PDF preparado, el registro y el CMS DER retornado, y escribe el archivo firmado. Nada ata las dos llamadas al mismo proceso
Preparar el documento con PreparePadesRemoteSignature
PreparePadesRemoteSignature lee el PDF de origen, adjunta 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 llena de ceros de ancho fijo, los cuatro números del ByteRange se parchean a su 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 agrega
El registro de salida, TPadesRemoteSigningRequest, tiene seis campos: FormatVersion, PreparedFingerprint (SHA-256 de todo el archivo preparado), DocumentDigest, el ByteRange de cuatro elementos, ContentsHexOffset (dónde empiezan los dígitos hex) y ContentsSize. Solo el digest va al servicio de firma. El resto existe para que la segunda llamada pueda probar que está completando los mismos bytes de donde vino el digest
Tres reglas de opciones afectan al archivo preparado, y una cuarta a su build. Cuando CommitmentTypeOid está asignado, 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 entonces tiene que escribir el commitment-type-indication dentro de los atributos firmados del CMS. SigningTimeUtc se convierte en la entrada /M. Las fuentes cifradas se rechazan de plano, así que descifre primero. Las funciones remotas pertenecen a la edición Enterprise: la unidad FPdfPadesRemote debe estar enlazada, de lo contrario los puntos de entrada en FPdfPades lanzan EPdfEnterpriseRequired
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;
// Su propio código: entregue el digest 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, devolviendo False cuando no hay documento activo. La finalización y los helpers de sesión son también métodos de clase en 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 debe cargar en su atributo firmado message-digest. Normalmente no son los bytes que la clave privada firma. 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 puro que solo firma hashes se lo deja a usted. En el segundo caso su 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 firmar el hash. Equivocarse en el orden de ordenamiento produce un CMS que se ve bien y falla la verificación criptográfica; el ordenamiento DER SET OF en atributos firmados CMS recorre esa trampa
Quien quiera que arme el CMS, la finalización acepta una forma específica: un SignedData con exactamente un SignerInfo, detached (sin contenido encapsulado), con atributos firmados content-type y message-digest, un algoritmo de digest distinto de MD5 o SHA-1, y un atributo signing-certificate-v2 válido. Eso coincide con lo que las firmas baseline de PAdES exigen 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 corre todas las revisiones antes de escribir un solo byte al stream de destino, y cada rechazo lanza EPadesCrypto con un mensaje que nombra la revisión fallida. El propio registro de petición se revisa primero: versión de formato 1, fingerprint y digest de 32 bytes, un ContentsSize entre 1024 bytes y 64 MiB, un offset hex positivo. Luego el archivo preparado:
- los offsets registrados deben caer dentro del archivo, y el ByteRange debe alinearse exactamente con el placeholder y la longitud del archivo
- el
<y el>alrededor de/Contentsdeben seguir en su lugar, y cada dígito hex entre ellos debe seguir siendo0 - el SHA-256 de todo el archivo debe ser igual a
PreparedFingerprint, y el hash del ByteRange debe ser igual aDocumentDigest
Luego el CMS: debe ser un único valor DER exacto sin bytes sobrantes, de a lo sumo ContentsSize, de la forma SignedData soportada, con signing-certificate-v2 presente, y por último su atributo message-digest debe ser igual a DocumentDigest
Un archivo preparado regenerado entre fases cambia el fingerprint aunque se vea idéntico en un visor. Una prueba de todo-ceros sobre el placeholder atrapa la doble finalización, donde un reintento escribe un segundo CMS sobre una firma que ya está ahí. La comparación del message-digest atrapa el caso más feo: un CMS correctamente formado de su propio certificado, firmado sobre un documento distinto porque una cola intercambió dos sesiones concurrentes. Ese archivo abriría bien y cargaría una aprobación destinada a otro contrato
La revisión de signing-certificate-v2 va más de conformidad que de integridad. Un CMS sin ella puede verificar criptográficamente y aun así fallar en un validador PAdES, y rechazarla en la finalización mueve ese descubrimiento del reporte de validación de un cliente a sus propios logs. Por qué los validadores rechazan firmas PAdES cubre los demás atributos que los validadores buscan
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; // su propio código: 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); // su propio código: conserve 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 encabezados PEM alrededor. Pase solo el DER decodificado. Un salto de línea final o un byte de encabezado sobrante falla la revisión de único-valor-DER-exacto, que es el resultado buscado: la alternativa es un CMS que parsea con basura detrás
Archivos de sesión entre procesos y máquinas
SavePadesRemoteSigningRequest escribe un registro binario fijo de 120 bytes: un magic PDRSIG01 de 8 bytes, la versión de formato, el offset hex, ContentsSize, los cuatro valores del ByteRange, y luego el digest y el fingerprint. LoadPadesRemoteSigningRequest rechaza cualquier cosa con tamaño equivocado, magic equivocado, datos sobrantes o una versión de formato distinta de 1. El registro no carga material de claves ni contenido del documento, así que guardarlo junto al PDF preparado en una fila de base de datos o en un object store está bien
Eso hace directo el caso de aplicación web. Un manejador de peticiones prepara el archivo y guarda ambos artefactos, el navegador o una app de teléfono aprueba el digest, 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. Reguardarlo mediante una biblioteca PDF, pasarlo por un optimizador, o dejar que una capa de transferencia toque los fines de línea cambian el fingerprint
Un servicio de firma calificado medido por operación cobra por cada operación, así que conviene revisar el archivo almacenado antes de pedir una firma siquiera. El boceto de abajo compara el hash del archivo con PreparedFingerprint usando el System.Hash de la RTL de Delphi; es una revisión que usted agrega, y la finalización la repite de todos modos
uses
System.SysUtils, System.Classes, System.Hash,
FPdfPades, FPdfPadesRemote;
// Verificación preflight sugerida que usted agrega; no es 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 TStream de GetHashBytes necesita un System.Hash reciente de Delphi;
// Lazarus no tiene System.Hash, así que ahí llame su 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 placeholder en el archivo es el doble de caracteres hex, que es por qué el default de 16384 produce los 32,768 ceros del párrafo inicial. Los valores debajo de 1024 se elevan a 1024, un valor arriba de 64 MiB se rechaza al preparar, y la finalización rechaza cualquier CMS de más de ContentsSize bytes
Muy pequeño es el error caro: el servicio ya firmó, la operación está gastada, y el único camino es preparar de nuevo con una ranura más grande y firmar otra vez. Muy grande solo cuesta relleno en cada archivo firmado. Inclínese hacia el lado grande. Suponga que su servicio devuelve un CMS de unos 7,000 bytes con una cadena de tres certificados; el default todavía deja libre más de la mitad de la ranura. Si el servicio además incrusta un token de timestamp de firma o datos de revocación como atributos no firmados, esos aterrizan dentro del mismo CMS y cuentan contra el mismo límite, así que mida una respuesta real de su cadena de producción y dimensione a partir de ahí, con espacio para una cadena de intermedios más larga después
Después de la finalización: B-B, luego LTV y verificación
Una firma remota completada es PAdES B-B. La validación a largo plazo agrega un timestamp de documento y material de validación en una actualización incremental posterior con un DSS y sus diccionarios VRI por firma, descrito en firmas a largo plazo con timestamps RFC 3161 y DSS. Ese paso corre localmente porque los certificados, las respuestas OCSP y las CRL no necesitan la clave privada
Verifique la salida por el mismo camino que tomaría una parte confiable, como cubre inspeccionar firmas digitales y niveles PAdES. En un pipeline remoto el código que arma el CMS vive en el servidor de otro, y el primer lugar donde su salida se encuentra con un validador real debería ser su propio build, antes que sus clientes
Las llamadas de firma remota vienen con la edición Enterprise de PDFium Component para Delphi y Lazarus, junto con el código Pascal nativo de firma PAdES, timestamping y validación. La referencia de la API y las descargas de prueba están en la página del producto PDFium Component