Identidade do certificado

Ler o CPF/CNPJ do certificado, recusar antes do PIN e restringir quem pode assinar.

Antes de o usuário digitar o PIN, a API já validou o certificado e devolveu a identidade dele. Este guia mostra como usar essa identidade, recusar o certificado errado antes do PIN e restringir quem pode assinar.

O que a API valida no prepare#

No prepare, a API confere a cadeia até uma raiz do contexto de segurança escolhido, a validade e o uso da chave (o certificado precisa poder assinar). Se algo falhar, o erro vem antes do PIN, e nada é gasto. Nos perfis AD-RC e AD-RA ela também consulta a revogação (LCR e OCSP).

A resposta traz a identidade em certificate:

{
  "thumbprint": "…",
  "subjectDn": "CN=MARIA DA SILVA:12345678909,OU=…,O=ICP-Brasil,C=BR",
  "issuerDn": "CN=AC Exemplo,OU=…,O=ICP-Brasil,C=BR",
  "subjectCn": "MARIA DA SILVA",
  "issuerCn": "AC Exemplo",
  "serialNumber": "…",
  "pkiBrazil": { "kind": "pf", "cpf": "12345678909", "cnpj": null, "…": "…" }
}

CPF, CNPJ e demais dados: pkiBrazil#

O bloco pkiBrazil é lido pelo servidor dos campos ICP-Brasil do certificado. Sempre existe: fora da ICP-Brasil, todos os campos são null.

• Os valores vêm só com dígitos, sem máscara ("12345678909"). Campo ausente, zerado ou de tamanho errado vira null: nunca vem lixo.
• Os dígitos verificadores não são conferidos: cabe ao seu formulário, se quiser.

Recusar antes do PIN#

O padrão para garantir que a pessoa certa assina: compare o CPF ou CNPJ do certificado com o que o seu cadastro espera, no prepare, e descarte a sessão se não bater.

$p  = $api->prepare($token, $certificadoDerBase64);
$pk = $p['certificate']['pkiBrazil'];

$daAssinatura = array_filter([$pk['cpf'], $pk['cnpj'], $pk['responsibleCpf']]);
if (!in_array($cpfOuCnpjEsperado, $daAssinatura, true)) {   // só dígitos nos dois lados
    $api->discard($token);                                  // nada foi assinado, nada foi gasto
    throw new DomainException('certificado de outra pessoa');
}

Para um e-CNPJ, aceite o CNPJ da empresa ou o CPF do responsável, conforme a sua regra. Em JavaScript (Node), a opção beforeSign de signPades faz o mesmo: ela roda depois do prepare e antes do PIN, e lançar um erro descarta a sessão.

Restringir a AC emissora: acceptableIssuers#

No início da assinatura, acceptableIssuers limita o certificado a ACs específicas. A restrição é imposta no servidor, no prepare, antes do PIN:

$api->startMultipart($arquivos, 'pades-icpbrasil-ad-rb', 'icp-brasil', null,
    ['CN=AC SOLUTI Multipla v5', 'a3f1…64 caracteres hexadecimais da impressão digital de uma AC']);   // até 20 itens

Cada item é o DN (RFC 4514, em qualquer ordem, sem diferenciar maiúsculas) ou a impressão digital SHA-256 de uma AC da cadeia validada do certificado (intermediária ou raiz; o certificado final não conta). Basta um item casar. A conferência acontece depois de a cadeia ser validada contra as raízes do contexto: uma AC de mesmo nome que não esteja na cadeia não passa. Sem casar, a API responde 422 certificate_issuer_not_allowed.

Por que o certificado foi recusado: error.reason#

As recusas de certificado (certificate_not_trusted, invalid_certificate e certificate_issuer_not_allowed) trazem um subcódigo estável, sem dados pessoais, para a sua tela explicar sem adivinhar:

try {
    $api->prepare($token, $der);
} catch (ApiException $e) {
    if ($e->errorCode === 'certificate_not_trusted') {
        $motivo = $e->reason;   // 'expired' | 'chain' | 'key_usage' | ...
    }
}