Artículo técnico

Signature wrapping en PDF: ByteRange y segundas firmas

Un PDF firmado puede llevar una página falsificada, pasar un check de digest CMS y reportar que su firma cubre el documento entero, todo al mismo tiempo. Cada byte firmado se queda exactamente como lo dejó el firmante, el /ByteRange sigue empezando en 0 y acabando en el tamaño del archivo, y los objetos extra se sientan en el único tramo del archivo que una firma PDF deja deliberadamente fuera del digest: el espacio reservado para el hex string del /Contents

Ese tramo es más grande de lo que la gente imagina. Reservar 8.192 bytes para el contenedor CMS pone 16.384 dígitos hex en el disco, y la parte que la firma real no usa va rellenada con el dígito 0. Un verificador que solo pregunta si el hueco entre los dos rangos es no vacío jamás mira lo que el hueco contiene. La misma pregunta de disposición aparece desde la dirección contraria cuando un contrato necesita una contrafirma: la firma del aprobador tiene que añadirse sin tocar un solo byte que el proveedor firmó, y su placeholder tiene que acabar exactamente en la forma que acepta un verificador estricto

Qué tiene que contener el hueco del ByteRange

El hueco tiene que contener el valor /Contents completo y nada más. ISO 32000-1 §12.8.3.3 dice que el hex string, con sus delimitadores < y >, encaja con precisión en el espacio entre los dos rangos de bytes, e ISO 32000-2 §12.8.1 arrastra la misma regla hacia delante. La Tabla 252 y los documentos PAdES lo formulan de forma más laxa, diciendo solo que el digest excluye el valor de Contents. Leído rápido, eso suena a "excluye los dígitos hex", y un firmante que sigue la lectura laxa hashea los dos paréntesis angulares junto con todo lo demás. Los validadores que comparan el hueco contra el valor de la firma marcan entonces el byte range como inválido

HotPDF sigue la redacción de §12.8.3.3 en ambas rutas de firma. THotPDF.PreparePDFForSigning termina el primer rango inmediatamente antes de < y arranca el segundo inmediatamente después de >, y la preparación en streaming dentro del pipeline de firma CMS calcula los mismos offsets. El placeholder /ByteRange en el diccionario de firma es una cadena literal de anchura fija, así que parchear los números reales nunca desplaza un byte y la tabla de referencias cruzadas se mantiene válida. Cada uno de los cuatro valores va alineado a la derecha en un campo de diez caracteres, que es la razón por la que un archivo firmado así muestra /ByteRange [ seguido de carreras de espacios. Ese padding lo pagamos una vez mientras manejábamos un verificador independiente propio: la primera versión partía los cuatro números por espacios simples y no encontraba nada, y el hex del /Contents solo producía los bytes CMS reales después de quitar su padding de ceros final

Dos bytes bastan para comprobar tú mismo cualquier archivo firmado, sea quien sea que lo produjera. El byte en el offset ByteRange[1] tiene que ser <, y el byte en el offset ByteRange[2] - 1 tiene que ser >. El helper de abajo no forma parte de la librería; son una docena de líneas que puedes meter en una herramienta de auditoría, alimentadas con el array ByteRange de GetLoadedSignatureInfo

// Helper sugerido para tu propio código de auditoría, no es una API de HotPDF
function GapIsSpecLayout(const FileName: string;
  const BR: array of Int64): Boolean;
var
  FS: TFileStream;
  B: AnsiChar;
begin
  Result := False;
  if Length(BR) <> 4 then Exit;
  FS := TFileStream.Create(FileName, fmOpenRead or fmShareDenyWrite);
  try
    FS.Position := BR[1];               // primer byte del hueco
    if (FS.Read(B, 1) <> 1) or (B <> '<') then Exit;
    FS.Position := BR[2] - 1;           // último byte del hueco
    if (FS.Read(B, 1) <> 1) or (B <> '>') then Exit;
    Result := True;
  finally
    FS.Free;
  end;
end;

// Uso, tras Pdf.LoadFromFile('Signed.pdf'):
//   if not GapIsSpecLayout('Signed.pdf',
//     Pdf.GetLoadedSignatureInfo(0).ByteRange) then
//     Writeln('Brackets sit inside the signed ranges');

Para la mitad criptográfica, OpenSSL verifica el CMS de forma independiente: concatena los dos rangos en un archivo y pásalo como contenido externo, por ejemplo openssl cms -verify -binary -inform DER -in contents.der -content signed-ranges.bin -noverify. Ese comando comprueba el digest y la firma sobre exactamente los bytes que le entregas. Nunca ve el hueco, así que el check de dos bytes de arriba sigue siendo cosa tuya

Anatomía de un ByteRange de firma PDF correctamente rellenado en HotPDF: el primer rango cubre el archivo desde el byte cero, el hueco guarda el hex string de /Contents completo con los delimitadores de menor que y mayor que, el segundo rango cubre el trailer hasta el final, y dos comprobaciones de un byte en ByteRange[1] y ByteRange[2] - 1 confirman la disposición en cualquier archivo firmado
Los delimitadores quedan fuera de los rangos firmados, así que el digest cubre solo los dígitos y el hueco se puede validar byte a byte

¿Por qué una comprobación de hueco no vacío se pierde el signature wrapping?

Un hueco no vacío solo prueba que algo quedó fuera del digest y no dice nada sobre qué. Esa es toda la superficie de ataque. El placeholder del /Contents se reserva con miles de dígitos cero, y un contenedor CMS real rara vez lo llena. Un atacante cierra el hex string antes de tiempo dentro de ese padding con un >, escribe objetos nuevos o una revisión falsificada entera en el resto del espacio reservado, y deja los rangos de bytes intactos. El CMS sigue verificando, porque cada byte firmado no cambia. Los rangos siguen yendo de 0 al tamaño del archivo. Un verificador que se pare en "el hueco es no vacío" reporta svValid con CoversWholeDocument puesto en True, mientras que cualquier parser PDF que abra el archivo sigue los objetos que se sienten en el agujero sin firmar

THotPDF.VerifyLoadedSignatureEx trata el hueco como datos que validar. Una vez que el check del CMS pasa, el verificador lee el hueco, quita los delimitadores y acepta solo dígitos hex más los cinco bytes de espacio en blanco PDF (tabulador, salto de línea, form feed, retorno de carro, espacio). Los dígitos decodificados tienen entonces que igualar byte a byte el /Contents del propio diccionario de firma. Un > suelto, un byte binario, o un valor decodificado un byte más largo o más corto vuelve el resultado svInvalidByteRange, y también un hueco mayor de 64 MiB. El mismo check corre en ValidateLoadedSignatureBatch; VerifyAllLoadedSignatures y VerifyLoadedSignatureWithTrust pasan por el camino de firma única, así que también lo heredan

Una disposición se deja pasar deliberadamente: archivos cuyo firmante mantuvo los paréntesis dentro de los rangos firmados, de modo que el hueco guarda solo los dígitos. Para esos, el verificador confirma que el byte justo antes del hueco es < y el byte justo después es >, y luego aplica el mismo test de dígitos-y-espacios. Rechazar esa disposición no compraría ninguna seguridad, porque el hueco sigue sin contener nada salvo el valor de la firma, y haría fallar contratos archivados perfectamente intactos. Aceptarla es el default correcto

Cómo explota el signature wrapping un ByteRange PDF poco comprobado en Delphi: el atacante cierra el hex string antes de tiempo dentro de miles de dígitos cero reservados, escribe una revisión falsificada en el hueco sin firmar sin tocar ningún byte cubierto, y una comprobación de hueco no vacío aún reporta svValid con CoversWholeDocument en true, que es por lo que HotPDF valida el hueco byte a byte
Un hueco no vacío solo prueba que algo quedó fuera del digest, no qué — el agujero relleno de ceros es toda la superficie de ataque
var
  Pdf: THotPDF;
  Info: THPDFSignatureInfo;
  Status: THPDFSignatureVerifyStatus;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.LoadFromFile('SignedTwice.pdf');
    for I := 0 to Pdf.GetLoadedSignatureFieldCount - 1 do
    begin
      Status := Pdf.VerifyLoadedSignatureEx(I, Info);
      case Status of
        svValid:
          if Info.CoversWholeDocument then
            Writeln(Info.FieldName, ': valid, covers the whole file')
          else
            Writeln(Info.FieldName, ': valid, ',
              Info.UnsignedTrailingBytes, ' bytes appended later');
        svInvalidByteRange:
          Writeln(Info.FieldName, ': ByteRange gap rejected (wrapping?)');
        svSourceUnavailable:
          Writeln('Loaded from a stream: use the TStream overload');
      else
        Writeln(Info.FieldName, ': failed, status ', Ord(Status));
      end;
    end;
  finally
    Pdf.Free;
  end;
end;

Tanto GetLoadedSignatureFieldCount como el índice pasado a VerifyLoadedSignatureEx cuentan campos de firma en orden de campos de formulario, empezando en 0. En un archivo contradado la firma del proveedor cae en la primera rama con CoversWholeDocument = False y un UnsignedTrailingBytes positivo: todo lo añadido después de ella, la revisión del aprobador incluida. Si lo básico de esta API es nuevo para ti, la guía para verificar firmas digitales PDF con HotPDF cubre los valores de estado y el record de información con más profundidad

Contratar con AddLoadedSignedSignatureField

Una contrafirma lleva cuatro llamadas: abrir el archivo firmado con BeginIncrementalUpdate, añadir el campo con AddLoadedSignedSignatureField, escribir la nueva revisión con SaveIncrementalUpdate, y firmar luego el archivo preparado con la class function THotPDF.SignPDFWithPFX. El THPDFPage.AddSignedSignatureField de nivel de página no aplica aquí, porque CurrentPage es nil durante una actualización incremental; el documento está cargado, no en disposición. El método de documento cargado crea el widget en una página existente y cuelga bajo /V el mismo diccionario de placeholder de firma que construye la vía de documento nuevo, así que ambas rutas de firma ven bytes idénticos. Para la primera firma en sí, el artículo sobre crear firmas digitales PAdES en Delphi recorre el pipeline de PFX

var
  Pdf: THotPDF;
  FieldIndex: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.BeginIncrementalUpdate('Signed.pdf');
    // Página 0, rectángulo del widget en puntos, 8192 bytes reservados para el CMS
    FieldIndex := Pdf.AddLoadedSignedSignatureField(0, 320, 60, 520, 120,
      'ApproverSignature', 8192, 'adbe.pkcs7.detached',
      'Approved for payment', 'Head office');
    if FieldIndex < 0 then
      raise Exception.Create('Page index out of range');
    Pdf.SaveIncrementalUpdate('Prepared.pdf');
  finally
    Pdf.Free;
  end;

  // Firma el primer placeholder sin rellenar; lanza ante errores de PFX o de cripto
  if not THotPDF.SignPDFWithPFX('Prepared.pdf', 'SignedTwice.pdf',
    'approver.pfx', 'pfx-password') then
    raise Exception.Create('Second signature failed');
end;

La lista de parámetros es corta pero cada valor tiene un efecto visible. ContentsBytes hace default a 8192 y dimensiona el contenedor CMS decodificado; el placeholder en el disco guarda el doble de dígitos hex, con un suelo de 64 bytes. SubFilter hace default a adbe.pkcs7.detached, y Reason, Location y ContactName acaban en el diccionario de firma como /Reason, /Location y /ContactInfo, junto a una marca de tiempo /M tomada cuando se crea el campo. El valor de retorno es el índice del campo nuevo, o -1 cuando el índice de página está fuera de rango. Un nombre de campo vacío o un rectángulo con anchura o altura cero lanza una excepción antes de escribir nada

Qué lleva la revisión añadida, y qué deja tranquilo

AddLoadedSignedSignatureField es deliberadamente más silencioso que sus hermanos. Los demás creadores de campos AddLoaded* ponen /NeedAppearances true en el AcroForm, lo que pide a un visor que regenere las appearances de los campos cuando abre el archivo. Sobre un documento firmado, esa regeneración puede reescribir contenido que el primer firmante cubrió. Así que el método nuevo quita el flag otra vez siempre que el archivo origen no lo llevara ya, y un archivo que llegó con /NeedAppearances lo conserva exactamente como estaba. /SigFlags conserva sus bits existentes y gana el 3, que es SignaturesExist (1) más AppendOnly (2) de ISO 32000-1 §12.7.2, Tabla 219

Deja MarkDirty tranquilo para la página. En modo incremental, los objetos recién creados se escriben automáticamente, y los objetos cargados se escriben solo cuando algo los marca. Añadir el widget al /Annots de la página y al /Fields del AcroForm ya mete en la nueva revisión los objetos indirectos dueños de esos arrays. Una marca de página explícita arrastra el diccionario de página incluso cuando su array /Annots vive en un objeto separado, y el análisis de revisiones reporta entonces una modificación de página en una revisión que no debería contener nada salvo un campo de firma

El diccionario de placeholder escribe /ByteRange antes de /Contents. Ese orden importa si postprocesas el archivo preparado con tus propias herramientas: PreparePDFForSigning encuentra primero el sentinel /ByteRange y luego busca hacia adelante el siguiente /Contents <. Un diccionario con las claves intercambiadas mandaría esa búsqueda hacia adelante más allá de su propio hex string y hacia lo que venga después en el archivo

Cuando el primer firmante aplicó una restricción DocMDP o FieldMDP, SaveIncrementalUpdateAuthenticated es la manera más estricta de escribir la revisión 2. Guarda en un archivo candidato en el mismo directorio, autentica cada firma que lleve una política de transformación, evalúa todas las revisiones después de cada una y publica el candidato solo cuando cada política permite el cambio. Sobre un contrato sin restricciones, el SaveIncrementalUpdate llano hace el trabajo con menos ceremonia

El flujo de HotPDF Delphi para contradar un PDF ya firmado: BeginIncrementalUpdate abre el archivo, AddLoadedSignedSignatureField crea el widget y reserva el placeholder de /Contents, SaveIncrementalUpdate añade una segunda revisión, y SignPDFWithPFX la rellena, dejando la primera firma válida con UnsignedTrailingBytes mientras el nuevo ByteRange abarca todo el archivo crecido
Un placeholder por revisión, preparado y parcheado por la misma serialización en ambas rutas de firma — la disposición limpia que el verificador más estricto espera

Entregar el digest a un firmante externo o a un HSM

En el flujo no cambia nada cuando el CMS viene de una tarjeta inteligente, un HSM o un servicio de firma remoto; solo el último paso cambia. THotPDF.PreparePDFForSigning parchea el /ByteRange en los bytes preparados y devuelve dos rangos 0-based cuyo hueco es el string /Contents entero, más ContentsHexStart, el índice 1-based del primer dígito hex en el AnsiString, y ContentsHexLen. Mezclar offsets de archivo 0-based con índices de string 1-based es el off-by-one clásico de este paso. El ejemplo de abajo afirma ambas posiciones de delimitador antes de hashear nada

var
  Bytes, ToSign, CmsHex: AnsiString;
  R1Start, R1Len, R2Start, R2Len, HexStart, HexLen: Integer;
begin
  Bytes := LoadFileAsAnsiString('Prepared.pdf');   // tu helper
  if not THotPDF.PreparePDFForSigning(Bytes, R1Start, R1Len,
    R2Start, R2Len, HexStart, HexLen) then
    raise Exception.Create('No signature placeholder found');

  // Comprobaciones de cordura sugeridas (tuyas, no llamadas de la librería):
  // '<' termina el rango 1, '>' se sitúa justo antes del rango 2
  Assert(Bytes[R1Start + R1Len + 1] = '<');
  Assert(Bytes[R2Start] = '>');

  ToSign := Copy(Bytes, R1Start + 1, R1Len) + Copy(Bytes, R2Start + 1, R2Len);
  CmsHex := SignDetachedWithHsm(ToSign);           // tu firmante CMS, DER hex
  if not THotPDF.InsertSignatureHexAt(Bytes, HexStart, HexLen, CmsHex) then
    raise Exception.Create('CMS does not fit the reserved space');
  SaveAnsiStringToFile(Bytes, 'SignedTwice.pdf');  // tu helper
end;

Prepara exactamente un placeholder por revisión. PreparePDFForSigning parchea el primer sentinel /ByteRange sin parchear que encuentra, y un segundo placeholder dejado en la misma revisión se sienta dentro de los bytes que la primera firma cubre, así que rellenarlo después rompe esa firma. Para escribir el CMS de vuelta, InsertSignatureHexAt con los offsets devueltos es la llamada a usar. InsertSignatureHex busca el primer string /Contents cuyos dígitos sean todos cero, lo que funciona en un archivo con un único placeholder vacío; con offsets en la mano no hay nada que buscar y nada que desajustar. Un CMS más corto se rellena con 0 al final, antes del > de cierre. Uno más largo hace que InsertSignatureHexAt devuelva False sin tocar los bytes del archivo

¿Qué prueba el check del hueco, y qué no?

El check del hueco cierra un agujero concreto. svValid sigue significando integridad de bytes más una firma que coincide con el certificado incrustado en el CMS; si ese certificado encadena hasta un trust anchor que aceptas lo responde VerifyLoadedSignatureWithTrust, con tus trust anchors y tu evidencia de revocación. Sin bytes de origen nada llega siquiera a svValid. VerifyLoadedSignatureEx los lee del archivo desde el que se cargó el documento y devuelve svSourceUnavailable para un documento cargado desde stream, donde la sobrecarga con TStream de VerifyLoadedSignature te los pide a ti

Para la primera firma en un archivo contradado, CoversWholeDocument es correctamente False. Si la revisión añadida solo metió una firma o también cambió páginas es pregunta para AnalyzeLoadedSignatureRevisions, explicado en DocMDP, FieldMDP y análisis de revisiones en HotPDF

La disposición de paréntesis también se filtra en el PDF MAC adjunto definido por ISO TS 32004 (/MACLocation /AttachedToSig), cuyo check compara offsets contra las posiciones exactas de < y > en el archivo. HotPDF acepta allí también ambas disposiciones. Una herramienta hecha en casa que tenga los offsets con paréntesis incluidos incrustados a fuego suele ser lo primero que rompe cuando se cruza con un archivo firmado a la disposición de §12.8.3.3, y correr el helper de dos bytes de la primera sección sobre la salida de tu propia herramienta lleva un minuto

La mayoría de los problemas de firma en esta zona empiezan cuando la herramienta que firma, la que contrata y la que audita discrepan sobre dónde van los paréntesis. HotPDF, el componente PDF nativo para Delphi y C++Builder escribe la disposición de §12.8.3.3 en cada ruta de firma, comprueba el hueco byte a byte en cada camino de verificación, y añade contrafirmas como revisiones incrementales limpias desde una sola API