Aplicar uma assinatura digital PAdES no NextPDF Connect (Pro)

Visão geral

Aplique uma assinatura digital de linha de base PDF Advanced Electronic Signatures (PAdES) a um PDF no NextPDF Connect. Use sign_pdf, que foi reverificado contra o provedor de ferramentas Pro: esse provedor registra new SignPdfTool(), cujo nome de protocolo é sign_pdf. sign_pdf é uma ferramenta de camada Pro. Na inicialização, o servidor a verifica com class_exists() e a registra apenas quando o pacote Pro está instalado.

Por padrão, a ferramenta gera PAdES B-B. Ela só pode gerar PAdES B-T (B-B mais um RFC 3161 signature-time-stamp) quando o host conectou um provedor de timestamp à ferramenta; a requisição não pode apontar para uma Time Stamp Authority (TSA). Níveis de longo prazo (B-LT, B-LTA) e o respectivo material de validação (DSS, VRI, LTV) não fazem parte desta ferramenta e estão fora do escopo aqui.

Ressalva U-1. O NextPDF não declara nenhuma certificação independente ETSI EN 319 142-1 para PAdES B-T. A EN 319 142-1 não está no corpus de verificação. O requisito de signature-time-stamp de B-T foi verificado em relação à ETSI EN 319 122-1 §5.3 (a base CAdES que a EN 319 142-1/-2 importa por referência), em conjunto com RFC 3161, RFC 5652, RFC 5816 e ISO 32000-2 §12.8. O suporte ao perfil B-T não é uma certificação de conformidade nem de validade jurídica; um validador independente faz essa determinação.

Instalação

composer require nextpdf/server
composer require nextpdf/pro

Vincule um transporte e, depois, confirme que sign_pdf existe com diagnostic.capabilities. Para B-T, o host deve construir a ferramenta com um provedor de timestamp. Sem esse provedor, uma requisição pades_b_t: true falha com um erro tipado em vez de sofrer downgrade silencioso.

Visão conceitual

sign_pdf calcula um digest de byte-range do arquivo, excluindo o placeholder do valor da assinatura (ISO 32000-2 §12.8.1). Em seguida, a ferramenta grava Cryptographic Message Syntax (CMS) SignedData codificado em Distinguished Encoding Rules (DER) no dicionário de assinatura Contents (ISO 32000-2 §12.8.1). Os algoritmos suportados são RSA-SHA256 (padrão), RSA + SHA-3 (256/384/512) e Ed25519. Para transportes que não são confidenciais de ponta a ponta, você pode encapsular o payload de entrada private_key em um envelope AES-GCM opcional.

Upgrade para B-T. Com pades_b_t: true e um provedor de timestamp conectado pelo host, a assinatura é promovida para PAdES B-T: o hash de byte-range é enviado a uma TSA e um TimeStampToken é incorporado (ISO 32000-2 §12.8.5). B-T é exatamente B-B mais um RFC 3161 signature-time-stamp carregado como atributo não assinado no CMS SignerInfo (RFC 5652 §5.3). Atributos não assinados não são cobertos pela assinatura, portanto o digest assinado B-B e sua validade permanecem inalterados (RFC 5652 §5.3). O valor do atributo é um SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T não adiciona nenhum dicionário Document Security Store (DSS), nenhuma Validation Related Information (VRI), nenhum material de validação e nenhum loop de archive-timestamp. Esses itens compõem o delta Enterprise B-LT/B-LTA e estão fora do escopo desta ferramenta.

Ressalva U-1 (repetida na declaração de B-T). O suporte a B-T aqui não constitui uma certificação de conformidade EN 319 142-1 nem de validade jurídica; um validador independente determina isso. A EN 319 142-1 não está no corpus de verificação. B-T baseia-se em ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816 e ISO 32000-2 §12.8.

O fluxo abaixo mostra o caminho da TSA controlado pelo host (a requisição não pode apontar para uma TSA) e o ramo B-T fail-closed (nunca um downgrade silencioso).

Diagram

Superfície da API

Ferramenta	Camada	Função	Nível de risco
`create_pdf`, `add_text`	Core	Construir conteúdo	Seguro / Cuidado
`sign_pdf`	Pro	Aplicar PAdES B-B (ou B-T controlado pelo host)	Aprovação obrigatória
`output_pdf`	Core	Renderizar e retornar o PDF	Aprovação obrigatória / Revisão (base64)

Os nomes das ferramentas são os nomes de protocolo do registro. O catálogo de ferramentas é o catálogo de referência. As ferramentas disponíveis dependem da camada instalada, e as ferramentas de nível de longo prazo não estão presentes no Pro.

Exemplo de código — Início rápido

create_pdf → construa o conteúdo com add_text.
sign_pdf com certificate (PEM), private_key (PKCS#8 PEM), signer_name opcional, reason e algorithm. Omita pades_b_t (ou defina-o como false) para B-B.
output_pdf.

A ferramenta retorna este envelope de resultado:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

Para uma assinatura B-T controlada pelo host, envie pades_b_t: true; level passa a ser "PAdES-B-T", e timestamped passa a ser true.

Exemplo de código — Produção

Assine como a última operação de conteúdo. Qualquer add_text/add_image após sign_pdf invalida a assinatura. Em um transporte não confidencial, encapsule private_key no envelope AES-GCM transport_encryption (nonce de 12 bytes; chave de 16/24/32 bytes). Verifique se o level do resultado corresponde à sua requisição. Uma requisição pades_b_t: true contra uma ferramenta sem provedor falha explicitamente. Trate esse erro e não tente novamente como B-B de forma silenciosa.

Casos extremos & pegadinhas

Incompatibilidade entre certificado/chave. A ferramenta rejeita a requisição com um erro claro; a chave privada deve corresponder à chave pública do certificado.
PEM malformado / certificado expirado. A ferramenta rejeita a requisição; por padrão, ela não assina com um certificado que não possa ser analisado ou que esteja expirado.
Conteúdo após a assinatura. A ferramenta rejeita a requisição — assine por último.
B-T solicitado, sem provedor. A ferramenta retorna um erro tipado: a assinatura não é produzida e não sofre downgrade silencioso para B-B.
Certificado autoassinado. A assinatura é aplicada, mas os leitores exibem confiança desconhecida. Isso é esperado, não um defeito da ferramenta.
Pro ausente. Com apenas o Core, o servidor não registra sign_pdf.

Desempenho

A assinatura adiciona a construção do CMS e, para B-T, uma ida e volta à TSA; o orçamento cobre ambos. O perfil é semantic: um token RFC 3161 é inerentemente não reproduzível, e o digest de byte-range da §12.8.1 exclui o valor da assinatura. Use apenas uma comparação de AST + metadados de assinatura.

Notas de segurança

Uma assinatura fornece integridade e autenticação relativas à chave de assinatura. Por si só, ela não torna um documento “seguro” ou “juridicamente válido”, nem garante não repúdio. Esses resultados dependem do certificado, da âncora de confiança, da custódia da chave e da política do verificador, todos fora desta ferramenta. Criptografar o payload da chave com o envelope AES-GCM protege a confidencialidade em trânsito, não a integridade. Trate a chave privada como segredo e prefira o envelope de transport-encryption em qualquer canal não confidencial.

Conformidade

Declaração	Especificação	Cláusula
O digest de byte-range cobre o arquivo e exclui o valor da assinatura.	ISO 32000-2	§12.8.1
`Contents` contém o CMS SignedData codificado em DER.	ISO 32000-2	§12.8.1
Para um timestamp, o hash de byte-range vai para uma TSA e o token é colocado em `Contents`.	ISO 32000-2	§12.8.5
O time-stamp B-T é um atributo não assinado no SignerInfo.	RFC 5652	§5.3
Atributos não assinados não alteram o digest assinado nem a validade B-B.	RFC 5652	§5.3
O valor de signature-time-stamp é um SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

O NextPDF produz a estrutura da assinatura. Ele não declara que qualquer assinatura resultante seja conformante ou juridicamente válida; um validador independente decide isso. Esta ferramenta não produz B-LT/B-LTA.

Contexto comercial

sign_pdf é uma ferramenta de camada Pro. O servidor a registra apenas quando o pacote Pro é resolvido na inicialização do servidor. Os níveis de longo prazo do PAdES (B-LT, B-LTA) e o respectivo material de validação (DSS, VRI, LTV) são exclusivos do Enterprise e não são expostos por esta ferramenta nem nesta receita.

Residência de dados & mitigações de PII

O certificado e a chave privada transitam pela requisição. Use o envelope AES-GCM transport_encryption em qualquer canal que não seja confidencial de ponta a ponta. O PDF assinado e a identidade do signatário (signer_name, reason) são conteúdo do documento, portanto mantenha-os dentro do seu limite de residência de dados. O integrador é responsável pela residência no nível da implantação.

Telemetria segura & limpeza de logs

Nunca registre o payload private_key, a chave/nonce AES-GCM nem o token de confirmação. Registre o algoritmo, o level resultante e signature_count, não o material da chave. A ferramenta não emite os bytes da chave no resultado.

Modelo de ameaças

Ameaças consideradas: divulgação da chave em trânsito (mitigada pelo envelope AES-GCM e pelo provedor de TSA injetado pelo host, que não é configurável pela requisição); tentativa de um chamador MCP de apontar o timestamp para um endpoint arbitrário (impedida porque o provedor é injetado pelo host, não configurável pela requisição); e adulteração pós-assinatura (o digest de byte-range detecta modificações). Um modelo de ameaças documenta as ameaças e mitigações consideradas; ele não declara a ausência de vulnerabilidades.

Comportamento em modo FIPS

A seleção de algoritmo (RSA-SHA256, RSA + SHA-3, Ed25519) é orientada pela requisição. O OpenSSL do host fornece as primitivas criptográficas. Em uma implantação com restrições FIPS, restrinja o algoritmo na camada de política e dependa do módulo validado do host. Esta ferramenta não declara, por si só, validação Federal Information Processing Standards (FIPS).

Disponibilidade de transporte

Transporte	Disponível	Notas
MCP (stdio)	Sim (Pro)	Use o envelope de chave AES-GCM no stdio.
REST	Sim (Pro)	Prefira TLS junto com o envelope de chave.
gRPC	Sim (Pro)	Prefira TLS junto com o envelope de chave.

Nível de risco HITL

sign_pdf é Aprovação obrigatória porque é uma operação destrutiva e irreversível; a ferramenta anuncia uma dica de operação destrutiva. O portão de confirmação se aplica como ocorre com qualquer ferramenta de Aprovação obrigatória. output_pdf para um arquivo também é Aprovação obrigatória; o modo base64 é Revisão (níveis de risco HITL).

Envelope JSON do portão de confirmação

sign_pdf sem um token válido retorna o envelope de desafio:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Chame novamente com _confirmation_token definido como o token → { "allowed": true }. Fluxo completo: output-approval.