Pro edição

Security — Referência Profunda

Visão geral

Esta é a referência profunda da superfície de segurança do NextPDF Pro: mascaramento em tempo de geração, detecção de PII na camada de texto, a sessão de assinatura remota e por cloud-KMS, assinatura sequencial multipartes, o caminho de ingestão CAdES e XAdES, o nível baseline PAdES B-B e o suporte à assinatura PAdES B-T (uma assinatura B-B mais um carimbo de tempo de assinatura RFC 3161 sobre o valor da assinatura). Ela enuncia o contrato da API pública, o comportamento observável externamente e o limite B-LT/B-LTA do Enterprise. É em nível de comportamento; não cita nenhum caminho de implementação interno.

Disponibilidade & licenciamento

Esta capacidade é fornecida no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes da capacidade. Compare edições e obtenha uma licença.

O Core fornece o signatário CMS por software, o cliente de carimbo de tempo RFC 3161, a validação de caminho RFC 5280 e a verificação de revogação por OCSP e CRL. O Pro acrescenta o mascaramento, a detecção de PII, a superfície de assinatura remota e por cloud-KMS e o suporte à assinatura PAdES B-T (ele compõe a pilha RFC 3161 do Core para acrescentar um carimbo de tempo de assinatura) descritos aqui. O sinalizador de capacidade desta superfície é pro: uma implantação sem um direito Pro ativo não carrega essas classes, o contrato de assinatura do Core continua funcionando inalterado, e o código que depende do contrato do Core não quebra quando o direito está ausente.

Instalação

composer require nextpdf/pro:^3

Contrato de comportamento

O motor de mascaramento aplica uma lista ordenada de regras ao texto antes de a página ser gravada. Uma regra corresponde a um padrão PCRE e substitui uma correspondência em um de três modos:

BlackBox — remove o texto correspondido do fluxo de conteúdo e reserva uma região de preenchimento. Esse modo remove os objetos de texto subjacentes, conforme testado.
Asterisks — substitui cada caractere correspondido por um asterisco, preservando a contagem de caracteres.
FixedLabel — substitui toda a correspondência por um rótulo configurável, [REDACTED] por padrão.

Uma regra é construída a partir de um literal exato por meio de MaskingRule::exactMatch (o literal é escapado como regex) ou a partir de um padrão PCRE personalizado por meio de MaskingRule::regex. MaskingConfig mantém a lista ordenada de regras, um modo padrão e a cor de preenchimento. MaskingConfig::fromArray analisa um mapa de configuração e descarta silenciosamente uma entrada de regra que não tenha um padrão de string utilizável, em vez de falhar toda a importação.

A superfície de PII extrai a camada de texto do PDF, então aplica padrões integrados para endereços de e-mail, números de telefone, números de Social Security dos Estados Unidos e números de cartão de crédito. Ela retorna um resultado estruturado: um booleano para indicar se houve alguma correspondência, uma contagem de correspondências, a visão mascarada do texto e a lista de tipos verificados. O chamador pode restringir a varredura a um subconjunto dos quatro tipos. A superfície não sobrescreve os glifos renderizados da página; uma página escaneada sem camada de texto não produz correspondências. Trate o resultado como detecção de padrões na camada de texto dos tipos configurados, não como remoção completa de dados pessoais e não como uma declaração de compliance regulatório.

A sessão de assinatura tem duas fases. RemoteSigningSession::create abre uma sessão. prepare calcula o digest do documento sobre as duas regiões ByteRange, então monta os atributos assinados do CMS. complete chama a estratégia e incorpora o resultado; suspend serializa a sessão para que um worker possa retomá-la depois com resume e completeWithRawSignature. A sessão monta um CMS SignedData e o armazena codificado em DER na entrada Contents do dicionário de assinatura — ISO 32000-2 §12.8.1. Quando um certificado X.509 analisável é fornecido, a sessão emite o conjunto completo de atributos assinados obrigatórios do PAdES B-B: content-type, message-digest, signing-time, signing-certificate-v2 e um atributo de proteção de algoritmo — RFC 5652 §5.3 e RFC 5652 §5. O verificador recalcula o digest do conteúdo e o compara com o atributo message-digest; a comparação deve coincidir para que a assinatura seja válida — RFC 5652 §5.4.

Quando o nível PAdES configurado é B-T (RemoteSigningConfig::default->withLevel(SignatureLevel::PAdES_B_T), ou via SequentialSigner::withTimestamping) e um provedor de carimbo de tempo está conectado, a sessão incorpora adicionalmente exatamente um signature-time-stamp RFC 3161 como um atributo não assinado do CMS no primeiro SignerInfo. Um signature-time-stamp é um atributo não assinado que carrega um token de carimbo de tempo calculado sobre o valor da assinatura digital de um signatário — ETSI EN 319 122-1 §5.3; seu MessageImprint é o hash do valor do campo de assinatura do SignerInfo com a tag e o comprimento ASN.1 excluídos — ETSI EN 319 122-1 §5.3 e RFC 3161 Appendix A (OID id-aa-timeStampToken = 1.2.840.113549.1.9.16.2.14). Como o carimbo de tempo é um atributo não assinado, os atributos assinados do B-B, o message-digest, o valor da assinatura do SignerInfo e o /ByteRange do PDF são byte-idênticos à saída B-B; apenas o CMS cresce pelo atributo não assinado, e o espaço /Contents reservado do B-T é elevado para que ele caiba. O token é solicitado ao provedor de carimbo de tempo configurado (o cliente RFC 3161 padrão do Core, ou um provedor fornecido pelo chamador). No caminho do provedor padrão, o digest do imprint é SHA-256; a forma legada ESSCertID v1, vinculada a SHA-1, é recusada e o ESSCertIDv2 é exigido — RFC 5816 §1. Uma falha da TSA, uma solicitação recusada, um nonce ou eco de message-imprint inválido, um token malformado ou com algoritmo não suportado, ou um token que falha na verificação criptográfica, vem à tona como uma exceção tipada PadesBt com a exceção originária do Core preservada como a exceção anterior (previous throwable). O NextPDF Pro implementa o suporte à assinatura PAdES B-T conforme ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 e RFC 5816, e ele é verificado por fixtures; ele não afirma uma certificação ETSI EN 319 142-1 independente e não afirma validade jurídica do documento.

SequentialSigner coordena a assinatura multipartes. Cada signatário é uma revisão separada de atualização incremental. O primeiro signatário pode ser uma assinatura de certificação com uma restrição DocMDP definida por meio de certifyFirst. PadesWrapper ingere uma assinatura existente: fromCades incorpora uma estrutura CMS diretamente, fromXades analisa um documento XAdES e reutiliza seu material de assinatura central, e detect seleciona automaticamente pelo formato. O caminho XAdES reutiliza o certificado, a cadeia, o valor da assinatura e o algoritmo; ele não transfere as propriedades qualificadoras do XAdES.

Superfície da API pública

composer require nextpdf/pro:^3

Tipo	Categoria	Função	Estabilidade	Desde
`RemoteSigningSession`	class	Sessão de assinatura remota ou assíncrona em duas fases	stable	1.9.0
`RemoteSigningConfig`	class	Configuração imutável da sessão, incluindo nível PAdES e algoritmo	stable	1.9.0
`SequentialSigner`	class	Assinatura sequencial multipartes com suporte a DocMDP	stable	1.9.0
`SequentialSigningResult`	class	Resultado de uma execução sequencial: bytes do PDF, cadeia, contagem, completude	stable	1.9.0
`SigningStrategy`	interface	O contrato do mecanismo de assinatura que uma sessão chama	stable	1.9.0
`PadesWrapper`	class	Encapsula uma assinatura CAdES ou XAdES existente para incorporação PAdES	stable	1.9.0
`KmsSignerInterface`	interface (SPI)	Contrato de driver de HSM e KMS de terceiros; estende o contrato de signatário HSM do Core	stable	2.1.0
`SignatureAlgorithm`	enum	OIDs de algoritmo de assinatura e nomes de digest do Pro	stable	2.1.0
`GenerationTimeMasker`	class	Mascaramento orientado por regras aplicado antes de a página ser gravada	stable	1.9.0
`MaskingConfig`	class	Configuração imutável de mascaramento	stable	1.9.0
`MaskingRule`	class	Uma única regra de mascaramento (literal ou PCRE)	stable	1.9.0
`MaskingMode`	enum	BlackBox, Asterisks, FixedLabel	stable	1.9.0

Contrato de `SigningStrategy`

Uma estratégia opera sobre os atributos assinados codificados em DER e retorna os bytes brutos da assinatura. A sessão, e não a estratégia, monta o CMS SignedData. Uma estratégia expõe o DER do certificado do signatário, o DER da cadeia ordenada de folha à raiz, o OID do algoritmo de assinatura, o nome do algoritmo de digest e um sinalizador isAsync que marca uma estratégia cuja sessão pode ser serializada e retomada.

SPI `KmsSignerInterface`

KmsSignerInterface estende o contrato de signatário HSM do Core. Ele acrescenta um providerId estável para busca no registro, um método signWithVersion com um parâmetro de versão de chave explícito por chamada, e supportsAlgorithm e supportedAlgorithms para que um chamador descubra a compatibilidade de algoritmo antes da chamada de assinatura. Os identificadores de provedor integrados reservados são aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli e openssl-engine. Um driver de terceiros deve usar namespace em seu identificador para evitar uma colisão. A semântica padrão de versão de chave varia por provedor: um provedor que resolve aliases resolve a chave ativa a partir do alias quando a versão é null; um provedor que seleciona a versão habilitada mais recente faz isso por meio do seu transporte; um provedor que não tem o conceito de versão ativa do lado do servidor deve usar uma versão fixada em sua configuração e deve gerar um erro de gerenciamento de chaves quando nem a chamada nem a configuração fixam uma versão. Uma versão não vazia fixa essa versão, e o provedor deve gerar um erro de gerenciamento de chaves quando a versão for desconhecida, desabilitada ou revogada.

Casos extremos & armadilhas

Uma assinatura produzida não é uma assinatura verificada. A validação de caminho é executada no verificador com as âncoras de confiança e as verificações de basic-constraint desse verificador — RFC 5280 §6.1. O produtor não pode afirmar o resultado.
A sessão tem um fallback legado de três atributos para bytes de certificado sintético que não sejam X.509. As estratégias de produção sempre fornecem DER X.509 real, portanto o conjunto completo de atributos B-B é o caminho de produção. O fallback existe apenas para a superfície de teste histórica de mecânica DER.
A estrutura CMS deve caber no espaço Contents reservado. O CMS SignedData B-B com uma cadeia de certificados completa tem um tamanho; a sessão gera um erro de estouro quando o CMS montado excede o espaço hexadecimal reservado. Dimensione o espaço reservado de acordo. Para B-T, o token RFC 3161 incorporado (dominado pela cadeia de certificados da TSA) aumenta o CMS; o espaço reservado do B-T é elevado automaticamente, e um espaço configurado subdimensionado falha de forma fechada com um erro de configuração tipado, em vez de truncar.
MaskingConfig::fromArray descarta uma entrada sem padrão de string utilizável, em vez de falhar a importação. Valide a fonte da configuração se um descarte silencioso for inaceitável.
O modo black-box de mascaramento emite uma substituição vazia para a sequência correspondida e remove o texto subjacente. Uma regra que não corresponde a um valor não o mascara; o motor não afirma que todo o conteúdo sensível é encontrado.
O B-T requer um provedor de carimbo de tempo conectado. No caminho do provedor RFC 3161 padrão do Core, o digest do imprint é SHA-256; um digest de imprint que não seja SHA-256 nesse caminho é rejeitado com um erro de configuração tipado, em vez de rebaixado silenciosamente, e um provedor personalizado fornecido pelo chamador pode legitimamente usar outro digest aprovado. Um serialNumber de carimbo de tempo é único por token de uma determinada Time-Stamping Authority, e genTime é o instante UTC em que o token foi criado — RFC 3161 §2.4.1, §2.4.2. O material de validação de longo prazo B-LT/B-LTA continua sendo uma preocupação do limite do Enterprise; o Pro não produz DSS, nem VRI, nem carimbo de tempo de documento.
O unknown do OCSP não é good, e a atualidade do status é limitada por thisUpdate e nextUpdate — RFC 6960 §2.2, §4.2.

Comportamento em modo FIPS

O Pro seleciona o algoritmo a partir do algoritmo de assinatura configurado e da estratégia. Quando configurado contra um KMS ou HSM validado por FIPS, a operação criptográfica é executada nesse limite validado, e o conjunto de algoritmos é o que esse limite permitir. O NextPDF Pro realiza a montagem estrutural do CMS e o cálculo do digest; ele não é um módulo criptográfico validado por FIPS e não faz nenhuma declaração de certificação FIPS. Uma implantação que exige uma postura FIPS deve configurar um KMS ou HSM validado por FIPS, e o perfil de política criptográfica FIPS 140-3 é uma capacidade do Enterprise.

Postura de controle de exportação

Este módulo diz respeito a funcionalidade criptográfica; trate-o como sensível à segurança em sua própria revisão.

Limite do Enterprise

O NextPDF Pro produz o baseline B-B e o nível B-T. Para o B-B, a sessão monta um CMS SignedData com o conjunto de atributos assinados do B-B e não aplica nenhum carimbo de tempo. Para o B-T, ele acrescenta exatamente um signature-time-stamp RFC 3161 como um atributo não assinado do CMS, calculado sobre o valor da assinatura digital de um signatário — ETSI EN 319 122-1 §5.3. O NextPDF Pro implementa isso conforme ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652 e RFC 5816, e ele é verificado por fixtures; ele não afirma uma certificação, conformidade ou compliance ETSI EN 319 142-1 independente e não afirma validade jurídica do documento.

Os níveis B-LT e B-LTA são capacidades do Enterprise e não são produzidos pelo Pro. O B-LT e o B-LTA acrescentam um Document Security Store e carimbos de tempo de documento para validação de arquivamento de longo prazo — ETSI EN 319 142-2 §5.5. Um manipulador de assinatura que produz esses níveis dá suporte a entradas DSS e a carimbos de tempo de documento — ETSI EN 319 142-2 §6.3.3.3. O RemoteSigningConfig do Pro pode carregar um nível acima do B-T (B-LT ou B-LTA) que solicita um Document Security Store, mas o Pro não fornece esse produtor e não age sobre ele; tal nível é um valor declarado antecipadamente. O fluxo de assinatura do Core resolve o produtor de longo prazo em tempo de execução por meio do contrato do Core, e esse produtor é fornecido no pacote nextpdf/enterprise. Em uma implantação somente Pro, uma solicitação de B-LT ou B-LTA falha de forma fechada com uma mensagem que nomeia o componente Enterprise ausente. O Pro não produz DSS, nem dicionário VRI, nem carimbo de tempo de documento, nem laço de arquivamento, e não faz nenhuma declaração de validação de longo prazo (LTV). A custódia de chaves em hardware por meio de PKCS#11, e o perfil de política criptográfica FIPS 140-3, também são capacidades do Enterprise. Esta página não documenta a implementação de validação de longo prazo do Enterprise; ela enuncia apenas o limite e o nome público do pacote.

Nível PAdES	Acrescenta	Edição produtora
B-B	Assinatura CMS com atributos assinados	Core, Pro
B-T	Um atributo não assinado signature-time-stamp RFC 3161 sobre o valor da assinatura	Core, Pro
B-LT	Document Security Store com material de validação	Enterprise (`nextpdf/enterprise`)
B-LTA	Carimbos de tempo de documento para validade de arquivamento	Enterprise (`nextpdf/enterprise`)

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. Caminhos de namespace interno, classes auxiliares, tabelas de mecanismos, nomes de arquivo de runbook e prefixos de ticket estão fora de escopo.

Fallback do Core

Uma implantação sem o direito Pro mantém o contrato de assinatura do Core. O código que depende do contrato SignerInterface do Core continua a assinar com o signatário CMS por software no baseline B-B. O mascaramento, a detecção de PII e as estratégias de assinatura remota e por cloud-KMS não estão presentes sem o pacote Pro, e uma chamada a esses tipos é um erro rígido de dependência, não um no-op silencioso.

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

As superfícies de mascaramento e de PII são executadas em processo. Nenhum conteúdo de documento sai do host para mascaramento ou detecção de PII. Uma estratégia cloud-KMS envia o digest dos atributos assinados, não o documento, ao provedor para a operação de assinatura. A detecção de PII é por correspondência de padrões nos tipos configurados e remove os objetos de texto subjacentes no modo black-box, conforme testado. Ela não é uma garantia de remoção completa de dados pessoais e não é uma declaração de compliance regulatório.

Telemetria segura & limpeza de logs

A biblioteca gera exceções tipadas com mensagens estruturais. Ela não grava conteúdo de documento ou valores de PII detectados em mensagens de exceção ou em logs. Uma implantação que registra logs em torno do caminho de assinatura deve registrar campos estruturais, não bytes de documento.

Conformidade

Afirmação	Padrão	Cláusula
A assinatura CMS é armazenada codificada em DER na entrada `Contents` do dicionário de assinatura.	ISO 32000-2	§12.8.1
O processo de cálculo do message digest; os atributos assinados carregam content-type e message-digest.	RFC 5652	§5.4
O verificador não deve confiar nos digests calculados pelo originador; ele recalcula e compara de forma independente (processo de verificação de assinatura).	RFC 5652	§5.6
O SignerInfo carrega o identificador do algoritmo de digest e o bloco de atributos assinados.	RFC 5652	§5
Uma solicitação de carimbo de tempo retorna uma estrutura TSTInfo.	RFC 3161	§2.4.1
Um serialNumber de carimbo de tempo é único por token de uma determinada TSA.	RFC 3161	§2.4.2
O genTime do carimbo de tempo é o instante UTC em que o token foi criado.	RFC 3161	§2.4.2
Um signature-time-stamp PAdES B-T é um atributo não assinado que carrega um token de carimbo de tempo calculado sobre o valor da assinatura digital de um signatário (o Pro produz B-T).	ETSI EN 319 122-1	§5.3
O imprint do signature-time-stamp é o hash do valor do campo de assinatura do SignerInfo com a tag e o comprimento ASN.1 excluídos.	ETSI EN 319 122-1	§5.3
O token signature-time-stamp usa o OID `id-aa-timeStampToken`; seu MessageImprint é um hash do valor do campo de assinatura do SignerInfo.	RFC 3161	Appendix A
No lado da verificação, o NextPDF vincula o MessageImprint de um signature-time-stamp ao valor da assinatura do SignerInfo e falha de forma fechada em caso de incompatibilidade, token ausente/duplicado ou imprint SHA-1 (verificação estrita, não uma certificação).	RFC 3161	Appendix A
O ESSCertIDv2 substitui o ESSCertID legado vinculado a SHA-1; o caminho B-T estrito exige ESSCertIDv2.	RFC 5816	§1
A validação de caminho de certificação verifica as basic constraints e as entradas de caminho até uma âncora de confiança.	RFC 5280	§6.1
O OCSP informa certStatus como good, revoked ou unknown.	RFC 6960	§2.2
A atualidade do status OCSP é limitada por thisUpdate e nextUpdate.	RFC 6960	§4.2
O B-LT e o B-LTA acrescentam um Document Security Store e carimbos de tempo de documento para validação de longo prazo (limite do Enterprise).	ETSI EN 319 142-2	§5.5
Um manipulador de assinatura que produz níveis de longo prazo dá suporte a entradas DSS e a carimbos de tempo de documento (limite do Enterprise).	ETSI EN 319 142-2	§6.3.3.3

Todas as cláusulas são parafraseadas. O NextPDF não reproduz texto normativo. Consulte os padrões publicados para obter a redação oficial. O NextPDF Pro implementa o suporte à assinatura PAdES B-T conforme ETSI EN 319 122-1 §5.3 (signature-time-stamp), RFC 3161, RFC 5652 e RFC 5816, e ele é verificado por fixtures. A ETSI EN 319 142-1 (a parte dos níveis baseline PAdES) está fora do conjunto de evidências citado; o NextPDF Pro, portanto, não afirma uma certificação, conformidade ou compliance ETSI EN 319 142-1 independente e não afirma validade jurídica do documento. Esta página enuncia a estrutura produzida, os padrões que o suporte B-T implementa e o limite B-LT/B-LTA do Enterprise, não um nível de conformidade certificado.

Veja também

Core signing — o signatário CMS, o carimbo de tempo RFC 3161, a validação de caminho RFC 5280, OCSP e CRL.
Mapeamento de cláusulas PAdES — B-B, B-T, B-LT, B-LTA entre as edições.
Security (visão geral da capacidade) — a página pública de capacidade de segurança do Pro.
CMS · PAdES · Carimbo de tempo RFC 3161 · KMS · DSS — termos do glossário.