Artículo técnico

Signature wrapping en PDF: huecos ByteRange y segunda firma

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

Ese tramo es más grande de lo que la mayoría imagina. Reservar 8.192 bytes para el contenedor CMS pone 16.384 dígitos hex en el disco, y la parte de ellos que la firma real no usa se rellena con el dígito 0. Un verificador que solo pregunta si el hueco entre los dos rangos es no vacío nunca mira qué contiene el hueco. La misma pregunta de layout aparece desde la dirección opuesta cuando un contrato necesita una countersignature: la firma del aprobador tiene que adjuntarse sin tocar un solo byte que el proveedor firmó, y su placeholder tiene que terminar exactamente en la forma que un verificador estricto acepta

Lo que el hueco del ByteRange debe contener

El hueco debe contener el valor completo de /Contents y nada más. ISO 32000-1 §12.8.3.3 dice que el string hexadecimal, con sus delimitadores < y >, calza justo en el espacio entre los dos rangos de bytes, e ISO 32000-2 §12.8.1 arrastra la misma regla hacia adelante. La Tabla 252 y los documentos de PAdES lo redactan de manera más laxa, diciendo solo que el digest excluye el valor de Contents. Leído rápido, eso suena a "excluir los dígitos hex", y un firmador que sigue la lectura laxa hashea los dos angle brackets 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 de sus 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 de /ByteRange en el diccionario de firma es un string literal de ancho fijo, así que parchear los números reales nunca desplaza un byte y la tabla de referencias cruzadas queda válida. Cada uno de los cuatro valores va alineado a la derecha en un campo de diez caracteres, que es por qué un archivo firmado así muestra /ByteRange [ seguido de corridas de espacios. Nosotros pagamos ese padding 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 de /Contents solo produjo los bytes CMS reales después de quitar su padding de ceros final

Dos bytes bastan para revisar usted mismo cualquier archivo firmado, lo haya producido quien lo haya producido. El byte en el offset ByteRange[1] debe ser <, y el byte en el offset ByteRange[2] - 1 debe ser >. El helper de abajo no forma parte de la librería; es una docena de líneas que puede soltar en una herramienta de auditoría, alimentada con el arreglo ByteRange de GetLoadedSignatureInfo

// Helper sugerido para su 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, después de Pdf.LoadFromFile('Signed.pdf'):
//   if not GapIsSpecLayout('Signed.pdf',
//     Pdf.GetLoadedSignatureInfo(0).ByteRange) then
//     Writeln('Los brackets quedan dentro de los rangos firmados');

Para la mitad criptográfica, OpenSSL verifica el CMS de manera independiente: concatene los dos rangos en un archivo y páselo como contenido externo, por ejemplo openssl cms -verify -binary -inform DER -in contents.der -content signed-ranges.bin -noverify. Ese comando revisa el digest y la firma sobre exactamente los bytes que usted le entrega. Nunca ve el hueco, así que el chequeo de dos bytes de arriba sigue siendo trabajo suyo

Anatomía de un ByteRange de firma PDF correctamente rellenado en HotPDF: el primer rango cubre el archivo desde el byte cero, el hueco sostiene el hex string completo de /Contents incluidos los delimitadores menor-que y mayor-que, el segundo rango cubre el trailer hasta el final, y dos chequeos de un byte en ByteRange[1] y ByteRange[2] - 1 confirman el layout 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é un chequeo de hueco no vacío se pierde el signature wrapping?

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

THotPDF.VerifyLoadedSignatureEx trata el hueco como data que hay que validar. Una vez que el chequeo CMS pasa, el verificador lee el hueco, le quita los delimitadores y acepta solo dígitos hex más los cinco bytes de whitespace de PDF (tab, line feed, form feed, carriage return, espacio). Los dígitos decodificados deben entonces igualar byte a byte el propio /Contents del 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 de más de 64 MiB. El mismo chequeo corre en ValidateLoadedSignatureBatch; VerifyAllLoadedSignatures y VerifyLoadedSignatureWithTrust pasan por el camino de firma única, así que lo heredan también

Un layout se deja pasar deliberadamente: archivos cuyo firmador mantuvo los brackets dentro de los rangos firmados, de modo que el hueco contiene 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 la misma prueba de dígitos-y-whitespace. Rechazar ese layout no compraría ninguna seguridad, ya que el hueco igual no contiene nada más que el valor de la firma, y fallaría contratos archivados que están perfectamente intactos. Aceptarlo es el default correcto

Cómo el signature wrapping explota un ByteRange de PDF poco chequeado en Delphi: el atacante cierra el hex string temprano 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 un chequeo de hueco no vacío igual reporta svValid con CoversWholeDocument en true, que es por qué HotPDF valida el hueco byte a byte
Un hueco no vacío solo prueba que algo quedó fuera del digest, no qué — el hueco rellenado 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 que se pasa a VerifyLoadedSignatureEx cuentan campos de firma en orden de campos de formulario, empezando en 0. En un archivo countersignado la firma del proveedor cae en la primera rama con CoversWholeDocument = False y un UnsignedTrailingBytes positivo: todo lo que se adjuntó después de ella, la revisión del aprobador incluida. Si lo básico de esta API le resulta nuevo, la guía de verificación de firmas digitales PDF con HotPDF cubre los valores de estado y el record de información con más profundidad

Countersignar con AddLoadedSignedSignatureField

Una countersignature toma cuatro llamadas: abra el archivo firmado con BeginIncrementalUpdate, agregue el campo con AddLoadedSignedSignatureField, escriba la nueva revisión con SaveIncrementalUpdate, y después firme el archivo preparado con la class function THotPDF.SignPDFWithPFX. El THPDFPage.AddSignedSignatureField de nivel de página no aplica acá, porque CurrentPage es nil durante una actualización incremental; el documento está cargado, no en proceso de maquetación. El método de documento cargado crea el widget sobre una página existente y cuelga bajo /V el mismo diccionario de firma placeholder que construye el camino 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 criptográficos
  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 queda en 8192 por defecto y dimensiona el contenedor CMS decodificado; el placeholder en el disco guarda el doble de dígitos hex, con un piso de 64 bytes. SubFilter queda en adbe.pkcs7.detached por defecto, y Reason, Location y ContactName terminan en el diccionario de firma como /Reason, /Location y /ContactInfo, junto a un timestamp /M tomado 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 de ancho o alto cero lanza una excepción antes de escribir nada

Qué lleva la revisión adjuntada, y qué deja quieto

AddLoadedSignedSignatureField es deliberadamente más silencioso que sus hermanos. Los otros creadores de campos AddLoaded* fijan /NeedAppearances true en el AcroForm, lo que le pide al visor que regenere las apariencias 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 vuelve a quitar el flag siempre que el archivo fuente no lo llevara ya, y un archivo que llegó con /NeedAppearances lo conserva exactamente como estaba. /SigFlags conserva sus bits existentes y gana 3, que es SignaturesExist (1) más AppendOnly (2) de ISO 32000-1 §12.7.2, Tabla 219

Deje MarkDirty quieto 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. Agregar el widget a /Annots de la página y a /Fields del AcroForm ya pone en la nueva revisión los objetos indirectos dueños de esos arreglos. Una marca de página explícita arrastra el diccionario de página aunque su arreglo /Annots viva 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 más que un campo de firma

El diccionario placeholder escribe /ByteRange antes de /Contents. Ese orden importa si usted post-procesa el archivo preparado con sus propias herramientas: PreparePDFForSigning encuentra primero el sentinel /ByteRange y después busca hacia adelante el próximo /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 estricta de escribir la revisión 2. Guarda a un archivo candidato en el mismo directorio, autentica cada firma que lleva una política de transformación, evalúa todas las revisiones después de cada una y publica el candidato solo cuando toda política permite el cambio. En un contrato sin restricciones, el SaveIncrementalUpdate llano hace el trabajo con menos ceremonia

El flujo de trabajo de HotPDF Delphi para countersignar un PDF ya firmado: BeginIncrementalUpdate abre el archivo, AddLoadedSignedSignatureField crea el widget y reserva el placeholder de /Contents, SaveIncrementalUpdate adjunta una segunda revisión, y SignPDFWithPFX la rellena, dejando la primera firma válida con UnsignedTrailingBytes mientras el nuevo ByteRange abarca el archivo entero ya crecido
Un placeholder por revisión, preparado y parchado por la misma serialización en ambas rutas de firma — el layout limpio que el verifier más estricto espera

Entregarle el digest a un firmante externo o un HSM

Nada del flujo de trabajo cambia cuando el CMS viene de una smart card, 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 completo de /Contents, 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 hace assert de 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');   // su helper
  if not THotPDF.PreparePDFForSigning(Bytes, R1Start, R1Len,
    R2Start, R2Len, HexStart, HexLen) then
    raise Exception.Create('No signature placeholder found');

  // Chequeos de cordura sugeridos (suyos, no llamadas de la librería):
  // '<' cierra el rango 1, '>' está 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);           // su firmante CMS, DER en hex
  if not THotPDF.InsertSignatureHexAt(Bytes, HexStart, HexLen, CmsHex) then
    raise Exception.Create('CMS does not fit the reserved space');
  SaveAnsiStringToFile(Bytes, 'SignedTwice.pdf');  // su helper
end;

Prepare 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 ni nada que desemparejar. 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 chequeo del hueco, y qué no?

El chequeo del hueco cierra un agujero específico. svValid sigue significando integridad de bytes más una firma que coincide con el certificado embebido en el CMS; si ese certificado encadena hasta un trust anchor que usted acepta lo responde VerifyLoadedSignatureWithTrust, dados sus trust anchors y evidencia de revocación. Sin bytes de la fuente nada llega a svValid para nada. VerifyLoadedSignatureEx los lee del archivo desde el que se cargó el documento y devuelve svSourceUnavailable para un documento cargado de un stream, donde la sobrecarga TStream de VerifyLoadedSignature se los pide a usted

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

El layout de brackets también se filtra en el PDF MAC adjunto definido por ISO TS 32004 (/MACLocation /AttachedToSig), cuyo chequeo compara offsets contra las posiciones exactas de < y > en el archivo. HotPDF acepta ambos layouts ahí también. Una herramienta casera que tenga hardcodeados offsets inclusivos de brackets suele ser lo primero que se rompe cuando se cruza con un archivo firmado al layout de §12.8.3.3, y correr el helper de dos bytes de la primera sección sobre la salida de su propia herramienta toma un minuto

La mayoría de los problemas de firma en esta área arranca cuando la herramienta que firma, la que countersigna y la que audita discrepan sobre dónde van los brackets. HotPDF, el componente PDF nativo para Delphi y C++Builder escribe el layout de §12.8.3.3 en toda ruta de firma, revisa el hueco byte a byte en cada camino de verificación, y adjunta countersignatures como revisiones incrementales limpias desde una sola API