Níveis de garantia eIDAS

Em resumo

O NextPDF Enterprise transforma a evidência de listas confiáveis da UE em um Nível de Garantia (LoA) eIDAS explícito. O serviço NextPDF\Enterprise\Security\Eidas\LoaMapping classifica uma entrada de serviço de confiança como Low, Substantial ou High. Ele retorna uma LoaAssertion que carrega o nível mais códigos de motivo legíveis por máquina. Seu fluxo de trabalho pode aplicar controle por garantia — “exigir High” — e arquivar os motivos como evidência de auditoria. Uma guarda complementar, CertPiiGuard, oculta os campos de identidade do signatário antes que os registros de auditoria deixem o processo.

Dois limites enquadram essa capacidade de forma honesta. Primeiro, a qualificação sempre pertence ao prestador de serviços de confiança (TSP) sob supervisão do Estado-membro. O NextPDF afirma uma classificação sobre evidência publicada; ele nunca concede, confere nem certifica qualificação. Segundo, esta página cobre apenas a asserção e o mapeamento de LoA. A política estrutural PAdES eidasQualified(), incluindo seus critérios de aprovação/reprovação, está documentada em Validação.

Disponibilidade e licenciamento

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

Instalação

composer require nextpdf/enterprise

O metapacote nextpdf/premium também resolve o pacote Enterprise. A ativação usa seu envelope de licença Enterprise; consulte Licenciamento e ativação. As classes eIDAS não precisam de nenhuma extensão PHP além da linha de base do mecanismo. Elas fazem autoload sob NextPDF\Enterprise\Security\Eidas e NextPDF\Enterprise\Signature\Eidas.

Visão geral conceitual

O Regulation (EU) No 910/2014 (eIDAS) define três níveis de garantia: low, substantial e high (Article 8(1)). Cada nível expressa um grau de confiança em uma identidade declarada. O nível high adiciona controles cujo propósito é impedir — não apenas reduzir — o uso indevido ou a alteração da identidade (Article 8(2)(c)). O Article 8 define esses níveis para esquemas de identificação eletrônica. O NextPDF reutiliza o mesmo vocabulário para classificar a evidência de serviço de confiança por trás de um certificado de assinatura. Essa reutilização é uma convenção de engenharia para controle por política e auditoria, não uma equivalência jurídica.

O enum LoaLevel modela os três níveis. Seus valores de apoio são as URIs de LoA do eIDAS em vez de rótulos simples, portanto uma asserção persistida carrega o identificador completo. rank() fornece uma ordem total (Low = 1, Substantial = 2, High = 3), e meetsOrExceeds() compara contra um piso exigido.

LoaMapping calcula um nível a partir de uma entrada de lista confiável — um TspService do subsistema de listas confiáveis do Enterprise (NextPDF\Enterprise\Security\Tsl). O mapeamento é determinístico:

Evidência da lista confiável	Nível	Códigos de motivo
O status do serviço não é granted	Low	service_not_granted
O tipo de serviço não é CA/QC	Low	service_not_qualified_ca
CA/QC granted com QCWithQSCD e sem QCNoQSCD	High	ca_qc_with_qscd mais esig_or_eseal ou qc_default
CA/QC granted em outros casos	Substantial	ca_qc_no_qscd_or_unspecified

O qualificador QSCD (dispositivo qualificado de criação de assinatura) é o pivô. Sob o Article 3(12), uma assinatura eletrônica qualificada exige tanto um certificado qualificado quanto um dispositivo qualificado de criação. Uma declaração de lista confiável de que os certificados são gerenciados em um QSCD é, portanto, a evidência que sustenta uma asserção High. Sem essa declaração, uma CA qualificada granted ainda sustenta Substantial, nunca High.

O resultado é uma LoaAssertion: o nível mais uma lista de códigos de motivo. Os motivos permitem que um consumidor de auditoria re-derive a classificação a partir da mesma evidência posteriormente. Avaliadores de política a jusante podem registrar a asserção junto com o resultado de uma validação de assinatura.

Mais uma peça é fornecida neste módulo: CertPiiGuard. Quando artefatos de validação são serializados em pacotes de auditoria JSON, o certificado do signatário carrega dados pessoais — o Subject CN, os atributos de email e o atributo serialNumber, que pode codificar um identificador nacional para pessoas físicas. O GDPR Article 5(1)(c) exige que o processamento seja limitado ao que é necessário. Portanto, a guarda oculta esses campos por padrão, substituindo os valores por [REDACTED] enquanto preserva o envelope estrutural (campos de organização, país, cadeia e status). Os consumidores ainda podem verificar se uma assinatura passou sem saber quem assinou.

Por que funciona assim

A decisão de sustentação é separar a asserção de garantia do veredito de validação. A validação de assinatura, conforme a ETSI EN 319 102-1, termina em uma indicação de status — TOTAL-PASSED, TOTAL-FAILED ou INDETERMINATE — e esse veredito pertence à camada de validação. O mapeamento de LoA é uma classificação distinta e reproduzível sobre a evidência da lista confiável, com códigos de motivo em vez de um rótulo simples. Isso impede o NextPDF de apresentar uma afirmação de garantia como um resultado de validação, ou um resultado de validação como uma concessão de qualificação. Também torna o mapeamento conservador por construção: evidência ausente ou ambígua reduz o nível, nunca o eleva.

Contexto de projeto: Assinaturas qualificadas, explicadas.

Superfície da API

Todos os símbolos abaixo são API pública em nextpdf/enterprise 3.1.0.

LoaLevel

enum LoaLevel: string
{
    case Low = 'http://eidas.europa.eu/LoA/low';
    case Substantial = 'http://eidas.europa.eu/LoA/substantial';
    case High = 'http://eidas.europa.eu/LoA/high';

    public function rank(): int

    public function meetsOrExceeds(self $required): bool
}

Lança ou falha com: nada de rank() ou meetsOrExceeds(). A construção nativa do enum via LoaLevel::from() lança \ValueError em uma URI não reconhecida; LoaLevel::tryFrom() retorna null em vez disso.

LoaMapping

final class LoaMapping
{
    public function loaForService(TspService $service): LoaAssertion
}

Lança ou falha com: nada. O método é total — toda entrada TspService produz uma LoaAssertion.

Os DTOs de entrada NextPDF\Enterprise\Security\Tsl\TspService e NextPDF\Enterprise\Security\Tsl\TspServiceQualifier são DTOs públicos estáveis (@api). O mapeamento consulta TspService::STATUS_GRANTED, TspService::TYPE_CA_QC e as constantes de qualificador TspServiceQualifier::QSCD_STATEMENT (QCWithQSCD), TspServiceQualifier::NO_QSCD (QCNoQSCD), TspServiceQualifier::FOR_ESIG e TspServiceQualifier::FOR_ESEAL.

LoaAssertion

final readonly class LoaAssertion
{
    /**
     * @param list<non-empty-string> $reasons Machine-readable reason codes for the assertion.
     */
    public function __construct(
        public LoaLevel $level,
        public array $reasons,
    ) {}
}

Lança ou falha com: nada. Objeto de valor imutável.

CertPiiGuard

final readonly class CertPiiGuard
{
    public function __construct(
        private bool $disclosePii = false,
    ) {}

    public function disclosesPii(): bool

    public function guardSignerCommonName(string $signer): string

    public function guardDistinguishedName(string $dn): string

    public function guardTsaName(string $tsaName): string

    public function guardRootIssuer(string $issuer): string

    public function guardChainIssue(string $issue): string
}

Lança ou falha com: nada. As guardas são transformações puras de string. Em um componente de DN que não pode ser tokenizado com confiança, a guarda falha de forma fechada e reduz o componente a [REDACTED] em vez de emitir um valor parcialmente mascarado.

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

Analise uma URI de LoA e compare-a contra um piso exigido.

loa-quick-start.php

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Security\Eidas\LoaLevel;

// A LoA URI as persisted in an audit record or received from a peer system.
$uri = 'http://eidas.europa.eu/LoA/substantial';

try {
    $level = LoaLevel::from($uri);
} catch (\ValueError $e) {
    // Unknown URI: refuse to classify. Never guess an assurance level.
    echo "Unrecognized LoA URI: {$uri}\n";
    exit(1);
}

echo 'Level: ' . $level->name . ' (rank ' . $level->rank() . ")\n";
echo 'Meets substantial: ' . ($level->meetsOrExceeds(LoaLevel::Substantial) ? 'yes' : 'no') . "\n";
echo 'Meets high: ' . ($level->meetsOrExceeds(LoaLevel::High) ? 'yes' : 'no') . "\n";

Saída esperada:

Level: Substantial (rank 2)
Meets substantial: yes
Meets high: no

Exemplo de código — Produção

Classifique uma entrada de lista confiável, aplique controle por um nível exigido e emita um registro de auditoria ocultado.

loa-audit-gate.php

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Security\Eidas\LoaLevel;
use NextPDF\Enterprise\Security\Eidas\LoaMapping;
use NextPDF\Enterprise\Security\Tsl\TspService;
use NextPDF\Enterprise\Security\Tsl\TspServiceQualifier;
use NextPDF\Enterprise\Signature\Eidas\CertPiiGuard;

// Normally produced by the Enterprise trusted-list subsystem from a
// member-state TSL; constructed inline here for a self-contained example.
$caPem = (string) file_get_contents(__DIR__ . '/example-qc-ca.pem');

$service = new TspService(
    tspName: 'Example Qualified TSP',
    serviceName: 'Example Qualified CA G2',
    serviceTypeIdentifier: TspService::TYPE_CA_QC,
    serviceStatus: TspService::STATUS_GRANTED,
    statusStartingTime: '2024-01-01T00:00:00Z',
    serviceCertificatePem: $caPem,
    qualifiers: [
        new TspServiceQualifier(qualifierUri: TspServiceQualifier::QSCD_STATEMENT),
        new TspServiceQualifier(qualifierUri: TspServiceQualifier::FOR_ESIG),
    ],
    additionalServiceInformation: [],
);

try {
    // Required floor from deployment configuration; defaults to High.
    $required = LoaLevel::from(getenv('LOA_REQUIRED') ?: LoaLevel::High->value);
} catch (\ValueError $e) {
    echo "Invalid LOA_REQUIRED URI; refusing to continue.\n";
    exit(1);
}

$mapping = new LoaMapping();
$assertion = $mapping->loaForService($service);

// Privacy by default: signer identity fields are redacted in audit output.
$guard = new CertPiiGuard();

$audit = [
    'loa' => $assertion->level->value,
    'reasons' => $assertion->reasons,
    'meets_required' => $assertion->level->meetsOrExceeds($required),
    'signer' => $guard->guardSignerCommonName('CN=Jane Example, O=Example Corp, C=DE'),
];

echo json_encode($audit, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n";

Saída esperada:

{
    "loa": "http://eidas.europa.eu/LoA/high",
    "reasons": [
        "ca_qc_with_qscd",
        "esig_or_eseal"
    ],
    "meets_required": true,
    "signer": "CN=[REDACTED], O=Example Corp, C=DE"
}

Casos extremos e armadilhas

• LoaLevel::from() lança \ValueError em URIs desconhecidas. Use LoaLevel::tryFrom() onde o tratamento de null for preferível.
• Evidência de dispositivo conflitante permanece conservadora. Um serviço que carrega tanto QCWithQSCD quanto QCNoQSCD mapeia para Substantial, não High.
• Um serviço CA/QC granted sem qualificadores mapeia para Substantial com o motivo ca_qc_no_qscd_or_unspecified — qualificado por padrão, dispositivo não comprovado.
• URIs de qualificador fora do conjunto rastreado não afetam a classificação. Qualificadores desconhecidos ou futuros nunca elevam o nível.
• O mapeamento lê apenas o status atual do serviço. Ele não avalia o histórico de statusStartingTime; janelas de ponto no tempo pertencem à camada de validação.
• Persista a URI de apoio do enum, não o inteiro de rank(). Os ranks existem apenas para comparação.
• CertPiiGuard reduz um nome simples sem = inteiramente a [REDACTED]; strings vazias passam inalteradas por todas as guardas.
• DNs legados do OpenSSL separados por barra são detectados e mascarados estruturalmente. Uma / dentro de um valor RFC 4514 é tratada como conteúdo, não como separador.
• Atributos de DN que não são PII (O, OU, C, ST, L) são preservados, de modo que o raciocínio de jurisdição sobrevive à ocultação.

Notas de segurança

• Privacidade por padrão. O construtor da guarda usa como padrão disclosePii: false. Construa new CertPiiGuard(disclosePii: true) apenas onde você tiver uma base legal documentada para processar a identidade do signatário. Isso implementa a minimização de dados do GDPR Article 5(1)(c) no limite de serialização.
• Ocultação com falha fechada. Quando um componente de DN não pode ser tokenizado com confiança, o componente inteiro é reduzido a [REDACTED]. Um controle de privacidade nunca falha de forma aberta.
• Saída determinística. As guardas usam processamento puro de strings — sem relógios, sem aleatoriedade — de modo que a saída mascarada é estável em bytes para entradas idênticas. A saída estável mantém os diffs de auditoria significativos.
• Ocultação não é criptografia. [REDACTED] remove o valor do registro. Se você precisar que a identidade seja recuperável, armazene-a separadamente sob sua própria base legal e controle de acesso.
• Lixo entra, lixo sai. Uma LoaAssertion é apenas tão confiável quanto a evidência da lista confiável por trás dela. Adquira e verifique a assinatura das listas confiáveis por meio do subsistema de listas confiáveis do Enterprise antes de alimentar entradas ao mapeamento.

Conformidade

O NextPDF Enterprise implementa comportamento informado pelo Regulation (EU) No 910/2014 Article 8 (níveis de garantia) e Article 3(12) (elementos de uma assinatura eletrônica qualificada), e pelo vocabulário de qualificadores de listas confiáveis da ETSI. Suporte não é conformidade, e conformidade não é certificação. O NextPDF não detém nenhuma certificação e não concede nenhuma. O NextPDF não é um prestador de serviços de confiança qualificado, não é um organismo de avaliação de conformidade e não é um organismo de supervisão. Uma LoaAssertion é uma classificação de software de evidência publicada. Ela não é uma determinação jurídica de qualificação ou de garantia, e não pode tornar uma assinatura qualificada.

O Regulation (EU) 2024/1183 (eIDAS 2) continua a referenciar os níveis do Article 8 e exige que as Carteiras Europeias de Identidade Digital sejam fornecidas no nível de garantia high. Esta página cita isso como contexto regulatório; o NextPDF não faz nenhuma afirmação de capacidade relacionada a carteiras.

Se uma assinatura específica satisfaz uma política estrutural orientada a eIDAS é uma questão separada, respondida pelo módulo de validação; consulte Validação.

Comportamento no modo FIPS

As classes de LoA eIDAS não realizam operações criptográficas — sem hashing, sem verificação de assinatura, sem aleatoriedade. A política de modo FIPS do Enterprise controla escolhas criptográficas, portanto ela não tem nada a controlar neste módulo. Habilitar o modo FIPS não altera o mapeamento de LoA nem o comportamento da guarda de PII. A verificação criptográfica de assinaturas e listas confiáveis é regida pelos módulos de verificação e segurança, onde a política de modo FIPS se aplica.

Contrato de comportamento

• LoaMapping::loaForService() é total e determinístico. Todo TspService produz uma LoaAssertion; o método nunca lança e não consulta relógio, rede ou estado global.
• A classificação é conservadora. Evidência ausente, desconhecida ou conflitante reduz o nível; nada o eleva exceto evidência explícita de CA/QC granted com QSCD.
• Os códigos de motivo são legíveis por máquina e estáveis: service_not_granted, service_not_qualified_ca, ca_qc_with_qscd, esig_or_eseal, qc_default, ca_qc_no_qscd_or_unspecified.
• A ordem dos níveis é fixa: Low < Substantial < High, exposta via rank() e meetsOrExceeds().
• CertPiiGuard usa a ocultação como padrão e falha de forma fechada em caso de dúvida na tokenização. Com disclosePii: true, cada guarda retorna sua entrada literalmente.
• A saída da guarda é estável em bytes para entradas idênticas.

Alternativa no Core

O NextPDF Core verifica assinaturas de PDF criptograficamente e falha de forma fechada em evidência quebrada. O Core não tem modelo de listas confiáveis da UE, não tem vocabulário LoaLevel, não tem mapeamento de LoA e não tem guarda de PII de camada eIDAS para serialização de auditoria. Apenas com o Core, você deve derivar as classificações de garantia por conta própria a partir dos dados de confiança que você mantém, e aplicar sua própria ocultação antes que os registros de auditoria deixem o processo.

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 internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora de escopo.

Veja também

• Validação — políticas de conformidade estrutural, incluindo a semântica de eidasQualified() e os critérios de aprovação/reprovação
• Verificação de assinatura — o lado de verificação criptográfica AdES/PAdES cujos relatórios a guarda de PII protege
• Segurança — Referência aprofundada — a referência aprofundada do módulo de Segurança
• Assinaturas qualificadas, explicadas — ensaio Insider sobre qualificação e garantia
• Como uma assinatura prova quem assinou — ensaio Insider sobre a confiança no lado de verificação