Enterprise edición

Certificate Transparency — Referencia detallada

De un vistazo

Esta página es la referencia detallada de la superficie de Certificate Transparency (CT) en NextPDF Enterprise. La superficie es un único objeto de valor inmutable: NextPDF\Enterprise\Security\CertificateTransparency\CtValidationResult. Resume la postura de Signed Certificate Timestamp (SCT) de un certificado de firma X.509. Lleva el indicador de la extensión SCT, los recuentos totales y válidos de SCT, y los identificadores de los logs emisores. Expone un método de política, meetsPolicy(), que es una comprobación del umbral mínimo de SCT. El tipo representa un resultado; no extrae SCT, no verifica firmas de SCT ni contacta con logs de CT. Para la guía a nivel de flujo de trabajo, véase Política de Certificate Transparency para certificados de firma.

Disponibilidad y licencia

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin esa habilitación no carga las clases de la capacidad. Compare ediciones y obtenga una licencia.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
`CtValidationResult`	—	Objeto de valor inmutable que resume la postura SCT de un certificado	—	No lanza	`final readonly`; las cuatro propiedades promovidas en el constructor son públicas
`CtValidationResult::__construct`	`bool $hasSctsExtension`, `int $totalScts`, `int $validScts`, `array<string> $logIds`	Almacena los valores suministrados tal cual, sin validación ni reconciliación	Nueva instancia de `CtValidationResult`	Sin `@throws` declarado; PHP lanza `TypeError` ante tipos de argumento no coincidentes bajo `strict_types`	Propiedades públicas `readonly` promovidas
`CtValidationResult::meetsPolicy`	`int $minimumScts = 2`	Compara el recuento de SCT válidos con el umbral: `validScts >= $minimumScts`	`bool`	No lanza	Cuenta solo los SCT válidos; no comprueba la distinción de logs ni la presencia de la extensión

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

Propiedades públicas readonly

Propiedad	Tipo	Significado
`$hasSctsExtension`	`bool`	Si el certificado contiene la extensión SCT
`$totalScts`	`int`	Número total de SCT encontrados en la extensión
`$validScts`	`int`	Número de SCT con firmas válidas, según se determina aguas arriba
`$logIds`	`array<string>`	Identificadores de log (hashes SHA-256) de los logs de CT que emitieron los SCT

Contrato de comportamiento

CtValidationResult es un valor de resultado. Representa el desenlace de la extracción y verificación de SCT que realizó el entorno del llamador. No analiza certificados, no verifica firmas de SCT, no consulta logs ni envía certificados a logs.
La extensión en cuestión es la extensión de certificado X.509v3 de SCT embebidos, identificada por el OID 1.3.6.1.4.1.11129.2.4.2 — RFC 6962 §3.3. Un SCT lleva una versión, un identificador de log, una marca de tiempo, extensiones y la firma del log sobre la entrada — RFC 6962 §3.2.
Cada elemento de $logIds es un identificador de log según lo define RFC 6962 §3.2: el hash SHA-256 de la clave pública del log sobre su SubjectPublicKeyInfo codificado en DER. El tipo almacena las cadenas tal como se suministran y no las recalcula ni las valida.
meetsPolicy() implementa exactamente una comparación: el recuento de SCT válidos es mayor o igual que el umbral. El umbral por defecto es 2.
meetsPolicy() no consulta $hasSctsExtension. Una política que deba fallar ante una extensión ausente debe verificar la propiedad por separado, antes o junto con la comprobación del umbral.
meetsPolicy() no elimina duplicados de $logIds. Una política que exija SCT de logs independientes debe comprobar la distinción a través del propio $logIds.
El constructor almacena las entradas literalmente. No realiza comprobaciones de rango ni comprobaciones de coherencia entre campos.
Las instancias son inmutables (final readonly). Todas las lecturas y la comprobación del umbral son deterministas y sin efectos secundarios.
El valor del umbral es la elección de política del operador; NextPDF no impone ningún número. La fuente del paquete anota un punto de referencia del ecosistema: la política de CT de Chrome, a fecha de 2024, espera al menos dos SCT de logs distintos para certificados con vidas útiles de hasta 180 días, y tres para certificados de mayor duración. Se trata de una política de un programa de navegador, no de un requisito del IETF.
La ubicación prevista es una barrera previa a la firma: un flujo de trabajo de firma se niega a construir un firmante cuando la comprobación falla. La justificación sigue el modelo de confianza de CT: un SCT es la promesa del log de incorporar el certificado, y las partes que confían rechazan un certificado que carece de un SCT válido — RFC 6962 §3. La versión 2.0 de CT mantiene el mismo modelo: un log que acepta un envío devuelve un SCT, que el remitente valida antes de confiar en él — RFC 9162 §3.

Casos límite y modos de fallo

Umbral cero o negativo. meetsPolicy(0) devuelve true para cualquier $validScts no negativo. El método no rechaza el valor. Elija un umbral de al menos 1.
Extensión ausente, recuentos positivos. Cuando $hasSctsExtension es false pero $validScts alcanza el umbral, meetsPolicy() devuelve true igualmente. La barrera debe comprobar $hasSctsExtension explícitamente cuando la ausencia deba provocar un fallo; la página de la capacidad muestra este patrón.
Identificadores de log duplicados. N SCT válidos de un único log satisfacen un umbral de N. La comprobación del umbral no formula ninguna afirmación de independencia. Las políticas de distinción de logs inspeccionan $logIds.
Recuentos incoherentes. Un $validScts mayor que $totalScts, o un recuento negativo, se almacena tal como se suministra. No se lanza ninguna excepción. El paso de extracción aguas arriba es responsable de la coherencia de la entrada.
Cadenas de identificador de log sin validar. El tipo no impone una forma de 32 bytes ni hexadecimal a los elementos de $logIds. Los identificadores malformados pasan sin cambios.
Sin ruta de excepción. Ningún método de esta superficie lanza excepciones bajo tipos PHP válidos. El modo de fallo de la comprobación de política es el rechazo (false), no una excepción. Los tipos de argumento no coincidentes provocan un TypeError de PHP bajo strict_types, como en cualquier API PHP tipada.

Comportamiento en modo FIPS

CtValidationResult no realiza ningún cálculo criptográfico. No calcula ningún resumen ni verifica ninguna firma. Que la firma de un SCT se cuente como válida se decide aguas arriba, en el componente que realizó la verificación antes de construir el resultado. El perfil de política criptográfica FIPS 140-3 de Enterprise, documentado junto con el módulo de seguridad, no altera por tanto el comportamiento de este tipo.

Conformidad

Afirmación	Estándar	Cláusula
Un SCT es la promesa del log de incorporar el certificado; las partes que confían rechazan un certificado que carece de un SCT válido.	RFC 6962	§3
Un SCT lleva una versión, un identificador de log, una marca de tiempo, extensiones y la firma del log sobre la entrada.	RFC 6962	§3.2
El identificador de log es el hash SHA-256 de la clave pública del log sobre su `SubjectPublicKeyInfo` codificado en DER.	RFC 6962	§3.2
Los SCT embebidos viajan en una extensión de certificado X.509v3 identificada por el OID `1.3.6.1.4.1.11129.2.4.2`.	RFC 6962	§3.3
En la versión 2.0 de CT, un log que acepta un envío devuelve un SCT, que el remitente valida antes de confiar en él.	RFC 9162	§3

Todas las cláusulas están parafraseadas; NextPDF no reproduce texto normativo. NextPDF no formula ninguna afirmación de conformidad ni de certificación de Certificate Transparency. NextPDF Enterprise no es un log de CT, ni un auditor, ni un monitor. No envía certificados a logs y no afirma un resultado de verificación de CT. El tipo representa recuentos e identificadores que produjo el entorno del llamador, y evalúa un umbral elegido por el llamador. Los programas de CT de los navegadores, como el de Chrome, son políticas del ecosistema y no requisitos normativos del IETF; seleccionar y satisfacer tal política es responsabilidad del operador.

Notas de desarrollo

El objeto de valor no tiene dependencias ni E/S. Construya las instancias directamente en las pruebas unitarias.
Pruebas de límite recomendadas: recuento válido exactamente en el umbral, uno por debajo del umbral, extensión ausente con recuentos en el umbral e identificadores de log duplicados frente a una política de distinción.
La clase se declara bajo strict_types=1 con propiedades promovidas tipadas. Los tipos de argumento incorrectos provocan un TypeError de PHP en el llamador.
La clase lleva una anotación de paquete @since de 1.0.0 y referencia RFC 6962 y RFC 9162 en la documentación de su código fuente.
El parámetro $logIds se documenta como array<string>; el análisis estático trata la propiedad como un array de cadenas. Conserve esa forma al construir resultados.
Coloque su verificación de CT aguas arriba y esta barrera de umbral antes de la construcción del firmante, de modo que un certificado con logs insuficientes nunca llegue a una operación de firma. La página de la capacidad documenta el flujo de trabajo y un ejemplo de barrera resuelto.

Véase también

Política de Certificate Transparency para certificados de firma — la página de la capacidad: flujo de trabajo, configuración y una barrera de política resuelta.
Seguridad — NextPDF Enterprise — la superficie de seguridad combinada de Enterprise.
Firma — Referencia detallada — el productor a largo plazo PAdES B-LT y B-LTA.
Seguridad / Firma (Core) — el firmante CMS de Core y el contrato de estrategia de firma.
Certificate Transparency · SCT — términos del glosario.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbooks y los prefijos de tickets quedan fuera del alcance.