Um placeholder de assinatura PAdES de 16.384 bytes aparece no arquivo como 32.768 zeros ASCII entre colchetes angulares, e cada byte do PDF fora dessa sequência já está coberto pelo hash que o signatário vai aprovar. Essa é a parte espinhosa de assinar com uma chave que você não pode tocar: o documento tem que se comprometer com o layout final antes de o CMS existir, e depois esperar, às vezes por horas, enquanto um HSM de rede ou um serviço de assinatura em nuvem pede a uma pessoa que confirme no celular. O que acontecer com o arquivo durante essa espera decide se a assinatura valida
Por que uma chave remota não pode usar SignPadesBytes?
A chamada comum assume que a chave privada está ao alcance dentro da própria chamada. O SignPadesBytes no PDFium Component constrói a atualização incremental, calcula o hash do ByteRange, assina com o certificado apontado por CertificateThumbprint no store do Windows e grava o arquivo pronto antes de retornar. Para uma chave no store local, esse é exatamente o formato que você quer
Um dispositivo qualificado de criação de assinaturas operado por um prestador de serviços de confiança não funciona assim. Nem uma API de assinatura em nuvem com uma etapa de segundo fator, nem um HSM que fica atrás de uma fila. A troca é uma conversa: você envia um digest, algo fora do seu processo autentica um humano, e um CMS chega depois, em outra thread, em outro handler de requisição, talvez em outro servidor. Uma chamada síncrona só consegue modelar isso bloqueando uma thread no celular de alguém
Então o caminho remoto se divide em duas chamadas. PreparePadesRemoteSignature produz o PDF preparado e um pequeno record de requisição. CompletePadesRemoteSignature recebe o PDF preparado, o record e o CMS DER devolvido, e grava o arquivo assinado. Nada prende as duas chamadas ao mesmo processo
Preparando o documento com PreparePadesRemoteSignature
PreparePadesRemoteSignature lê o PDF de origem, anexa uma atualização incremental com um widget de assinatura invisível na primeira página e grava um dicionário de assinatura com /Filter /Adobe.PPKLite e /SubFilter /ETSI.CAdES.detached. A entrada /Contents é preenchida com zeros de largura fixa, os quatro números do ByteRange são ajustados ao redor dela, e o SHA-256 sobre esses dois intervalos vira o Request.DocumentDigest. Os bytes originais do arquivo de origem ficam intocados; a atualização só acrescenta
O record de saída, TPadesRemoteSigningRequest, tem seis campos: FormatVersion, PreparedFingerprint (SHA-256 do arquivo preparado inteiro), DocumentDigest, o ByteRange de quatro elementos, ContentsHexOffset (onde os dígitos hex começam) e ContentsSize. Só o digest vai para o serviço de assinatura. O resto existe para que a segunda chamada possa provar que está completando os mesmos bytes de onde o digest veio
Três regras de opções afetam o arquivo preparado, e uma quarta afeta o seu build. Quando CommitmentTypeOid está definido, o dicionário não carrega /Reason, porque a ETSI EN 319 142-1 trata o commitment type no CMS e o reason do PDF como alternativas; o serviço de assinatura então precisa escrever o commitment-type-indication nos atributos assinados do CMS. SigningTimeUtc vira a entrada /M. Fontes criptografadas são recusadas de cara, então descriptografe antes. As funções remotas pertencem à edição Enterprise: a unit FPdfPadesRemote precisa estar linkada, senão os entry points em FPdfPades levantam EPdfEnterpriseRequired
uses
System.SysUtils, System.Classes, System.DateUtils,
FPdfCrypto, FPdfPades,
FPdfPadesRemote; // liga a implementação 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 seu: entregue o digest de 32 bytes ao HSM ou à API de assinatura
SendDigestToSigningService(Request.DocumentDigest);
end;
Se o documento já estiver aberto em um componente TPdf, TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) salva o estado atual e prepara a partir dele, devolvendo False quando não há documento ativo. A conclusão e os helpers de sessão são class methods no TPdf também, então a segunda fase não precisa de documento carregado nenhum
O que o serviço de assinatura precisa devolver
Os 32 bytes em DocumentDigest são o valor que o CMS precisa carregar no atributo assinado message-digest. Normalmente não são os bytes que a chave privada assina. O RFC 5652 §5.4 diz que, quando atributos assinados estão presentes, a assinatura é calculada sobre a codificação DER do conjunto de atributos, então um serviço que devolve um CMS completo faz essa etapa por conta própria, enquanto um HSM puro que só assina hashes deixa-a para você. No segundo caso o seu código monta os SignedAttributes (content-type, message-digest, signing-certificate-v2), os codifica em DER como um SET OF com membros ordenados, calcula o hash disso e pede ao HSM para assinar o hash. Errar a ordem de ordenação produz um CMS que parece bem e falha na verificação criptográfica; ordenação DER SET OF em atributos assinados CMS percorre essa armadilha
Quem quer que monte o CMS, a conclusão aceita uma forma específica: um SignedData com exatamente um SignerInfo, detached (sem conteúdo encapsulado), com atributos assinados content-type e message-digest, um algoritmo de digest que não seja MD5 ou SHA-1, e um atributo signing-certificate-v2 válido. Isso bate com o que as assinaturas baseline PAdES exigem sob a ETSI EN 319 142-1, então um serviço que já produz saída CAdES compatível com PAdES encaixa sem trabalho extra
O que CompletePadesRemoteSignature recusa?
CompletePadesRemoteSignature roda toda checagem antes de gravar um único byte no stream de destino, e cada recusa levanta EPadesCrypto com uma mensagem que nomeia a checagem que falhou. O próprio record de requisição é checado primeiro: versão de formato 1, fingerprint e digest de 32 bytes, um ContentsSize entre 1024 bytes e 64 MiB, um offset hex positivo. Depois o arquivo preparado:
- os offsets registrados precisam estar dentro do arquivo, e o ByteRange precisa alinhar exatamente com o placeholder e o comprimento do arquivo
- o
<e o>ao redor de/Contentsprecisam continuar no lugar, e cada dígito hex entre eles precisa continuar sendo0 - o SHA-256 do arquivo inteiro precisa ser igual a
PreparedFingerprint, e o hash do ByteRange precisa ser igual aDocumentDigest
Depois o CMS: ele precisa ser um único valor DER exato, sem bytes de sobra, não maior que ContentsSize, da forma de SignedData suportada, com signing-certificate-v2 presente e, por fim, com o atributo message-digest igual a DocumentDigest
Um arquivo preparado regenerado entre as fases muda o fingerprint mesmo quando parece idêntico em um visualizador. O teste de só-zeros no placeholder captura conclusão dupla, em que uma tentativa repetida grava um segundo CMS sobre uma assinatura que já está lá. A comparação do message-digest captura o caso mais intrusivo: um CMS corretamente formado, do seu próprio certificado, assinado sobre um documento diferente porque uma fila trocou duas sessões concorrentes. Esse arquivo abriria bem e carregaria uma aprovação destinada a outro contrato
A checagem de signing-certificate-v2 é sobre conformidade mais do que integridade. Um CMS sem ela pode verificar criptograficamente e ainda assim falhar em um validador PAdES, e recusá-la na conclusão move essa descoberta do relatório de validação de um cliente para os seus próprios logs. Por que validadores rejeitam assinaturas PAdES cobre os outros atributos que os validadores procuram
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 seu: bytes DER, não 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 seu: guarde a mensagem exata
end;
finally
Dest.Free;
end;
finally
Prepared.Free;
end;
end;
Muitas APIs de assinatura devolvem o CMS como Base64 dentro de JSON, às vezes com headers PEM ao redor. Passe só o DER decodificado. Uma quebra de linha no final ou um byte de header esquecido falha na checagem de valor DER único exato, que é o resultado pretendido: a alternativa é um CMS que parseia com lixo depois dele
Arquivos de sessão entre processos e máquinas
SavePadesRemoteSigningRequest grava um record binário fixo de 120 bytes: uma mágica PDRSIG01 de 8 bytes, a versão do formato, o offset hex, ContentsSize, os quatro valores do ByteRange, e então o digest e o fingerprint. LoadPadesRemoteSigningRequest rejeita qualquer coisa com tamanho errado, mágica errada, dados de sobra ou versão de formato diferente de 1. O record não carrega material de chave nem conteúdo de documento, então guardá-lo ao lado do PDF preparado em uma linha de banco de dados ou object store está ok
Isso torna o caso de aplicação web direto. Um handler de requisição prepara o arquivo e guarda os dois artefatos, o navegador ou um app de celular aprova o digest, e um handler de callback em outro nó carrega a sessão e completa. A restrição fica no PDF preparado: ele precisa voltar byte a byte. Re-salvá-lo por uma biblioteca PDF, passá-lo por um otimizador ou deixar uma camada de transferência tocar as quebras de linha mudam o fingerprint
Um serviço de assinatura qualificada cobrado por operação faz com que valha a pena conferir o arquivo guardado antes de pedir uma assinatura sequer. O esboço abaixo compara o hash do arquivo com PreparedFingerprint usando o System.Hash da RTL do Delphi; é uma checagem que você adiciona você mesmo, e a conclusão a repete de qualquer forma
uses
System.SysUtils, System.Classes, System.Hash,
FPdfPades, FPdfPadesRemote;
// Checagem de preflight sugerida, você mesmo adiciona; não faz parte do componente
function PreparedFileStillMatches(const PreparedPath: string;
const Request: TPadesRemoteSigningRequest): Boolean;
var
S: TFileStream;
H: TBytes;
begin
S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
try
// A sobrecarga de TStream de GetHashBytes precisa de um System.Hash recente do Delphi;
// Lazarus não tem System.Hash, então chame lá a sua própria rotina SHA-256
H := THashSHA2.GetHashBytes(S); // SHA-256 por padrão
finally
S.Free;
end;
Result := (Length(H) = Length(Request.PreparedFingerprint)) and
CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;
Dimensionando ContentsSize antes de o CMS existir
ContentsSize conta bytes de CMS DER. O placeholder no arquivo é o dobro disso em caracteres hex, que é por que o default de 16384 produz os 32.768 zeros do parágrafo de abertura. Valores abaixo de 1024 são elevados a 1024, um valor acima de 64 MiB é recusado na preparação, e a conclusão recusa qualquer CMS maior que ContentsSize bytes
Pequeno demais é o erro caro: o serviço já assinou, a operação foi gasta, e o único caminho é preparar de novo com um slot maior e assinar de novo. Grande demais só custa padding em cada arquivo assinado. Penda para o lado grande. Suponha que o seu serviço devolva um CMS de uns 7.000 bytes com uma cadeia de três certificados; o default ainda deixa mais da metade do slot livre. Se o serviço também embutir um token de timestamp de assinatura ou dados de revogação como atributos não assinados, esses caem dentro do mesmo CMS e contam contra o mesmo limite, então meça uma resposta real da sua cadeia de produção e dimensione a partir dela, com folga para uma cadeia de intermediários maior no futuro
Depois da conclusão: B-B, então LTV e verificação
Uma assinatura remota concluída é PAdES B-B. A validação de longo prazo acrescenta um timestamp de documento e material de validação em uma atualização incremental posterior com um DSS e seus dicionários VRI por assinatura, descrito em assinaturas de longo prazo com timestamps RFC 3161 e DSS. Essa etapa roda localmente porque certificados, respostas OCSP e CRLs não precisam da chave privada
Verifique a saída pelo mesmo caminho que uma relying party tomaria, como cobre inspecionando assinaturas digitais e níveis PAdES. Em um pipeline remoto o código que monta o CMS vive no servidor de outra pessoa, e o primeiro lugar em que a saída dele encontra um validador de verdade deveria ser o seu próprio build, antes dos seus clientes
As chamadas de assinatura remota vêm com a edição Enterprise do PDFium Component para Delphi e Lazarus, ao lado do código nativo em Pascal de assinatura PAdES, timestamp e validação. Referência da API e downloads de teste estão na página do produto PDFium Component