cybercore-signer/docs/compatibility.md

Matriz de Compatibilidade de Hardware e Dispositivos Criptográficos A3

Este documento apresenta a matriz técnica de compatibilidade de tokens USB, smartcards e leitores criptográficos suportados pelo CyberCore Signer, detalhando drivers, middlewares e o status de homologação de cada dispositivo.

---

1. Princípio de Transparência e Rastreabilidade

Conforme as diretrizes mestras do projeto:

Testes dependentes de hardware só podem ser declarados executados quando o hardware realmente estiver disponível no ambiente de teste. Nunca invente suporte a dispositivos ou fabricantes que não tenham sido realmente testados.

O CyberCore Signer utiliza duas camadas complementares para acesso a dispositivos físicos no Windows e Linux:

1. Windows Certificate Store (CAPI / CNG): Acesso transparente a qualquer token ou smartcard cujo middleware instale um CSP (Cryptographic Service Provider) ou KSP (Key Storage Provider) no Windows.
2. SunPKCS11 (jdk.crypto.cryptoki): Comunicação direta via padrão PKCS#11 (bibliotecas .dll no Windows ou .so no Linux), garantindo independência de fabricantes.
3. CI Automatizado via SoftHSM2: O pipeline de integração contínua (CI) valida a pilha criptográfica PKCS#11 utilizando o emulador de hardware criptográfico SoftHSM2, testando ciclos completos de inicialização de token, busca de chaves e assinatura matemática SHA-256 com chave RSA sem depender de conexões físicas de hardware no servidor de build.

---

2. Matriz de Compatibilidade de Tokens e Smartcards

Fabricante / Modelo	Tipo de Dispositivo	Middleware / Driver	Biblioteca PKCS#11	Status de Homologação
SoftHSM2 (Emulador PKCS#11)	Emulador de Hardware Criptográfico	SoftHSM2 v2.6+	libsofthsm2.so / softhsm2.dll	Validado no CI Automatizado (Gitea)
Thales / SafeNet eToken 5110	Token USB Criptográfico	SafeNet Authentication Client (SAC)	eps2003csp11.dll	Compatível via Windows Store / PKCS#11 (Pendente hardware físico)
AET / GD StarSign (SafeSign)	Smartcard / Token USB	SafeSign Identity Client	aetpkss1.dll / libaetpkss.so	Compatível via Windows Store / PKCS#11 (Pendente hardware físico)
Gemalto IDPrime (MD 830 / 840)	Token USB / Smartcard	IDPrime Minidriver / Gemalto CC	gclib.dll / libgclib.so	Compatível nativamente via Windows CNG Minidriver
Oberthur / Idemia Cosmo	Smartcard ICP-Brasil	AWPS / ACOS PKCS#11	acospkcs11.dll / libacospkcs11.so	Compatível via Windows Store / PKCS#11 (Pendente hardware físico)
Watchdata PROXKey	Token USB Criptográfico	Watchdata Middleware	Watchdata ProxKey PKCS11.dll	Compatível via Windows Store / PKCS#11 (Pendente hardware físico)
OpenSC (Padrão Aberto)	Leitores PC/SC genéricos e Smartcards	OpenSC Suite	opensc-pkcs11.dll / opensc-pkcs11.so	Compatível via PKCS#11 (Linux e Windows)

---

3. Gestão de Concorrência e Conflito de Hardware (signLock)

Grande parte dos microcontroladores de smartcards e tokens USB físicos (chips ISO 7816) não possui suporte a canais concorrentes multi-thread. Se duas requisições de assinatura tentarem acessar o chip simultaneamente através do middleware:

• O dispositivo trava com erro CKR_DEVICE_ERROR ou SCARD_E_SHARING_VIOLATION.
• O leitor pode exigir reinicialização do serviço PC/SC (scardsvr) ou desplugue físico do token.

Solução Arquitetural do CyberCore Signer

1. Fila Serializada (FIFO) via ReentrantLock: Todas as operações criptográficas de assinatura no subsistema A3 passam obrigatoriamente pela trava signLock, enfileirando requisições concorrentes transparentemente.
2. Sessão PC/SC Desacoplada (SmartCardWatcher): O monitoramento de inserção e remoção utiliza javax.smartcardio de forma assíncrona, notificando a interface gráfica sem bloquear o canal criptográfico do SunPKCS11.
3. Limpeza Imediata de Memória: Ao desconectar o dispositivo, o evento TOKEN_REMOVED força a limpeza imediata de buffers e o encerramento das conexões com o leitor (SmartCardSessionManager).

---

4. Requisitos de Instalação no Cliente

1. Windows 10 / 11 (64-bit):
   • O aplicativo desktop já embute seu próprio runtime Java (OpenJDK 25 LTS via jpackage), sem exigir Java instalado na máquina do usuário.
   • O usuário deve manter instalado o software/driver fornecido pela Autoridade Certificadora emissora do token (ex: SafeNet Authentication Client ou SafeSign).
2. Linux (Ubuntu / Debian / Fedora):
   • O serviço pcscd deve estar em execução (sudo systemctl enable --now pcscd).
   • Biblioteca de middleware do fabricante instalada em /usr/lib/ ou /usr/lib/x86_64-linux-gnu/.