From cf7ac8c51c5021d1822dc3d7c699bb9fc6b24565 Mon Sep 17 00:00:00 2001 From: Claudecio Martins Date: Tue, 20 Oct 2026 15:35:21 -0300 Subject: [PATCH] docs: publish hardware compatibility matrix and align pades icp-brasil policy documentation --- docs/README.md | 2 ++ docs/compatibility.md | 53 +++++++++++++++++++++++++++++++++++++++++++ docs/pades.md | 14 ++++++++++++ 3 files changed, 69 insertions(+) create mode 100644 docs/compatibility.md diff --git a/docs/README.md b/docs/README.md index 8251b27..d0e103c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -58,6 +58,8 @@ Se você precisa implantar, homologar ou validar os aspectos de conformidade e s | [`diagnostics.md`](diagnostics.md) | Auto-testes e guia de resolução de problemas | Suporte & Operações | | [`installation.md`](installation.md) | Empacotamento com `jpackage` e instaladores MSI | DevOps & Usuários Finais | | [`release-and-versioning.md`](release-and-versioning.md) | Estratégia SemVer, metas JaCoCo e corte de tags | DevOps & Governança | +| [`compliance-testing.md`](compliance-testing.md) | Guia de Conformidade ICP-Brasil e Verificador ITI | Compliance & QA | +| [`compatibility.md`](compatibility.md) | Matriz de compatibilidade de hardware A3 e SoftHSM2 | Suporte & Hardware | | [`limitations.md`](limitations.md) | Dependências de drivers e limitações declaradas | Todos | | [`development-mode.md`](development-mode.md) | Parâmetro `--dev` e certificados de teste | Desenvolvedores Desktop | | [`sdk.md`](sdk.md) | Guia completo da biblioteca JavaScript | Desenvolvedores Web | diff --git a/docs/compatibility.md b/docs/compatibility.md new file mode 100644 index 0000000..c21580f --- /dev/null +++ b/docs/compatibility.md @@ -0,0 +1,53 @@ +# 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/`. diff --git a/docs/pades.md b/docs/pades.md index e8da082..f9d8799 100644 --- a/docs/pades.md +++ b/docs/pades.md @@ -142,3 +142,17 @@ const result = await signer.signPdfDocument({ console.log('PDF Assinado Base64:', result.signed_pdf); console.log('SHA-256 do Documento Final:', result.sha256); ``` + +--- + +## 6. Políticas de Assinatura ICP-Brasil (DOC-ICP-15) + +O padrão brasileiro de assinaturas digitais mantido pelo ITI prevê quatro perfis progressivos de conformidade: + +| Política | Denominação | Status no CyberCore Signer | Componentes Arquiteturais | +| :--- | :--- | :--- | :--- | +| **AD-RB** | Assinatura com Referência Básica | **Homologado / Ativo** | Envelope PAdES detached CMS com selo Java2D e `/ByteRange` validado pelo ITI | +| **AD-RT** | Assinatura com Referência de Tempo | **Em Integração** | Cliente TSA RFC 3161 resiliente (`TsaClient`) com retentativas e fallback | +| **AD-RC** | Assinatura com Referências Completas | **Roadmap** | Validador de cadeia (`CertificateChainValidator`) e cache de revogação (`RevocationCache`) | +| **AD-RA** | Assinatura com Referência para Arquivamento | **Roadmap** | Dicionário LTV (`/DSS`) embutido no PDF com carimbos periódicos de arquivo | +