docs: update documentation files and project README structure
This commit is contained in:
Claudecio Martins
+84
-39
@@ -1,12 +1,14 @@
|
||||
# Arquitetura do CyberCore Signer
|
||||
|
||||
O **CyberCore Signer** é um agente desktop nativo desenvolvido em Java 21+ LTS (Java 25 LTS) com interface JavaFX e segurança criptográfica JCA/JCE pura, projetado para permitir que aplicações web autorizadas solicitem assinaturas digitais ICP-Brasil padrão **A1** e **A3** diretamente da máquina do usuário.
|
||||
> **Especificação da Arquitetura Modular, Modelo de Threads e Fluxo Criptográfico**
|
||||
|
||||
O **CyberCore Signer** foi concebido a partir de princípios de alta coesão, baixo acoplamento e estrito isolamento de camadas. O software é desenvolvido em **Java 21+ LTS (Java 25 LTS)**, utilizando o runtime modular do JDK, JavaFX para a camada de apresentação e os provedores JCA/JCE da plataforma para operações criptográficas seguras.
|
||||
|
||||
---
|
||||
|
||||
## 1. Visão Geral da Arquitetura em Módulos
|
||||
|
||||
O projeto adota uma arquitetura desacoplada em múltiplos módulos Maven independentes:
|
||||
O projeto adota uma divisão modular rigorosa no Maven, garantindo que regras de negócio e algoritmos de criptografia nunca se acoplem a componentes visuais:
|
||||
|
||||
```
|
||||
cybercore-signer/
|
||||
@@ -19,43 +21,75 @@ cybercore-signer/
|
||||
└── docs/ # Especificações técnicas e manuais de integração
|
||||
```
|
||||
|
||||
### 1.1 `cybercore-core`
|
||||
- **Domínio:** Modelos imutáveis como `ManagedCertificate`, `SigningContext`, `SigningResult`, `CertificateType` e `CertificateStatus`.
|
||||
- **Criptografia:** `SigningService` e `DigestAlgorithm` utilizando exclusivamente os provedores padrão JCA/JCE (sem reimplementação manual de algoritmos).
|
||||
- **Provedores:** Abstração `CertificateProvider` com implementações:
|
||||
- `Pkcs12CertificateProvider`: leitura de arquivos `.pfx`/`.p12` em memória protegida.
|
||||
- `WindowsCertificateStoreProvider`: integração nativa com o repositório de chaves do Windows (`Windows-MY` via SunMSCAPI/CNG).
|
||||
- `Pkcs11CertificateProvider`: integração com drivers de middleware e tokens USB/Smartcards via `SunPKCS11`.
|
||||
- **Protocolo & Rede Local:** `CcspServer` escuta estritamente em `127.0.0.1:21325`, fornecendo a API REST CCSP/1.
|
||||
- **Segurança & Configurações:** `ApplicationRegistry`, `NonceManager` (proteção anti-replay), `OriginValidator`, `SmartCardSessionManager` e `AgentConfigurationService` (persistência em `~/.cybercore/config.json`).
|
||||
- **Validação Criptográfica:** `SignatureValidationService` com suporte a Assinaturas Incorporadas (PAdES PDF, CMS/P7M com conteúdo embutido, XMLDSig) e Assinaturas Destacadas (Detached CMS/P7S).
|
||||
- **Selos Visuais Personalizados:** `CustomSealStorage` (persistência em `~/.cybercore/seals/`), `PdfSealThemeRegistry` dinâmico e `CpfDisplayMode` (privacidade LGPD).
|
||||
### 1.1 Módulo `cybercore-core` (Agnóstico de UI)
|
||||
O módulo de núcleo é totalmente independente de JavaFX ou bibliotecas visuais:
|
||||
* **Domínio Imutável:** Modelos imutáveis (`ManagedCertificate`, `SigningContext`, `SigningResult`, `CertificateType`, `CertificateStatus`).
|
||||
* **Serviços de Assinatura:** `SigningService` orquestra a aplicação de algoritmos certificados (`SHA256withRSA`) delegando a operação ao provedor de certificado resolvido.
|
||||
* **Provedores de Certificados (`CertificateProvider`):** Abstração que unifica:
|
||||
- `Pkcs12CertificateProvider`: leitura de arquivos `.pfx`/`.p12` em memória com limpeza volátil de senha.
|
||||
- `WindowsCertificateStoreProvider`: integração com o repositório nativo do Windows (`Windows-MY` via SunMSCAPI/CNG).
|
||||
- `Pkcs11CertificateProvider`: integração direta com bibliotecas dinâmicas (DLL/SO) de drivers e tokens USB através do SunPKCS11.
|
||||
* **Protocolo e Rede Local:** `CcspServer` escuta exclusivamente em `127.0.0.1:21325`, fornecendo a API REST CCSP/1 com validação de origens e controle de concorrência.
|
||||
* **Segurança e Persistência:** `ApplicationRegistry`, `NonceManager` (proteção anti-replay), `OriginValidator`, `SmartCardSessionManager` e `AgentConfigurationService` com armazenamento persistente em diretório de usuário (`~/.cybercore/`).
|
||||
* **Assinatura de Documentos e Validação:** `PdfSigningService` (PAdES com salvamento incremental e carimbo TSA via PDFBox e Bouncy Castle), `XmlSigningService` (XAdES-BES e XMLDSig via `javax.xml.crypto`) e `SignatureValidationService` para conferência de integridade e signatários.
|
||||
|
||||
### 1.2 `cybercore-ui`
|
||||
- Interface desenvolvida com JavaFX 25, empregando layout moderno e simétrico de grade 3x3 de operações e coluna lateral de utilitários:
|
||||
- `MainAppView`: grade 3x3 otimizada:
|
||||
- Linha 0: Assinar PDF, Assinar XML, Assinatura Atachada
|
||||
- Linha 1: Co-Assinar Documento, Carimbo do Tempo, Gerenciar Selos
|
||||
- Linha 2: Validar Assinatura, Validar Carimbo, Sair do Agente
|
||||
- `SealDesignerDialog`: criador e instalador de selos digitais personalizados com pré-visualização ao vivo (Live Preview), seletores de cores, estilos de emblema, obrigatoriedade de nome completo, controle de mascaramento de CPF e estampa de data/hora.
|
||||
- `SignatureValidationDialog`: diálogo de validação criptográfica real com alternância entre Assinatura Incorporada e Assinatura Destacada, extração de documento embutido e relatório de signatários.
|
||||
- `PdfSignDialog`: modal de assinatura PAdES com posicionamento por clique na folha, atalho direto para criar/instalar selos e opções dinâmicas de CPF/data-hora.
|
||||
- `SettingsView`: configurações gerais persistentes, política de PIN e gerenciamento de selos instalados.
|
||||
### 1.2 Módulo `cybercore-ui` (Apresentação JavaFX)
|
||||
Responsável por toda a interação com o usuário:
|
||||
* **Interface Principal (`MainAppView`):** Painel de navegação moderno com alternador dinâmico de tema (Claro/Escuro), grade 3x3 de operações rápidas (PDF, XML, Arquivo Genérico, Assinatura em Lote, Assinatura Atachada, Co-Assinatura, Carimbo de Tempo, Designer de Selos, Validador) e coluna lateral de utilitários (Logs em tempo real, Configurações e Diagnóstico).
|
||||
* **Diálogos de Consentimento e PIN:** Modais nativos de aprovação visual para requisições do protocolo CCSP/1 (`SignatureConfirmationDialog`, `ApplicationAuthorizeDialog`) e coleta segura de PIN de tokens (`A1PasswordDialog`).
|
||||
* **Designer de Selos Digitais (`SealDesignerDialog`):** Ferramenta com Live Preview para criação de selos visuais com controle de cores, estilo de brasão, exibição de nome completo sem truncamento e privacidade de CPF.
|
||||
* **Bandeja do Sistema (System Tray):** Execução minimizada com menu de contexto rápido para restauração da tela ou encerramento da sessão.
|
||||
|
||||
### 1.3 `cybercore-app`
|
||||
- Main bootstrap (`CyberCoreSignerApplication`).
|
||||
- Tratamento de parâmetros de inicialização (`--dev`, `--headless`).
|
||||
- Execução de diagnósticos preliminares de ambiente e engine criptográfica antes do início das threads de escuta.
|
||||
- Geração de Fat JAR autocontido via `maven-shade-plugin` e preparação para distribuição `jpackage`.
|
||||
### 1.3 Módulo `cybercore-app` (Orquestração e Bootstrap)
|
||||
Ponto de partida da aplicação (`CyberCoreApp`):
|
||||
* Processa argumentos de linha de comando (`--dev`, `--headless`).
|
||||
* Executa rotinas de diagnóstico pré-inicialização do ambiente Java e disponibilidade criptográfica.
|
||||
* Inicia o `CcspServer` em segundo plano e abre a interface gráfica na `JavaFX Application Thread`.
|
||||
* Empacota o executável consolidado via `maven-shade-plugin` e orquestra o build nativo via `jpackage`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Fluxo de Dados e Princípio de Menor Privilégio
|
||||
## 2. Modelo de Threads e Concorrência
|
||||
|
||||
O CyberCore Signer opera sob o **modelo de assinatura descentralizada por digest**:
|
||||
1. A aplicação web calcula o hash criptográfico SHA-256 no próprio navegador utilizando a Web Crypto API nativa.
|
||||
2. Apenas o hash Base64 de 32 bytes trafega localmente para o CyberCore Signer.
|
||||
3. O documento completo nunca sai do navegador e a chave privada nunca sai do computador ou do hardware do usuário.
|
||||
Para manter a interface gráfica sempre fluida e ágil, o CyberCore Signer utiliza um particionamento rígido de threads:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph UI Layer
|
||||
JFX[JavaFX Application Thread]
|
||||
end
|
||||
|
||||
subgraph Local Protocol Layer
|
||||
HTTPPool[CcspServer Worker Pool (FixedThreadPool 8)]
|
||||
end
|
||||
|
||||
subgraph Background Services
|
||||
Watcher[SmartCardWatcher Thread (PC/SC Loop)]
|
||||
AsyncTasks[JavaFX Task / CompletableFuture Workers]
|
||||
end
|
||||
|
||||
subgraph Hardware Critical Section
|
||||
Lock[Trava Serializada FIFO: signLock]
|
||||
Hardware[Token Físico A3 / SmartCard Driver]
|
||||
end
|
||||
|
||||
HTTPPool -->|Solicita Aprovação Visual| JFX
|
||||
JFX -->|Consentimento Concedido| HTTPPool
|
||||
HTTPPool --> Lock
|
||||
AsyncTasks --> Lock
|
||||
Lock --> Hardware
|
||||
```
|
||||
|
||||
1. **JavaFX Application Thread:** Dedicada exclusivamente à renderização da interface e tratamento de eventos visuais. Nenhuma operação criptográfica, leitura de disco ou chamada de rede é executada nesta thread.
|
||||
2. **CcspServer Worker Pool:** Pool de 8 threads daemon dedicadas ao atendimento de requisições HTTP da API REST CCSP/1.
|
||||
3. **SmartCardWatcher Thread:** Thread daemon isolada que executa `cardTerminal.waitForCardPresent()` e `waitForCardAbsent()` para monitorar hardware PC/SC sem onerar a CPU.
|
||||
4. **Trava Serializada FIFO (`signLock`):** Implementada via `ReentrantLock(true)`. Garante que operações de assinatura em cartões inteligentes físicos sejam enfileiradas ordenadamente, prevenindo falhas de hardware e estados corrompidos em drivers de fabricantes mono-thread.
|
||||
|
||||
---
|
||||
|
||||
## 3. Fluxo de Dados e Assinatura Descentralizada por Digest
|
||||
|
||||
A arquitetura do CyberCore Signer prioriza a privacidade e o modelo de **assinatura por digest**:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
@@ -66,14 +100,25 @@ sequenceDiagram
|
||||
participant UI as CyberCore JavaFX
|
||||
participant Crypto as SigningService & Providers
|
||||
|
||||
Web->>CCSP: POST /ccsp/v1/sign (digest, appId, certHint, nonce)
|
||||
CCSP->>CCSP: Valida autorização, nonce anti-replay e digest
|
||||
Web->>CCSP: POST /ccsp/v1/sign (digest, appId, certHint, nonce, expires_at)
|
||||
CCSP->>CCSP: Valida autorização, nonce anti-replay e integridade do digest
|
||||
CCSP->>UI: Solicita confirmação visual (requestSignatureConfirmation)
|
||||
UI->>Usuario: Exibe Diálogo (Hash, Certificado, Aplicação)
|
||||
Usuario->>UI: Aprova assinatura (e insere PIN se A3)
|
||||
UI->>Usuario: Exibe Diálogo Nativo (Nome do Documento, Hash SHA-256, Certificado)
|
||||
Usuario->>UI: Clica em "Autorizar Assinatura" (e digita PIN se requerido)
|
||||
UI-->>CCSP: Confirmação concedida
|
||||
CCSP->>Crypto: sign(SigningContext) [Trava FIFO]
|
||||
CCSP->>Crypto: sign(SigningContext) sob signLock.lock()
|
||||
Crypto->>Crypto: JCA/JCE Signature.update(digest) + sign()
|
||||
Crypto-->>CCSP: SigningResult (signatureBytes, certChain)
|
||||
CCSP-->>Web: JSON { status: "signed", signature: "...", certificate: "..." }
|
||||
CCSP-->>Web: 200 OK JSON { status: "signed", signature: "Base64", certificate: "Base64" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Persistência de Dados e Configurações
|
||||
|
||||
Todos os dados de configuração e personalizações do usuário são armazenados no diretório do usuário no sistema operacional:
|
||||
|
||||
* **Diretório Base:** `~/.cybercore/` (ou `%USERPROFILE%\.cybercore\` no Windows).
|
||||
* **`config.json`:** Configurações globais do agente (política de cache de PIN, tema padrão, selo padrão ativo).
|
||||
* **`authorized-apps.json`:** Registro de aplicações web autorizadas pelo usuário, contendo `application_id`, nome amigável e data da aprovação.
|
||||
* **`seals/*.json`:** Selos visuais SVG personalizados criados ou importados pelo usuário no designer de selos.
|
||||
|
||||
Reference in New Issue
Block a user