Segurança

Visão geral

O NextPDF Pro acrescenta uma superfície de segurança sobre o NextPDF Core: mascaramento de conteúdo em tempo de geração, detecção de PII na camada de texto, estratégias de assinatura remota e por cloud-KMS e assinatura sequencial multipartes. O NextPDF Core produz os níveis PAdES B-B e B-T; o Pro produz os mesmos níveis e acrescenta esses fluxos de assinatura sobre eles (para o B-T, uma assinatura B-B mais um carimbo de tempo de assinatura RFC 3161 sobre o valor da assinatura). Esta página é em nível de comportamento. Ela enuncia o que cada parte faz, o que ela não faz e onde começa o limite do Enterprise.

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 as 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 e os fluxos de assinatura remota/cloud-KMS/sequencial; esses fluxos produzem os mesmos níveis B-B e B-T do Core por meio da pilha RFC 3161 do Core (para o B-T, um signature-time-stamp sobre o valor da assinatura). Uma implantação sem um direito Pro ativo não carrega essas classes; o contrato de assinatura do Core continua funcionando inalterado.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

O motor de mascaramento aplica uma lista ordenada de regras ao texto antes de a página ser gravada. Cada regra corresponde a uma expressão regular. Uma regra substitui uma correspondência de uma de três maneiras: um preenchimento black-box que remove o texto do fluxo de conteúdo, uma sequência de asteriscos com a mesma contagem de caracteres, ou um rótulo fixo como [REDACTED]. O motor remove os objetos de texto subjacentes no modo black-box, conforme testado; ele não afirma que toda forma de conteúdo sensível é encontrada. A detecção depende das regras que você configura.

A superfície de PII é uma ferramenta de detecção, não uma garantia de tarjamento. Ela extrai a camada de texto, 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 uma visão mascarada do texto e uma contagem de correspondências. Ela não sobrescreve os glifos renderizados na imagem da página. Uma página escaneada sem camada de texto não produz correspondências. Trate o resultado como detecção por correspondência de padrões dos tipos configurados, não como remoção completa de dados pessoais.

A superfície de assinatura acrescenta fluxos de trabalho remotos e assíncronos sobre o signatário do Core. Uma sessão calcula o digest do documento, monta os atributos assinados do CMS e entrega os bytes dos atributos assinados a uma estratégia de assinatura. Uma estratégia pode ser um cloud KMS, um signatário externo diferido ou um caminho de ingestão que encapsula uma assinatura CAdES ou XAdES existente. A sessão então monta o CMS SignedData e o armazena codificado em DER na entrada Contents do dicionário de assinatura — ISO 32000-2 §12.8.1. O SignerInfo carrega os atributos assinados content-type e message-digest; o processo de cálculo do message digest é RFC 5652 §5.4. Um verificador não deve confiar nos digests calculados pelo originador; ele recalcula de forma independente o digest do conteúdo e o compara com o atributo message-digest, e a comparação deve coincidir para que a assinatura seja válida — processo de verificação de assinatura RFC 5652 §5.6.

O NextPDF Core produz os níveis PAdES B-B e B-T; o NextPDF Pro produz os mesmos níveis e acrescenta seus fluxos de assinatura sobre eles. 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, a sessão acrescenta exatamente um signature-time-stamp RFC 3161 como um atributo não assinado do CMS sobre o valor da assinatura: 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, e seu MessageImprint é um hash do valor do campo de assinatura do SignerInfo, identificado pelo OID id-aa-timeStampToken — RFC 3161 Appendix A. O genTime do carimbo de tempo é o instante UTC em que o token foi criado — RFC 3161 §2.4.2. Como o carimbo de tempo é um atributo não assinado, o digest assinado do B-B, o valor da assinatura do SignerInfo e o /ByteRange do PDF permanecem inalterados; apenas o CMS cresce. O token RFC 3161 é obtido de um provedor de carimbo de tempo configurado (o cliente RFC 3161 padrão do Core, ou um provedor fornecido pelo chamador); o B-T usa um message imprint SHA-256 no caminho do provedor padrão. 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; isso é verificado por fixtures. O NextPDF Pro não afirma uma certificação ETSI EN 319 142-1 independente e não afirma validade jurídica do documento. 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; esses níveis são uma capacidade do Enterprise (nextpdf/enterprise) e não são produzidos pelo Pro. Veja Limite do Enterprise abaixo.

Por que funciona assim

A superfície de assinatura entrega os bytes dos atributos assinados a uma SigningStrategy em vez de deter uma chave privada. Essa única decisão é estruturante. Um cloud KMS, um signatário externo diferido ou um caminho de ingestão CAdES/XAdES todos satisfazem o mesmo contrato, portanto o código chamador permanece idêntico e o material da chave nunca entra no NextPDF. Dividir a sessão em RemoteSigningSession::prepare() e RemoteSigningSession::complete() permite que a assinatura retorne de forma assíncrona, porque o digest é fixado antes de a chave ser alcançada. O carimbo de tempo é anexado como um atributo não assinado do CMS, de modo que o B-T permanece aditivo: o digest assinado do B-B, o valor da assinatura do SignerInfo e o /ByteRange ficam intocados. Cada junção é fail-closed, já que um caminho de assinatura que se degrada silenciosamente é pior do que um que para. Contexto de design: Assinatura em escala, sem concessões.

Superfície da API

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	stable	1.9.0
SequentialSigner	class	Assinatura sequencial multipartes com suporte a DocMDP	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	stable	2.1.0
GenerationTimeMasker	class	Mascaramento orientado por regras aplicado antes de a página ser gravada	stable	1.9.0
MaskingConfig / MaskingRule / MaskingMode	types	Configuração de mascaramento, regra e modo de substituição	stable	1.9.0

RemoteSigningConfig carrega um campo de nível PAdES cujo enum é o SignatureLevel do Core. O caminho de assinatura do Pro produz o baseline B-B e o nível B-T: configure RemoteSigningConfig::default()->withLevel(SignatureLevel::PAdES_B_T) (ou use SequentialSigner::withTimestamping()) e forneça um provedor de carimbo de tempo, e a sessão acrescenta o atributo não assinado signature-time-stamp RFC 3161. O espaço /Contents reservado do B-T é elevado automaticamente para que o token caiba; um espaço configurado subdimensionado falha de forma fechada com um erro de configuração tipado, em vez de truncar. Um nível acima do B-T carregado na configuração (B-LT ou B-LTA) é um valor declarado antecipadamente sobre o qual o Pro não age; esse produtor de longo prazo resolve em tempo de execução por meio do contrato do Core e é fornecido no pacote nextpdf/enterprise.

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

Sign with a cloud-KMS strategy

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Pro\Security\Signing\RemoteSigningSession;
use NextPDF\Pro\Security\Signing\SigningStrategy;

/**
 * Produce a signed PDF using any signing strategy.
 *
 * @param string          $pdfWithPlaceholder PDF bytes with a signature placeholder.
 * @param SigningStrategy  $strategy           A cloud-KMS, deferred, or ingest strategy.
 *
 * @return string The signed PDF bytes.
 */
function signWithStrategy(string $pdfWithPlaceholder, SigningStrategy $strategy): string
{
    $session = RemoteSigningSession::create($pdfWithPlaceholder);

    $session->prepare(
        certDer: $strategy->getCertificateDer(),
        chainDer: $strategy->getCertificateChainDer(),
        algorithmOid: $strategy->getSignatureAlgorithmOid(),
        digestAlgorithm: $strategy->getDigestAlgorithm(),
        contentsHexStart: 0,
        contentsHexEnd: 0,
    );

    return $session->complete($strategy);
}

O chamador depende do contrato SigningStrategy. Uma estratégia cloud-KMS e uma estratégia de ingestão CAdES ambas o satisfazem, portanto este código não muda entre as estratégias.

Exemplo de código — Produção

Multi-party sequential signing with audit logging

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Pro\Security\Signing\SequentialSigner;
use NextPDF\Pro\Security\Signing\SigningStrategy;
use Psr\Log\LoggerInterface;

final readonly class ApprovalWorkflow
{
    public function __construct(private LoggerInterface $logger) {}

    /**
     * Sign a PDF with two parties in sequence.
     *
     * @param string          $pdfData   The PDF bytes to sign.
     * @param SigningStrategy  $approver  The first-party strategy.
     * @param SigningStrategy  $reviewer  The second-party strategy.
     *
     * @return string The signed PDF bytes.
     */
    public function run(string $pdfData, SigningStrategy $approver, SigningStrategy $reviewer): string
    {
        try {
            $result = SequentialSigner::create($pdfData)
                ->addSigner($approver, 'Approver', reason: 'Approved')
                ->addSigner($reviewer, 'Reviewer', reason: 'Reviewed')
                ->sign();

            $this->logger->info('Sequential signing complete', [
                'signatures' => $result->signatureCount,
            ]);

            return $result->pdfData;
        } catch (\Throwable $e) {
            $this->logger->error('Sequential signing failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

Cada signatário é uma revisão incremental separada. O bloco catch registra o log e relança; ele não engole a falha, o que mantém o caminho de assinatura fail-closed.

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 desse verificador — RFC 5280 §6.1. O produtor não pode afirmar o resultado.
• A detecção de mascaramento depende das regras configuradas. Um conjunto de regras que não corresponde a um valor não o mascara. O motor não afirma que todo o conteúdo sensível é encontrado.
• A detecção de PII é apenas na camada de texto. Uma página escaneada sem camada de texto não produz correspondências. A ferramenta não sobrescreve os glifos renderizados da página.
• A estrutura CMS deve caber no espaço Contents reservado. O SignedData B-B com uma cadeia de certificados completa tem um tamanho; dimensione o espaço reservado de acordo, ou a sessão gera um erro de estouro.
• Uma estratégia cloud-KMS depende da acessibilidade de rede e da disponibilidade do provedor. Um erro de rede ou de provedor gera uma exceção tipada; a sessão não produz silenciosamente um documento não assinado.
• O unknown do OCSP não é good. Trate unknown como uma não determinação — RFC 6960 §2.2.

Desempenho

Uma assinatura por software leva milissegundos de um dígito. Uma assinatura cloud-KMS acrescenta uma ida e volta de rede ao provedor. Uma assinatura B-T acrescenta uma ida e volta ao provedor de carimbo de tempo configurado, além da operação de assinatura. O orçamento de 1500 ms de wall cobre uma única assinatura B-B com um provedor remoto em uma conexão aquecida. O custo do mascaramento escala com a contagem de regras e o comprimento do texto. O perfil de reprodutibilidade é structural: os atributos assinados do B-B incorporam o instante da assinatura e uma assinatura B-T incorpora adicionalmente um token de carimbo de tempo, de modo que duas execuções diferem nos bytes de signing-time e de carimbo de tempo, embora a estrutura assinada seja idêntica.

Notas de segurança

Este é um limite criptográfico, portanto o modelo de ameaça é explícito. O byte range é calculado pelo motor e nunca é aceito do chamador. O caminho de assinatura é fail-closed: uma falha de primitiva ou uma lacuna de capacidade gera uma exceção tipada e nunca rebaixa silenciosamente para um algoritmo mais fraco. Uma estratégia cloud-KMS é um ponto de integração, não um armazenamento de chaves. A proteção da chave depende do tratamento de chaves, do KMS configurado e da implantação; o NextPDF Pro não detém a chave privada para uma estratégia KMS. O Pro opera em um modo compatível com FIPS quando configurado contra um KMS ou HSM validado por FIPS; o próprio NextPDF Pro não é um módulo criptográfico validado por FIPS. Esta página diz respeito à assinatura criptográfica; toda fonte normativa é parafraseada e nenhuma é reproduzida.

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 os campos estruturais mostrados no exemplo de produção, não os bytes do documento.

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. O próprio NextPDF Pro realiza a montagem estrutural e o cálculo do digest; ele não é um módulo validado por FIPS e não faz nenhuma declaração de certificação FIPS.

Limite do Enterprise

O NextPDF Pro produz o baseline B-B e o nível B-T. O B-T acrescenta um signature-time-stamp RFC 3161 como um atributo não assinado do CMS sobre o valor da assinatura, 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; ele é verificado por fixtures. O NextPDF Pro não afirma uma certificação 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. Uma configuração que solicita um Document Security Store ou o laço de arquivamento de longo prazo resolve esse produtor em tempo de execução por meio do contrato do Core; esse produtor é fornecido no pacote nextpdf/enterprise. Em uma implantação somente Pro, solicitar B-LT ou B-LTA falha de forma fechada com uma mensagem que nomeia o componente Enterprise ausente. O Pro não produz Document Security Store, 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.

Nível PAdES	Acrescenta	Edição produtora
B-B	Assinatura CMS com atributos assinados	Core, Pro, Enterprise
B-T	Um atributo não assinado signature-time-stamp RFC 3161 sobre o valor da assinatura	Core, Pro, Enterprise
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)

Contrato de comportamento

• O mascaramento aplica as regras configuradas antes de a página ser gravada e remove os objetos de texto subjacentes no modo black-box, conforme testado.
• A detecção de PII extrai a camada de texto, aplica os padrões configurados e retorna uma visão mascarada e uma contagem de correspondências. Ela não sobrescreve os glifos renderizados.
• A assinatura remota tem duas fases: prepare calcula o digest e monta os atributos assinados; complete monta o CMS e o incorpora.
• O Pro produz o baseline B-B e o nível B-T. Para o B-T, a sessão acrescenta um signature-time-stamp RFC 3161 como um atributo não assinado do CMS sobre o valor da assinatura; o digest assinado do B-B e o /ByteRange permanecem inalterados. Uma solicitação de B-T sem um provedor de carimbo de tempo, ou com um espaço Contents configurado subdimensionado, falha de forma fechada com um erro de configuração tipado. Uma solicitação de B-LT ou B-LTA sem o pacote Enterprise falha de forma fechada com um erro nomeado.
• Uma estratégia cloud-KMS recebe o digest dos atributos assinados, não o documento, e retorna os bytes brutos da assinatura.

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
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 MessageImprint do token id-aa-timeStampToken do signature-time-stamp é 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
Um token de carimbo de tempo B-T carrega um genTime UTC que é o instante em que o token foi criado.	RFC 3161	§2.4.2
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
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

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.

Limite de publicação

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

Veja também

• Segurança — Referência Detalhada — a referência detalhada para esta superfície de segurança do Pro.
• 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.
• NextPDF Pro — a superfície completa de recursos do Pro.
• Core security — criptografia e a superfície de assinatura mais ampla.
• CMS · PAdES · Carimbo de tempo RFC 3161 · KMS · DSS — termos do glossário.