cybercore-signer/docs/a1-a3-certificates.md

Certificados Digitais A1, A3 e PKCS#11

Guia Técnico de Suporte a Provedores Criptográficos, Hardware PC/SC e ICP-Brasil

O CyberCore Signer fornece uma camada unificada de abstração para gerenciamento e consumo de certificados digitais brasileiros padrão ICP-Brasil, cobrindo certificados em arquivo de software (A1) e dispositivos físicos criptográficos em hardware (A3 via tokens USB e cartões inteligentes smartcards).

---

1. Certificados Digitais A1 (Software / PKCS#12)

Os certificados padrão A1 são contêineres criptográficos protegidos por senha em formato .pfx ou .p12.

1.1 Arquitetura e Ciclo de Vida

1. Importação: O usuário seleciona o arquivo via diálogo nativo (FileChooser) na interface ou pelo método de importação no Dashboard.
2. Coleta Segura de Senha: A senha é obtida por meio do diálogo A1PasswordDialog e armazenada estritamente em um array de caracteres char[] volátil. Logo após o carregamento do KeyStore, o array é preenchido com zeros via Arrays.fill(passwordChars, (char) 0).
3. Instanciação JCA/JCE: O provedor Pkcs12CertificateProvider inicializa um KeyStore.getInstance("PKCS12") e extrai o certificado X.509 e o manipulador da chave privada (PrivateKey).
4. Isolamento de Memória: A chave privada nunca é serializada, exportada para disco ou enviada em logs. Durante a assinatura, a chave privada em memória gera os bytes da assinatura via Signature.getInstance("SHA256withRSA").

---

2. Certificados Digitais A3 no Windows (Windows Certificate Store)

No sistema operacional Microsoft Windows (Windows 10 e Windows 11), a grande maioria dos middlewares de fabricantes de tokens e smartcards registra os certificados automaticamente no repositório de certificados pessoais do usuário (Windows-MY).

2.1 Funcionamento do WindowsCertificateStoreProvider

• Integração SunMSCAPI / CNG: O agente consome o provedor JCA nativo SunMSCAPI (KeyStore.getInstance("Windows-MY")), integrando-se diretamente à CryptoAPI e à moderna Cryptography Next Generation (CNG) do Windows.
• Preservação no Chip Físico: A chave privada nunca sai do chip criptográfico do token. As operações de assinatura delegam a cifragem ao módulo de segurança em hardware (HSM/Token).
• Diálogo Nativo de PIN do Fabricante: Quando o token exige autenticação por PIN para liberar a chave privada, a janela nativa do próprio driver do fabricante (ex: diálogo nativo SafeSign ou SafeNet) é exibida com total segurança pelo subsistema de segurança do Windows.
• Tratamento de Chaves Não Exportáveis: O CyberCore Signer respeita integralmente a flag de chave privada não exportável, utilizando apenas referências de handle sem tentar copiar os bytes brutos da chave.

---

3. Acesso Direto a Hardware PKCS#11 (Tokens USB e Smartcards)

Para ambientes corporativos que requerem comunicação direta com bibliotecas de middleware ou para execução em ambientes Linux, o componente Pkcs11CertificateProvider interage com o driver PKCS#11 do fabricante através do módulo do JDK jdk.crypto.cryptoki (SunPKCS11).

3.1 Mapeamento de Middlewares Homologados no Brasil

O CyberCore Signer possui rotinas automáticas de varredura nos diretórios padrão do sistema (System32, SysWOW64 no Windows e /usr/lib/, /usr/local/lib/ no Linux):

Fabricante / Modelo	Biblioteca Windows (DLL)	Biblioteca Linux (.so)	Tipo de Dispositivo
SafeSign Identity Client (AET / GD)	aetpkss1.dll	libaetpkss.so	Tokens e Smartcards (Certisign, Valid, Serasa)
SafeNet Authentication Client (Gemalto / Thales)	eps2003csp11.dll, eTPKCS11.dll	libeTPkcs11.so	Tokens eToken Pro / 5110 (Serpro, Safeweb)
ACOS / Oberthur (Idemia)	acospkcs11.dll, OcsCryptoki.dll	libacospkcs11.so	Smartcards e leitores de cartão
Watchdata / PROXKey	Watchdata ProxKey PKCS11.dll	libwatchdata.so	Tokens USB
OpenSC (Padrão Aberto)	opensc-pkcs11.dll	opensc-pkcs11.so	Leitores genéricos PC/SC e smartcards

3.2 Configuração Dinâmica do Provedor SunPKCS11

A configuração do provedor é criada dinamicamente em memória (sem gravar arquivos temporários em disco com dados sensíveis):

name = CyberCore-Token
library = C:\Windows\System32\aetpkss1.dll
slotListIndex = 0

---

4. Monitoramento Dinâmico de Hardware (SmartCardWatcher)

O componente SmartCardWatcher executa um loop em segundo plano baseado na API padrão javax.smartcardio (subsistema PC/SC):

1. Detecção de Conexão (Card Inserted):
   • Detecta quando um novo smartcard ou token USB é conectado a qualquer leitora do sistema.
   • Dispara recarregamento assíncrono do repositório de certificados.
   • Notifica a interface gráfica (UIEventListener) e emite evento de auditoria (AUDITORIA [TOKEN_INSERTED]).
2. Detecção de Desconexão (Card Removed):
   • Ao detectar a remoção do dispositivo, registra imediatamente o evento de auditoria AUDITORIA [TOKEN_REMOVED].
   • Limpa e zera os buffers de memória de PIN mantidos pelo PinSessionManager.
   • Força o encerramento das conexões com o leitor via SmartCardSessionManager para liberar handles travados no sistema operacional.
3. Serialização de Concorrência (signLock):
   • Como grande parte dos drivers de smartcard e chips criptográficos físicos não suporta acesso concorrente multi-thread, todas as requisições de assinatura são processadas de forma estritamente sequencial (fila FIFO garantida por ReentrantLock).

---

5. Extração e Parsing de Identidade ICP-Brasil (OIDs X.509)

O CyberCore Signer implementa o analisador de extensões X.509 conforme os padrões da Infraestrutura de Chaves Públicas Brasileira (ICP-Brasil) estabelecidos pelo ITI (normas DOC-ICP-04).

As informações são extraídas da extensão SubjectAlternativeName (OID 2.5.29.17) e analisadas a partir de seus identificadores de objeto (OIDs):

5.1 OID ICP-Brasil de Pessoa Física (e-CPF) — 2.16.76.1.3.1

Contém uma estrutura ASN.1 com as informações cadastrais do titular:

• Data de Nascimento: 8 caracteres no formato DDMMAAAA;
• CPF do Titular: 11 dígitos numéricos;
• Número do NIS/PIS/PASEP: 11 dígitos numéricos;
• Registro Geral (RG): Número do documento de identidade;
• Órgão Expedidor e UF: Identificação do órgão emissor.

5.2 OID ICP-Brasil de Pessoa Jurídica (e-CNPJ) — 2.16.76.1.3.3

Contém os dados cadastrais da empresa e do seu representante legal:

• CNPJ da Entidade: 14 dígitos numéricos;
• Nome do Responsável: Nome completo do signatário cadastrado na Receita Federal.

5.3 Demais OIDs Mapeados

• OID 2.16.76.1.3.2: Título de Eleitor, zona e seção eleitoral.
• OID 2.16.76.1.3.4: Cadastro Específico do INSS (CEI / CAEPF).

Essa extração permite ao agente preencher automaticamente o nome e documento do signatário para o SDK Web e selos visuais em PDF, garantindo conformidade com a legislação e auditoria fiscal.