docs: update documentation files and project README structure
This commit is contained in:
Claudecio Martins
+77
-23
@@ -1,46 +1,100 @@
|
||||
# Certificados Digitais A1, A3 e PKCS#11
|
||||
|
||||
O **CyberCore Signer** oferece suporte abrangente aos formatos e repositórios de certificados digitais padrão ICP-Brasil utilizados no Brasil.
|
||||
> **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 A1 são arquivos com extensão `.pfx` ou `.p12` protegidos por senha.
|
||||
Os certificados padrão A1 são contêineres criptográficos protegidos por senha em formato `.pfx` ou `.p12`.
|
||||
|
||||
### Fluxo de Uso
|
||||
1. O usuário seleciona o arquivo via diálogo nativo (`FileChooser`) na interface ou importa via tela de Dashboard.
|
||||
2. É solicitada a senha em um diálogo seguro (`A1PasswordDialog`), mantida em `char[]` temporário e sobrescrita com zeros logo após a leitura da chave.
|
||||
3. O provedor `Pkcs12CertificateProvider` instancia um `KeyStore.getInstance("PKCS12")` e extrai os metadados do certificado X.509 (`subject`, `issuer`, `validade`, `algoritmo`, `tamanho da chave`).
|
||||
4. Durante a assinatura, a chave privada em memória gera a assinatura digital via `Signature.getInstance("SHA256withRSA")`.
|
||||
### 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 Windows 10/11, a maioria dos drivers de tokens USB e Smart Cards (ex: SafeSign, SafeNet Authentication Client, Serpro, Certisign) registra seus certificados diretamente no repositório de certificados do usuário (`Windows-MY`).
|
||||
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`).
|
||||
|
||||
### Vantagens do Provider `WindowsCertificateStoreProvider`
|
||||
- Acessa certificados físicos via CryptoAPI (CAPI) e Cryptography Next Generation (CNG) através do provedor JDK `SunMSCAPI`.
|
||||
- A chave privada permanece dentro do chip criptográfico do token.
|
||||
- Quando o token exige autenticação por PIN, a janela nativa do próprio driver do fabricante é invocada com segurança pelo sistema operacional Windows.
|
||||
### 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. Hardware PKCS#11 Direto (Tokens USB e Smartcards)
|
||||
## 3. Acesso Direto a Hardware PKCS#11 (Tokens USB e Smartcards)
|
||||
|
||||
Para ambientes onde se deseja acesso direto ao middleware ou no Linux:
|
||||
- `Pkcs11CertificateProvider` pesquisa bibliotecas DLL / SO padrão:
|
||||
- `eps2003csp11.dll` (SafeNet / eToken)
|
||||
- `aetpkss1.dll` (SafeSign AET)
|
||||
- `acospkcs11.dll` (ACOS / G&D)
|
||||
- `opensc-pkcs11.dll` / `opensc-pkcs11.so` (OpenSC)
|
||||
- Utiliza o provider SunPKCS11 do JDK (`jdk.crypto.cryptoki`).
|
||||
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):
|
||||
|
||||
```properties
|
||||
name = CyberCore-Token
|
||||
library = C:\Windows\System32\aetpkss1.dll
|
||||
slotListIndex = 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Monitoramento Dinâmico de Hardware (`SmartCardWatcher`)
|
||||
|
||||
O componente `SmartCardWatcher` monitora os leitores PC/SC em segundo plano:
|
||||
- **Ao inserir um token:** Atualiza a lista de certificados automaticamente e notifica a interface gráfica.
|
||||
- **Ao remover o token:** Registra evento de auditoria (`AUDITORIA [TOKEN_REMOVED]`), limpa o cache de PIN de sessão em `PinSessionManager` e força um warm reset via `SmartCardSessionManager`.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user