Artigo Técnico

Signature wrapping em PDF: ByteRange e segunda assinatura

Um PDF assinado pode carregar uma página forjada, passar numa checagem de digest CMS e reportar que a assinatura dele cobre o documento inteiro, tudo ao mesmo tempo. Todo byte assinado permanece exatamente como o signer o deixou, o /ByteRange ainda começa em 0 e termina no tamanho do arquivo, e os objetos extras sentam no único trecho do arquivo que uma assinatura PDF deliberadamente deixa fora do digest: o espaço reservado para a hex string de /Contents

Esse trecho é maior do que a maioria imagina. Reservar 8.192 bytes para o contêiner CMS põe 16.384 dígitos hex no disco, e a parte que a assinatura real não usa é preenchida com o dígito 0. Um verifier que só pergunta se o vão entre as duas faixas é não vazio nunca olha o que o vão guarda. A mesma pergunta de layout aparece na direção oposta quando um contrato precisa de uma contrassinatura: a assinatura do aprovador tem que ser anexada sem tocar um único byte que o fornecedor assinou, e o placeholder dela tem que acabar exatamente na forma que um verifier estrito aceita

O que o gap do ByteRange deve conter

O gap deve guardar o valor completo de /Contents e nada mais. A ISO 32000-1 §12.8.3.3 diz que a string hexadecimal, com os delimitadores < e >, cabe precisamente no espaço entre as duas faixas de bytes, e a ISO 32000-2 §12.8.1 carrega a mesma regra adiante. A Tabela 252 e os documentos PAdES formulam de forma mais frouxa, dizendo só que o digest exclui o valor de Contents. Lida rápido, isso soa como "excluir os dígitos hex", e um signer que segue a leitura frouxa faz hash dos dois colchetes angulares junto com todo o resto. Validators que comparam o gap com o valor da assinatura então sinalizam o byte range como inválido

O HotPDF segue a redação da §12.8.3.3 nas duas rotas de assinatura dele. O THotPDF.PreparePDFForSigning termina a primeira faixa imediatamente antes do < e começa a segunda imediatamente depois do >, e a preparação em streaming dentro do pipeline de assinatura CMS calcula os mesmos offsets. O placeholder de /ByteRange no dicionário de assinatura é uma string literal de largura fixa, então remendar os números reais não desloca um byte e a tabela de referência cruzada continua válida. Cada um dos quatro valores é alinhado à direita num campo de dez caracteres, por isso um arquivo assinado assim mostra /ByteRange [ seguido de runs de espaços. Pagamos por esse padding uma vez enquanto dirigíamos um verifier standalone nosso: a primeira versão dividia os quatro números em espaços únicos e não achava nada, e o hex de /Contents só produzia os bytes reais do CMS depois que o padding de zeros no fim era removido

Dois bytes bastam para você mesmo checar qualquer arquivo assinado, quem quer que o tenha produzido. O byte no offset ByteRange[1] precisa ser <, e o byte no offset ByteRange[2] - 1 precisa ser >. O helper abaixo não faz parte da biblioteca; são uma dúzia de linhas que você pode soltar numa ferramenta de auditoria, alimentadas com o array ByteRange do GetLoadedSignatureInfo

// Helper sugerido para o seu próprio código de auditoria, não é uma API do 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];               // primeiro byte do gap
    if (FS.Read(B, 1) <> 1) or (B <> '<') then Exit;
    FS.Position := BR[2] - 1;           // último byte do gap
    if (FS.Read(B, 1) <> 1) or (B <> '>') then Exit;
    Result := True;
  finally
    FS.Free;
  end;
end;

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

Para a metade criptográfica, o OpenSSL verifica o CMS de forma independente: concatene as duas faixas num arquivo e passe-o como conteúdo externo, por exemplo openssl cms -verify -binary -inform DER -in contents.der -content signed-ranges.bin -noverify. Esse comando confere o digest e a assinatura sobre exatamente os bytes que você entrega. Ele nunca vê o gap, então a checagem de dois bytes acima continua sendo tarefa sua

Anatomia de um ByteRange de assinatura de PDF corretamente preenchido no HotPDF: a primeira faixa cobre o arquivo desde o byte zero, o gap segura a hex string completa de /Contents incluindo os delimitadores de menor e maior, a segunda faixa cobre o trailer até o fim, e duas checagens de um byte em ByteRange[1] e ByteRange[2] - 1 confirmam o layout em qualquer arquivo assinado
Os delimitadores sentam fora das faixas assinadas, então o digest cobre só os dígitos e o gap pode ser validado byte a byte

Por que uma checagem de gap não vazio não vê o signature wrapping?

Um gap não vazio só prova que algo ficou fora do digest, e não diz nada sobre o quê. Essa é a superfície de ataque inteira. O placeholder de /Contents é reservado com milhares de dígitos zero, e um contêiner CMS real raramente o preenche. Um atacante fecha a hex string cedo dentro desse padding com um >, grava objetos novos ou uma revisão forjada inteira no resto do espaço reservado, e deixa as faixas de bytes intocadas. O CMS ainda verifica, porque todo byte assinado está inalterado. As faixas ainda correm de 0 até o tamanho do arquivo. Um verifier que para em "o gap é não vazio" reporta svValid com CoversWholeDocument em True, enquanto qualquer parser de PDF que abre o arquivo segue o que quer que sente no buraco não assinado

O THotPDF.VerifyLoadedSignatureEx trata o gap como dados a validar. Depois que a checagem CMS passa, o verifier lê o gap, tira os delimitadores e aceita só dígitos hex mais os cinco bytes de whitespace do PDF (tab, line feed, form feed, carriage return, espaço). Os dígitos decodificados então têm que igualar byte a byte o próprio /Contents do dicionário de assinatura. Um > perdido, um byte binário, ou um valor decodificado um byte mais longo ou mais curto vira svInvalidByteRange, e um gap maior que 64 MiB também. A mesma checagem roda no ValidateLoadedSignatureBatch; o VerifyAllLoadedSignatures e o VerifyLoadedSignatureWithTrust passam pelo caminho de assinatura única, então o herdam também

Um layout é deliberadamente deixado passar: arquivos cujo signer manteve os colchetes dentro das faixas assinadas, de modo que o gap guarda só os dígitos. Para esses, o verifier confirma que o byte logo antes do gap é < e o logo depois é >, então aplica o mesmo teste de dígitos-e-whitespace. Rejeitar esse layout não compraria segurança nenhuma, já que o gap ainda não contém nada além do valor da assinatura, e falharia contratos arquivados perfeitamente intactos. Aceitá-lo é o default certo

Como o signature wrapping explora um ByteRange de PDF pouco checado em Delphi: o atacante fecha a hex string cedo dentro de milhares de dígitos zero reservados, grava uma revisão forjada no gap sem assinatura sem tocar byte coberto nenhum, e uma checagem de gap não vazio ainda reporta svValid com CoversWholeDocument true, que é por que o HotPDF valida o gap byte a byte
Um gap não vazio só prova que algo ficou fora do digest, não o quê — o buraco com padding é a superfície de ataque inteira
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 o GetLoadedSignatureFieldCount quanto o índice passado ao VerifyLoadedSignatureEx contam campos de assinatura na ordem de form-field, começando em 0. Num arquivo contrassinado, a assinatura do fornecedor cai no primeiro ramo com CoversWholeDocument = False e um UnsignedTrailingBytes positivo: tudo que foi anexado depois dela, a revisão do aprovador incluída. Se o básico dessa API é novo para você, o guia de verificação de assinaturas digitais de PDF com o HotPDF cobre os valores de status e o record de informações em mais profundidade

Contrassinatura com AddLoadedSignedSignatureField

Uma contrassinatura leva quatro chamadas: abrir o arquivo assinado com BeginIncrementalUpdate, adicionar o campo com AddLoadedSignedSignatureField, gravar a nova revisão com SaveIncrementalUpdate, então assinar o arquivo preparado com a class function THotPDF.SignPDFWithPFX. O THPDFPage.AddSignedSignatureField de nível de página não se aplica aqui, porque o CurrentPage é nil durante um incremental update; o documento está carregado, não sendo disposto. O método de documento carregado cria o widget numa página existente e pendura sob o /V o mesmo dicionário de placeholder de assinatura que o caminho de documento novo constrói, então as duas rotas de assinatura veem bytes idênticos. Para a primeira assinatura em si, o artigo sobre criar assinaturas digitais PAdES em Delphi percorre o pipeline de PFX

var
  Pdf: THotPDF;
  FieldIndex: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.BeginIncrementalUpdate('Signed.pdf');
    // Página 0, retângulo do widget em points, 8192 bytes reservados para o 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;

  // Assina o primeiro placeholder não preenchido; levanta exceção em erros de PFX ou cripto
  if not THotPDF.SignPDFWithPFX('Prepared.pdf', 'SignedTwice.pdf',
    'approver.pfx', 'pfx-password') then
    raise Exception.Create('Second signature failed');
end;

A lista de parâmetros é curta, mas cada valor tem efeito visível. ContentsBytes tem default 8192 e dimensiona o contêiner CMS decodificado; o placeholder no disco guarda o dobro de dígitos hex, com piso de 64 bytes. SubFilter tem default adbe.pkcs7.detached, e Reason, Location e ContactName acabam no dicionário de assinatura como /Reason, /Location e /ContactInfo, ao lado de um timestamp /M tirado quando o campo é criado. O valor de retorno é o novo índice de campo, ou -1 quando o índice de página está fora da faixa. Nome de campo vazio ou retângulo de largura ou altura zero levanta exceção antes de qualquer coisa ser gravada

O que a revisão anexada carrega, e o que ela deixa em paz

O AddLoadedSignedSignatureField é deliberadamente mais quieto que os irmãos dele. Os outros criadores de campo AddLoaded* definem /NeedAppearances true no AcroForm, o que pede a um viewer que regenere appearances de campos quando abrir o arquivo. Num documento assinado essa regeneração pode reescrever conteúdo que o primeiro signer cobriu. Então o método novo remove a flag de novo sempre que o arquivo de origem já não a carregava, e um arquivo que chegou com /NeedAppearances a mantém exatamente como estava. O /SigFlags mantém os bits existentes e ganha 3, que é SignaturesExist (1) mais AppendOnly (2) da ISO 32000-1 §12.7.2, Tabela 219

Deixe o MarkDirty da página em paz. Em modo incremental, objetos recém-criados são gravados automaticamente, e objetos carregados só são gravados quando algo os marca. Adicionar o widget ao /Annots da página e ao /Fields do AcroForm já põe na nova revisão os objetos indiretos que são donos desses arrays. Uma marca explícita de página arrasta o dicionário de página junto mesmo quando o array /Annots dele mora num objeto separado, e a análise de revisão então reporta uma modificação de página numa revisão que deveria conter nada além de um campo de assinatura

O dicionário de placeholder grava /ByteRange antes do /Contents. Essa ordem importa se você pós-processa o arquivo preparado com ferramentas suas: o PreparePDFForSigning acha o sentinel de /ByteRange primeiro e então busca adiante pelo próximo /Contents <. Um dicionário com as chaves trocadas mandaria essa busca adiante passar da própria hex string dele e entrar no que vier depois no arquivo

Quando o primeiro signer aplicou uma restrição DocMDP ou FieldMDP, o SaveIncrementalUpdateAuthenticated é o modo mais estrito de gravar a revisão 2. Ele salva para um arquivo candidato no mesmo diretório, autentica toda assinatura que carrega uma política de transform, avalia todas as revisões depois de cada uma, e publica o candidato só quando toda política permite a mudança. Num contrato sem restrição, o SaveIncrementalUpdate simples faz o trabalho com menos cerimônia

O fluxo de trabalho do HotPDF Delphi para contrassinar um PDF já assinado: o BeginIncrementalUpdate abre o arquivo, o AddLoadedSignedSignatureField cria o widget e reserva o placeholder de /Contents, o SaveIncrementalUpdate anexa uma segunda revisão, e o SignPDFWithPFX a preenche, deixando a primeira assinatura válida com UnsignedTrailingBytes enquanto o ByteRange novo cobre o arquivo inteiro já crescido
Um placeholder por revisão, preparado e remendado pela mesma serialização nas duas rotas de assinatura — o layout limpo que o verificador estrito espera

Entregando o digest a um assinador externo ou HSM

Nada no fluxo de trabalho muda quando o CMS vem de um smart card, de um HSM ou de um serviço de assinatura remoto; só o último passo muda. O THotPDF.PreparePDFForSigning remenda o /ByteRange nos bytes preparados e retorna duas faixas 0-based cujo vão é a string /Contents inteira, mais ContentsHexStart, o índice 1-based do primeiro dígito hex no AnsiString, e ContentsHexLen. Misturar offsets de arquivo 0-based com índices de string 1-based é o off-by-one clássico nesse passo. O sample afirma as duas posições de delimitador antes de fazer hash de qualquer coisa

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

  // Checagens de sanidade sugeridas (suas, não chamadas da biblioteca):
  // '<' encerra a faixa 1, '>' senta logo antes da faixa 2
  Assert(Bytes[R1Start + R1Len + 1] = '<');
  Assert(Bytes[R2Start] = '>');

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

Prepare exatamente um placeholder por revisão. O PreparePDFForSigning remenda o primeiro sentinel de /ByteRange não remendado que encontra, e um segundo placeholder deixado na mesma revisão senta dentro dos bytes que a primeira assinatura cobre, então preenchê-lo depois quebra essa assinatura. Para gravar o CMS de volta, o InsertSignatureHexAt com os offsets retornados é a chamada a usar. O InsertSignatureHex busca a primeira string /Contents cujos dígitos são todos zero, o que funciona num arquivo com um único placeholder vazio; com offsets em mãos não há nada a buscar nem a errar. Um CMS mais curto recebe padding de 0 no fim, antes do > de fechamento. Um mais longo faz o InsertSignatureHexAt retornar False sem tocar nos bytes do arquivo

O que a checagem de gap prova, e o que não?

A checagem de gap fecha um buraco específico. svValid ainda significa integridade de bytes mais uma assinatura que bate com o certificado embutido no CMS; se esse certificado encadeia a uma trust anchor que você aceita é respondido pelo VerifyLoadedSignatureWithTrust, com as suas trust anchors e evidências de revogação. Sem os bytes de origem nada chega a svValid de forma alguma. O VerifyLoadedSignatureEx lê os bytes do arquivo de origem e retorna svSourceUnavailable num documento carregado de stream, em que o overload de TStream do VerifyLoadedSignature os recebe de você

Para a primeira assinatura num arquivo contrassinado, o CoversWholeDocument é corretamente False. Se a revisão anexada só acrescentou uma assinatura ou também mudou páginas é pergunta para o AnalyzeLoadedSignatureRevisions, explicado em DocMDP, FieldMDP e análise de revisão no HotPDF

O layout de colchetes também vaza para o PDF MAC anexado definido pela ISO TS 32004 (/MACLocation /AttachedToSig), cuja checagem compara offsets com as posições exatas de < e > no arquivo. O HotPDF aceita os dois layouts ali também. Uma ferramenta caseira que hard-coda offsets inclusivos de colchete costuma ser a primeira a quebrar quando encontra um arquivo assinado no layout da §12.8.3.3, e rodar o helper de dois bytes da primeira seção sobre a saída da sua própria ferramenta leva um minuto

A maior parte do trouble de assinatura nessa área começa quando a ferramenta que assina, a que contrassina e a que audita discordam sobre onde os colchetes vão. O HotPDF, o componente PDF nativo para Delphi e C++Builder grava o layout da §12.8.3.3 em toda rota de assinatura, confere o gap byte a byte em todo caminho de verificação, e anexa contrassinaturas como revisões incrementais limpas a partir de uma única API