Enterprise edição

Certificate Transparency — Referência Profunda

Visão geral

Esta página é a referência detalhada da superfície de Certificate Transparency (CT) no NextPDF Enterprise. A superfície é um único value object imutável: NextPDF\Enterprise\Security\CertificateTransparency\CtValidationResult. Ele resume a postura de Signed Certificate Timestamp (SCT) de um certificado de assinatura X.509. Ele carrega a flag da extensão de SCT, as contagens totais e válidas de SCT e os identificadores dos logs emissores. Ele expõe um método de política, meetsPolicy(), que é uma verificação de limiar mínimo de SCT. O tipo representa um resultado; ele não extrai SCTs, não verifica assinaturas de SCT e não contata logs de CT. Para o guia em nível de fluxo de trabalho, veja Política de Certificate Transparency para certificados de assinatura.

Disponibilidade e licenciamento

Esta capacidade é fornecida no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de tier Enterprise. Uma implantação sem essa titularidade não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`CtValidationResult`	—	Value object imutável que resume a postura de SCT de um certificado	—	Não lança	`final readonly`; todas as quatro propriedades promovidas pelo construtor são públicas
`CtValidationResult::__construct`	`bool $hasSctsExtension`, `int $totalScts`, `int $validScts`, `array<string> $logIds`	Armazena os valores fornecidos como recebidos, sem validação ou reconciliação	Nova instância de `CtValidationResult`	Sem `@throws` declarado; o PHP levanta `TypeError` em tipos de argumento incompatíveis sob `strict_types`	Propriedades `readonly` públicas promovidas
`CtValidationResult::meetsPolicy`	`int $minimumScts = 2`	Compara a contagem de SCTs válidos com o limiar: `validScts >= $minimumScts`	`bool`	Não lança	Conta apenas SCTs válidos; não verifica distinção de logs nem presença da extensão

final readonly class CtValidationResult

public function __construct(
    public bool $hasSctsExtension,
    public int $totalScts,
    public int $validScts,
    public array $logIds,
) {}

public function meetsPolicy(int $minimumScts = 2): bool

Propriedades readonly públicas

Propriedade	Tipo	Significado
`$hasSctsExtension`	`bool`	Se o certificado contém a extensão de SCT
`$totalScts`	`int`	Número total de SCTs encontrados na extensão
`$validScts`	`int`	Número de SCTs com assinaturas válidas, conforme determinado a montante
`$logIds`	`array<string>`	Identificadores de log (hashes SHA-256) dos logs de CT que emitiram os SCTs

Contrato de comportamento

CtValidationResult é um valor de resultado. Ele representa o desfecho da extração e verificação de SCT que o ambiente do chamador realizou. Ele não faz parsing de certificados, não verifica assinaturas de SCT, não consulta logs e não submete certificados a logs.
A extensão em questão é a extensão de certificado X.509v3 de SCT embutido, identificada pelo OID 1.3.6.1.4.1.11129.2.4.2 — RFC 6962 §3.3. Um SCT carrega uma versão, um identificador de log, um timestamp, extensões e a assinatura do log sobre a entrada — RFC 6962 §3.2.
Cada entrada em $logIds é um identificador de log conforme definido pela RFC 6962 §3.2: o hash SHA-256 da chave pública do log sobre seu SubjectPublicKeyInfo codificado em DER. O tipo armazena as strings como fornecidas e não as recalcula nem valida.
meetsPolicy() implementa exatamente uma comparação: a contagem de SCTs válidos é maior ou igual ao limiar. O limiar padrão é 2.
meetsPolicy() não consulta $hasSctsExtension. Uma política que precisa falhar diante de uma extensão ausente restringe a propriedade separadamente, antes ou junto com a verificação de limiar.
meetsPolicy() não deduplica $logIds. Uma política que exige SCTs de logs independentes verifica a distinção por meio do próprio $logIds.
O construtor armazena as entradas literalmente. Ele não realiza verificações de faixa nem verificações de consistência entre campos.
As instâncias são imutáveis (final readonly). Todas as leituras e a verificação de limiar são determinísticas e livres de efeitos colaterais.
O valor do limiar é a escolha de política do operador; o NextPDF não impõe nenhum número. O código-fonte do pacote anota um ponto de referência do ecossistema: a política de CT do Chrome, a partir de 2024, espera pelo menos dois SCTs de logs diferentes para certificados com vida útil de até 180 dias, e três para certificados de vida mais longa. Essa é uma política de programa de navegador, não um requisito do IETF.
A colocação pretendida é uma barreira pré-assinatura: um fluxo de trabalho de assinatura recusa-se a construir um signatário quando a verificação falha. A justificativa segue o modelo de confiança do CT: um SCT é a promessa do log de incorporar o certificado, e as partes confiantes rejeitam um certificado que carece de um SCT válido — RFC 6962 §3. A versão 2.0 do CT mantém o mesmo modelo: um log que aceita uma submissão retorna um SCT, que o submissor valida antes de confiar nele — RFC 9162 §3.

Casos extremos e modos de falha

Limiar zero ou negativo. meetsPolicy(0) retorna true para qualquer $validScts não negativo. O método não rejeita o valor. Escolha um limiar de pelo menos 1.
Extensão ausente, contagens positivas. Quando $hasSctsExtension é false mas $validScts atinge o limiar, meetsPolicy() ainda retorna true. A barreira deve verificar $hasSctsExtension explicitamente quando a ausência deve falhar; a página da capacidade mostra esse padrão.
Identificadores de log duplicados. N SCTs válidos de um único log satisfazem um limiar de N. A verificação de limiar não faz nenhuma afirmação de independência. Políticas de distinção de logs inspecionam $logIds.
Contagens inconsistentes. Um $validScts maior que $totalScts, ou uma contagem negativa, é armazenado como fornecido. Nenhuma exceção é levantada. A etapa de extração a montante é responsável pela consistência da entrada.
Strings de identificador de log não validadas. O tipo não impõe um formato de 32 bytes ou hexadecimal sobre as entradas de $logIds. Identificadores malformados passam inalterados.
Sem caminho de exceção. Nenhum método nesta superfície lança sob tipos PHP válidos. O modo de falha da verificação de política é a recusa (false), não uma exceção. Tipos de argumento incompatíveis levantam um TypeError do PHP sob strict_types, como em qualquer API PHP tipada.

Comportamento em modo FIPS

CtValidationResult não realiza nenhuma computação criptográfica. Ele não calcula nenhum digest e não verifica nenhuma assinatura. Se uma assinatura de SCT foi contada como válida é decidido a montante, pelo componente que realizou a verificação antes de construir o resultado. O perfil de política criptográfica FIPS 140-3 do Enterprise, documentado junto ao módulo de segurança, portanto, não altera o comportamento deste tipo.

Conformidade

Afirmação	Padrão	Cláusula
Um SCT é a promessa do log de incorporar o certificado; as partes confiantes rejeitam um certificado que carece de um SCT válido.	RFC 6962	§3
Um SCT carrega uma versão, um identificador de log, um timestamp, extensões e a assinatura do log sobre a entrada.	RFC 6962	§3.2
O identificador de log é o hash SHA-256 da chave pública do log sobre seu `SubjectPublicKeyInfo` codificado em DER.	RFC 6962	§3.2
SCTs embutidos são transportados por uma extensão de certificado X.509v3 identificada pelo OID `1.3.6.1.4.1.11129.2.4.2`.	RFC 6962	§3.3
Na versão 2.0 do CT, um log que aceita uma submissão retorna um SCT, que o submissor valida antes de confiar nele.	RFC 9162	§3

Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. O NextPDF não faz nenhuma afirmação de conformidade ou certificação de Certificate Transparency. O NextPDF Enterprise não é um log de CT, um auditor ou um monitor. Ele não submete certificados a logs e não afirma um desfecho de verificação de CT. O tipo representa contagens e identificadores que o ambiente do chamador produziu, e avalia um limiar escolhido pelo chamador. Programas de CT de navegadores, como o do Chrome, são políticas de ecossistema em vez de requisitos normativos do IETF; selecionar e satisfazer tal política é responsabilidade do operador.

Notas de desenvolvimento

O value object não tem dependências nem I/O. Construa instâncias diretamente em testes unitários.
Testes de fronteira recomendados: contagem válida exatamente no limiar, uma abaixo do limiar, extensão ausente com contagens no limiar e identificadores de log duplicados contra uma política de distinção.
A classe é declarada sob strict_types=1 com propriedades promovidas tipadas. Tipos de argumento errados levantam um TypeError do PHP no chamador.
A classe carrega uma anotação de pacote @since de 1.0.0 e referencia a RFC 6962 e a RFC 9162 em sua documentação de código-fonte.
O parâmetro $logIds é documentado como array<string>; a análise estática trata a propriedade como um array de strings. Preserve esse formato ao construir resultados.
Coloque sua verificação de CT a montante e esta barreira de limiar antes da construção do signatário, para que um certificado sub-registrado nunca alcance uma operação de assinatura. A página da capacidade documenta o fluxo de trabalho e um exemplo de barreira trabalhado.

Veja também

Política de Certificate Transparency para certificados de assinatura — a página da capacidade: fluxo de trabalho, configuração e uma barreira de política trabalhada.
Segurança — NextPDF Enterprise — a superfície combinada de segurança do Enterprise.
Signature — Referência Detalhada — o produtor de longo prazo PAdES B-LT e B-LTA.
Segurança / Assinatura (Core) — o signatário CMS do Core e o contrato de estratégia de assinatura.
Certificate Transparency · SCT — termos do glossário.

Fronteira de publicação

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