cybercore-systems/cybercore-signer
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: update documentation files and project README structure

Browse Source
This commit is contained in:
Claudecio Martins
2026-10-11 18:04:46 -03:00
parent 176acf6f40
commit d8d2e6ee46
12 changed files with 1040 additions and 425 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+111 -74
View File
@@ -1,100 +1,137 @@
# CyberCore Signer
> **Agente Desktop de Assinatura Digital e Autenticação Criptográfica (A1 / A3 / PKCS#11) para Windows e Linux.**
> **Agente Desktop Nativo de Assinatura Digital e Autenticação Criptográfica (A1 / A3 / PKCS#11) para Windows e Linux.**
O **CyberCore Signer** é uma solução desktop em Java 21 LTS com JavaFX que permite que aplicações web autorizadas solicitem assinaturas digitais, autenticação de sessão e carimbos do tempo utilizando certificados digitais ICP-Brasil (A1 em arquivo e A3 em tokens/smartcards físicos) instalados ou conectados na estação de trabalho do usuário.
[![Java 21+](https://img.shields.io/badge/Java-21%2B%20LTS-orange.svg)](https://openjdk.org/)
[![JavaFX 25](https://img.shields.io/badge/JavaFX-25-blue.svg)](https://openjfx.io/)
[![Protocol CCSP/1](https://img.shields.io/badge/Protocol-CCSP%2F1-green.svg)](docs/CCSP.md)
[![Standard ICP-Brasil](https://img.shields.io/badge/Standard-ICP--Brasil-emerald.svg)](https://www.gov.br/iti/pt-br)
[![License](https://img.shields.io/badge/License-Proprietary-darkred.svg)](#licença)
A comunicação local entre a página web e o agente utiliza o protocolo **CCSP (CyberCore Signing Protocol)** via HTTP/WebSocket localhost autenticado e seguro.
O **CyberCore Signer** é uma solução desktop desenvolvida em Java 21+ LTS (homologada em Java 25 LTS) com interface gráfica moderna JavaFX e segurança criptográfica estrita JCA/JCE. Permite que aplicações web autorizadas solicitem assinaturas digitais, autenticação de sessão e validação de documentos utilizando certificados digitais padrão ICP-Brasil (A1 em arquivo e A3 em tokens/smartcards físicos) conectados ou instalados na máquina do usuário.
A comunicação local entre a página web e o agente utiliza o protocolo **CCSP (CyberCore Signing Protocol)** via HTTP localhost (`127.0.0.1:21325`), garantindo isolamento total de rede, consentimento visual explícito e preservação integral das chaves privadas na máquina local.
---
## ⚡ Quick Start
### 🌐 Para Aplicações Web (via SDK JavaScript)
Instale e utilize o SDK oficial `@cybercore/signer-sdk` para conectar sua aplicação web ao agente local em poucos passos:
```javascript
import { CyberCoreSigner } from '@cybercore/signer-sdk';
// 1. Inicializar o cliente do assinador
const signer = new CyberCoreSigner({
applicationName: 'Portal Meu Negócio'
});
// 2. Obter certificados disponíveis na máquina do usuário
const certificates = await signer.getCertificates();
const cert = certificates[0]; // Seleciona o primeiro certificado disponível
// 3. Assinar o hash SHA-256 de um documento (a chave nunca sai da máquina!)
const result = await signer.sign({
certificateId: cert.id,
digest: '47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=',
documentName: 'contrato_prestacao_servicos.pdf'
});
console.log('Assinatura gerada:', result.signature);
console.log('Certificado titular:', result.subject_name);
```
> Para o manual completo com exemplos de login digital, assinatura de PDF e XML, consulte o [Guia do SDK](docs/sdk.md).
---
### ☕ Para Desenvolvedores Desktop
#### Requisitos
* **Java Development Kit (JDK):** Versão 21+ LTS (OpenJDK, Temurin ou Corretto).
* **Maven:** 3.9+ (ou utilizar o `./mvnw` embutido).
* **Sistema Operacional:** Windows 10/11 ou Linux x86_64.
#### Compilação e Execução
```bash
# Compilar e gerar o JAR consolidado (Fat JAR sombreado):
./mvnw clean package -DskipTests
# Executar o agente no Linux / macOS:
./run.sh
# Executar o agente no Windows:
run.bat
# Executar com logs detalhados de diagnóstico:
java -jar modules/cybercore-app/target/cybercore-signer.jar --dev
```
---
## 🏛 Arquitetura do Projeto
O projeto é estruturado em módulos Maven:
O projeto é estruturado em módulos Maven desacoplados, garantindo isolamento entre regras criptográficas de baixo nível e a camada de interface gráfica:
* **[modules/cybercore-core](modules/cybercore-core)**: Núcleo de regras criptográficas (JCA/JCE, SunPKCS11, X.509, PAdES, XMLDSig, carimbo de tempo TSA, LTV e validação de cadeias). Não possui dependência de interface gráfica.
* **[modules/cybercore-ui](modules/cybercore-ui)**: Interface gráfica com o usuário construída em JavaFX (Dashboard, Gerenciador de Certificados, Diagnóstico Criptográfico, Diálogo de Confirmação de Assinatura, PIN dialog e System Tray).
* **[modules/cybercore-app](modules/cybercore-app)**: Ponto de entrada da aplicação (`CyberCoreApp`), orquestrador dos serviços de ciclo de vida e servidor CCSP local.
* **[sdk/](sdk)**: SDK JavaScript oficial (`@cybercore/signer-sdk`) para integração de aplicações web com o agente desktop.
* **[docs/](docs)**: Documentação técnica detalhada de arquitetura, protocolo, segurança e casos de uso.
* **[`modules/cybercore-core`](modules/cybercore-core):** Núcleo de regras criptográficas (JCA/JCE, SunPKCS11, X.509, PAdES com Apache PDFBox e Bouncy Castle, XAdES-BES/XMLDSig, carimbo de tempo TSA, LTV, fila FIFO de concorrência e validação de cadeias). **Agnóstico de UI**, sem nenhuma dependência de JavaFX.
* **[`modules/cybercore-ui`](modules/cybercore-ui):** Interface gráfica com o usuário construída em JavaFX 25, apresentando design moderno com alternância dinâmica Claro/Escuro (Dual-Theme), Dashboard, Gerenciador de Certificados, Designer de Selos Visuais SVG com Live Preview, Diálogos de Confirmação de Assinatura, PIN dialog e System Tray.
* **[`modules/cybercore-app`](modules/cybercore-app):** Ponto de entrada da aplicação (`CyberCoreApp`), orquestrador dos serviços de ciclo de vida, diagnóstico pré-inicialização e servidor CCSP local.
* **[`sdk/`](sdk):** SDK JavaScript oficial (`@cybercore/signer-sdk`) para integração simplificada de aplicações web modernas com o agente desktop.
* **[`docs/`](docs):** Documentação técnica abrangente contendo especificações do protocolo, arquitetura, segurança e manuais de integração.
---
## 🚀 Requisitos
## 📊 Matriz de Recursos e Conformidade
* **Java Development Kit (JDK):** Versão 21+ LTS (OpenJDK, Temurin, Corretto, etc.).
* **Maven:** 3.9+ (ou utilizar o wrapper `./mvnw` incluído no projeto).
* **Sistema Operacional Alvo:** Windows 10/11 ou Linux (x86_64).
| Recurso | Padrão / Tecnologia | Descrição |
|---|---|---|
| **Certificados A1** | PKCS#12 / `.pfx` / `.p12` | Leitura em memória volátil com destruição segura de senhas |
| **Certificados A3** | Windows-MY (CryptoAPI/CNG) & PKCS#11 | Acesso nativo a tokens USB e smartcards (SafeSign, SafeNet, GD Burti, OpenSC) |
| **Assinatura PDF** | PAdES (ISO 32000-1 / ETSI TS 102 778) | Envelope CMS/PKCS#7, suporte a salvamento incremental e carimbo TSA |
| **Selos Visuais PDF** | Renderização Java2D de Alta Resolução (300 DPI) | Brasões vetoriais, upload de logos, controle de sigilo de CPF (LGPD) e pré-visualização interativa |
| **Assinatura XML** | XAdES-BES (ETSI TS 101 903 / DOC-ICP-15.03) | Suporte completo a NF-e, CT-e, MDF-e, eSocial e documentos envelopados |
| **Assinatura Genérica** | CMS / CAdES / P7S / P7M | Modalidades atachada (enveloped) e destacada (detached) |
| **Login Digital** | Challenge-Response ICP-Brasil | Autenticação web segura sem senhas tradicionais |
| **Validação** | Verificação Criptográfica Local | Auditoria de integridade de hashes, validade de certificados e signatários |
| **Interface Desktop** | JavaFX 25 com Dual-Theme | Modo Claro e Modo Escuro com comutação instantânea e atalhos na bandeja |
| **Protocolo Local** | CCSP/1 REST (`127.0.0.1:21325`) | Bind estrito em loopback, proteção anti-replay via nonce e autorização de origens |
---
## 🛠 Compilação e Empacotamento
## 🔒 Princípios Fundamentais de Segurança
### 1. Compilação do JAR Executável
Para compilar e gerar o JAR consolidado (com todas as dependências sombreadas e assets):
```bash
./build-jar.sh
```
Ou diretamente via Maven:
```bash
./mvnw clean package -DskipTests
```
O artefato consolidado será gerado em:
`modules/cybercore-app/target/cybercore-signer.jar`
### 2. Execução Local
Para iniciar o agente em ambiente de desenvolvimento:
```bash
# No Linux / macOS:
./run.sh
# No Windows:
run.bat
```
### 3. Empacotamento com Runtime Nativo (`jpackage`)
Para criar a distribuição com Java Runtime embutido (sem exigir JDK pré-instalado pelo usuário final):
```bash
./scripts/package-jpackage.sh
```
1. **A Chave Privada Permanece na Estação de Trabalho:** A chave privada e os segredos (PIN do token A3 ou senha do arquivo A1) nunca saem da máquina do usuário nem trafegam pela rede ou saem em logs.
2. **Assinatura por Digest Descentralizada:** Por padrão, a aplicação web calcula o hash SHA-256 do documento localmente e o CyberCore assina apenas o digest de 32 bytes, eliminando o tráfego desnecessário de arquivos inteiros.
3. **Consentimento Visual Explícito:** Nenhuma operação de assinatura ocorre silenciosamente. Toda requisição exige autorização física do usuário em diálogo nativo do sistema operacional.
4. **Isolamento de Origem e Anti-Replay:** Cada requisição web deve apresentar identificador de aplicação aprovado, nonce único com validação temporal (`expires_at`) e cabeçalho de origem verificado.
5. **Fila FIFO de Operações:** O acesso a tokens físicos A3 é protegido por trava de concorrência (`signLock`) serializada, prevenindo travamento ou corrupção de sessão nos chips criptográficos.
---
## 🔒 Princípios de Segurança e Privacidade
## 📚 Documentação Técnica Detalhada
1. **Chave Privada Preservada:** A chave privada e os segredos (PIN de token A3 e senha de certificado A1) nunca saem da máquina do usuário nem trafegam pela rede.
2. **Assinatura por Digest:** Por padrão, a aplicação web calcula o hash/digest (ex: SHA-256) do documento e o CyberCore assina localmente apenas o digest, minimizando o tráfego de dados sensíveis.
3. **Confirmação Explícita:** Toda operação de assinatura exige consentimento e autorização visual do usuário antes da aplicação da chave.
4. **Isolamento de Origem e CCSP:** O agente atende apenas origens web autorizadas, protegendo contra abusos via CSRF ou requisições locais não autenticadas.
Para detalhes completos sobre arquitetura, protocolos e manuais técnicos, acesse o [Portal de Documentação](docs/README.md) ou consulte diretamente os links abaixo:
* 🌐 **[Protocolo CCSP/1](docs/CCSP.md):** Contrato REST, endpoints, códigos de status e anti-replay.
* 📦 **[SDK Web JavaScript](docs/sdk.md):** Guia de integração e métodos da biblioteca oficial.
* 🏛 **[Arquitetura do Sistema](docs/architecture.md):** Módulos, threading e fluxo sequencial.
* 💳 **[Certificados A1, A3 e PKCS#11](docs/a1-a3-certificates.md):** Suporte a hardware, drivers e OIDs ICP-Brasil.
* 📄 **[Assinaturas PDF e Selos SVG](docs/pades.md):** PAdES, renderização Java2D e selos visuais.
* 📑 **[Assinaturas XML (XAdES-BES)](docs/xml-xmldsig.md):** Padrão DOC-ICP-15.03 e notas fiscais.
* 🔑 **[Autenticação e Login Digital](docs/authentication-login.md):** Fluxo Challenge-Response via ICP-Brasil.
* ⚠️ **[Catálogo Estruturado de Erros](docs/errors.md):** Tabela de erros `CcspErrorCode` e códigos HTTP.
* 🛡️ **[Modelo de Segurança e Privacidade](docs/security.md):** Diretrizes de isolamento, memória e LGPD.
* 🩺 **[Diagnóstico e Troubleshooting](docs/diagnostics.md):** Auto-teste e guia de resolução de problemas.
* 💿 **[Instalação e Empacotamento Nativo](docs/installation.md):** Distribuição via `jpackage` sem JRE pré-instalado.
* ⚖️ **[Limitações Técnicas](docs/limitations.md):** Declaração de dependências conforme a Regra 23.
* 🛠️ **[Modo de Desenvolvimento](docs/development-mode.md):** Parâmetro `--dev` e certificados de teste.
* 🎨 **[Layout Dual-Theme e Assinatura em Lote](docs/serpro-layout-and-batch.md):** Design da UI e operações em lote.
---
## 📚 Documentação Técnica
## 📄 Licença e Propriedade
Consulte a pasta [docs/](docs) para especificações completas:
* [Protocolo CCSP (CyberCore Signing Protocol)](docs/CCSP.md)
* [Arquitetura e Fluxo do Sistema](docs/architecture.md)
* [Certificados A1 e A3 (PKCS#11 / MSCAPI)](docs/a1-a3-certificates.md)
* [Assinatura de Documentos PDF (PAdES / LTV / TSA)](docs/pades.md)
* [Assinatura de Documentos XML (XMLDSig)](docs/xml-xmldsig.md)
* [Autenticação e Sessão Criptográfica](docs/authentication-login.md)
* [Diagnóstico e Resolução de Problemas](docs/diagnostics.md)
* [Segurança e Tratamento de Erros](docs/security.md)
* [SDK Web JavaScript](docs/sdk.md)
* [Guia de Instalação](docs/installation.md)
---
## 📄 Licença
Propriedade de **CyberCore Systems**. Todos os direitos reservados.
Copyright © 2026 **CyberCore Systems**. Todos os direitos reservados.
Este software é proprietário e confidencial. O uso, distribuição ou modificação não autorizados são estritamente proibidos.
docs/CCSP.md
+174 -108
View File
@@ -1,28 +1,52 @@
# CyberCore Signing Protocol (CCSP/1)
O **CyberCore Signing Protocol (CCSP)** é o protocolo padrão para comunicação local entre aplicações web rodando no navegador e o agente desktop **CyberCore Signer**.
> **Especificação Técnica do Protocolo de Comunicação Local e API REST (Versão 1)**
A versão inicial descrita neste documento é a **CCSP/1**.
O **CyberCore Signing Protocol (CCSP)** é o protocolo padrão para comunicação local entre aplicações web rodando no navegador do usuário e o agente desktop **CyberCore Signer**.
A versão atual especificada neste documento é a **CCSP/1**.
---
## 1. Princípios de Segurança
## 1. Princípios de Segurança e Isolamento
1. **Isolamento de Rede:** O servidor local escuta exclusivamente no endereço de loopback `127.0.0.1` (porta padrão `21325`), impedindo qualquer acesso a partir da rede local (LAN) ou externa (WAN).
2. **Controle Estrito de Origem (CORS):** O agente valida cabeçalhos `Origin` e responde apenas a pré-voos `OPTIONS` com origens autorizadas.
3. **Registro e Autorização de Aplicações:** Nenhuma aplicação desconhecida tem acesso a certificados ou assinaturas. Ao tentar conectar pela primeira vez, uma caixa de diálogo nativa solicita aprovação explícita do usuário.
4. **Confirmação Visual da Assinatura:** Toda operação de assinatura exige confirmação manual na interface gráfica, exibindo a aplicação solicitante, o hash do documento e o certificado selecionado.
5. **Proteção Contra Ataques de Replay:** Toda requisição deve conter um `nonce` UUID único com validação temporal (`expires_at` ou `timestamp`). Requisições com nonces repetidos são sumariamente rejeitadas (`REPLAY_DETECTED`).
6. **Privacidade Criptográfica:** Apenas o **digest (hash)** do documento é enviado ao agente. O documento completo nunca sai da aplicação web e a chave privada nunca sai do dispositivo/computador do usuário.
O protocolo CCSP/1 adota o princípio de menor privilégio e segurança em profundidade:
1. **Loopback Estrito (`127.0.0.1`):** O servidor HTTP local vincula seu socket exclusivamente ao endereço IP `127.0.0.1` na porta padrão `21325`. O agente rejeita escuta em `0.0.0.0`, prevenindo qualquer acesso proveniente da rede local (LAN) ou externa (WAN).
2. **Validação de Cabeçalhos e DNS Rebinding:** O agente valida o cabeçalho `Host` para garantir que as requisições se originem estritamente de `127.0.0.1:21325` ou `localhost:21325`.
3. **Controle de Origem (CORS):** Todas as respostas incluem cabeçalhos CORS restritivos. Métodos HTTP `OPTIONS` prévios (preflight) são tratados para liberar apenas métodos e headers homologados (`Content-Type`, `Origin`, `X-CyberCore-AppId`).
4. **Handshake de Autorização de Aplicações:** Nenhuma página web desconhecida pode listar certificados ou solicitar assinaturas. Uma aplicação deve se identificar (`POST /ccsp/v1/authorize`) e obter aprovação explícita do usuário via diálogo nativo do sistema operacional.
5. **Proteção Anti-Replay com Nonce e TTL:** Todas as chamadas de assinatura exigem um identificador pseudoaleatório `nonce` único e um timestamp de expiração (`expires_at`). Requisições com nonces repetidos são sumariamente rejeitadas com erro estruturado `REPLAY_DETECTED`.
6. **Privacidade Criptográfica por Digest:** Por padrão, a aplicação web calcula o hash SHA-256 no próprio navegador utilizando a Web Crypto API nativa e envia apenas o digest de 32 bytes (em Base64). O documento confidencial nunca trafega para o agente e a chave privada nunca sai do computador ou do chip criptográfico do usuário.
7. **Trava FIFO Serializada (`signLock`):** O processamento de assinaturas físicas em smartcards/tokens USB A3 é serializado em fila FIFO para evitar colisões no hardware mono-thread do middleware do fabricante.
---
## 2. Endpoints do Protocolo (CCSP/1)
## 2. Visão Geral dos Endpoints (CCSP/1)
### 2.1 `GET /ccsp/v1/status`
Verifica se o agente está instalado, em execução e pronto para operações.
| Método | Endpoint | Finalidade | Autenticação Requerida |
|---|---|---|---|
| `GET` | `/ccsp/v1/status` | Verifica integridade e status de prontidão do agente local | Nenhuma |
| `POST` | `/ccsp/v1/authorize` | Handshake de autorização inicial de uma aplicação web | Consentimento visual do usuário |
| `GET` | `/ccsp/v1/certificates` | Lista certificados digitais ICP-Brasil válidos e operacionais | Aplicação Autorizada |
| `POST` | `/ccsp/v1/sign` | Executa assinatura digital do digest informado | Aplicação Autorizada + Diálogo Nativo |
| `POST` | `/ccsp/v1/authenticate` | Realiza login seguro via desafio criptográfico (*Challenge-Response*) | Aplicação Autorizada + Diálogo Nativo |
#### Resposta de Sucesso (200 OK)
---
## 3. Especificação Detalhada dos Endpoints
### 3.1 `GET /ccsp/v1/status`
Verifica se o agente desktop está instalado, em execução e pronto para operações criptográficas.
#### Requisição
```http
GET /ccsp/v1/status HTTP/1.1
Host: 127.0.0.1:21325
Origin: https://meusistema.empresa.com.br
```
#### Resposta de Sucesso (`200 OK`)
```json
{
"version": "1",
@@ -30,20 +54,58 @@ Verifica se o agente está instalado, em execução e pronto para operações.
"agent": "CyberCore Signer",
"agent_version": "0.1.0",
"os": "Windows 11",
"timestamp": "2026-10-08T19:40:00Z"
"timestamp": "2026-10-11T20:45:00Z"
}
```
---
### 2.2 `GET /ccsp/v1/certificates`
Retorna a lista de certificados digitais atualmente disponíveis e aptos para assinatura.
### 3.2 `POST /ccsp/v1/authorize`
Inicia o handshake para autorizar uma nova aplicação web. Quando a aplicação ainda não foi homologada pelo usuário, o CyberCore Signer suspende a requisição e exibe um modal nativo na tela do desktop para confirmação.
#### Headers / Parâmetros
- `X-CyberCore-AppId`: UUID da aplicação autorizada (ou query param `?application_id=uuid`).
#### Cabeçalhos
- `Content-Type: application/json`
- `Origin: https://meusistema.empresa.com.br`
#### Payload da Requisição
```json
{
"version": "1",
"application_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Portal Jurídico e Tributário"
}
```
#### Resposta de Sucesso (`200 OK`)
```json
{
"version": "1",
"status": "authorized",
"application_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "Aplicação autorizada pelo usuário com sucesso."
}
```
#### Resposta de Recusa do Usuário (`403 Forbidden`)
```json
{
"version": "1",
"status": "error",
"error_code": "APPLICATION_NOT_AUTHORIZED",
"message": "O usuário recusou a autorização para esta aplicação."
}
```
---
### 3.3 `GET /ccsp/v1/certificates`
Retorna a lista de certificados digitais atualmente disponíveis e aptos para assinatura no sistema (A1 importados e A3 conectados via Windows Store ou PKCS#11).
#### Cabeçalhos / Parâmetros
- `Origin`: Origem web autorizada.
- `X-CyberCore-AppId` (Header) ou `?application_id=uuid` (Query Param).
#### Resposta de Sucesso (200 OK)
#### Resposta de Sucesso (`200 OK`)
```json
{
"version": "1",
@@ -51,16 +113,18 @@ Retorna a lista de certificados digitais atualmente disponíveis e aptos para as
"certificates": [
{
"id": "win-4340656a",
"alias": "CLAUDIO SILVA:12345678900",
"common_name": "CLAUDIO SILVA:12345678900",
"subject_dn": "CN=CLAUDIO SILVA:12345678900, OU=Autenticado por AR, O=ICP-Brasil, C=BR",
"issuer_dn": "CN=AC SERPRO v5, O=ICP-Brasil, C=BR",
"alias": "MARIA DA SILVA:12345678900",
"common_name": "MARIA DA SILVA:12345678900",
"subject_dn": "CN=MARIA DA SILVA:12345678900, OU=Autenticado por AR, O=ICP-Brasil, C=BR",
"issuer_dn": "CN=AC SERPRO v5, OU=Servico Federal de Processamento de Dados, O=ICP-Brasil, C=BR",
"type": "A3",
"provider_id": "provider-win-store",
"device_name": "Token / Smart Card (Windows CAPI/CNG)",
"valid_from": "2024-05-10T12:00:00Z",
"valid_to": "2027-05-10T12:00:00Z",
"device_name": "Token USB / Smart Card (Windows CAPI/CNG)",
"valid_from": "2025-01-10T10:00:00Z",
"valid_to": "2028-01-10T10:00:00Z",
"serial_number": "72910482910482019482",
"cpf": "12345678900",
"cnpj": null,
"can_sign": true,
"status": "AVAILABLE"
}
@@ -70,33 +134,10 @@ Retorna a lista de certificados digitais atualmente disponíveis e aptos para as
---
### 2.3 `POST /ccsp/v1/authorize`
Handshake inicial de uma nova aplicação web para solicitar autorização ao usuário.
### 3.4 `POST /ccsp/v1/sign`
Solicita a assinatura digital local do digest informado com o certificado escolhido.
#### Requisição
```json
{
"version": "1",
"application_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Portal Assinaturas Jurídicas"
}
```
#### Resposta (200 OK)
```json
{
"version": "1",
"status": "authorized",
"application_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
---
### 2.4 `POST /ccsp/v1/sign`
Executa a assinatura digital do digest informado (PDF, XML, documentos ou arquivos gerais).
#### Requisição
#### Payload da Requisição
```json
{
"version": "1",
@@ -106,103 +147,128 @@ Executa a assinatura digital do digest informado (PDF, XML, documentos ou arquiv
"algorithm": "SHA256withRSA",
"digest": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
"certificate_hint": "win-4340656a",
"document_name": "contrato_locacao.pdf",
"document_name": "contrato_prestacao_servicos.pdf",
"document_type": "PDF",
"nonce": "c4ca4238a0b923820dcc509a6f75849b",
"expires_at": "2026-10-08T19:45:00Z"
"expires_at": "2026-10-11T20:50:00Z"
}
```
#### Resposta de Sucesso (200 OK)
#### Resposta de Sucesso (`200 OK`)
```json
{
"version": "1",
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"status": "signed",
"signature": "MEUCIQDq...base64...",
"certificate": "MIIFazC...base64...",
"signature": "MEUCIQDq95kZc...Base64...",
"certificate": "MIIFazCCBF...Base64...",
"certificate_chain": [
"MIIFazC...base64...",
"MIIEazC...base64..."
"MIIFazCCBF...Base64...",
"MIIEazCCA1...Base64..."
],
"algorithm": "SHA256withRSA",
"subject_name": "CLAUDIO SILVA",
"subject_name": "MARIA DA SILVA",
"subject_cpf_cnpj": "12345678900",
"document_name": "contrato_locacao.pdf",
"document_name": "contrato_prestacao_servicos.pdf",
"document_type": "PDF"
}
```
---
### 2.5 `POST /ccsp/v1/authenticate`
Executa o login / autenticação digital segura de um usuário em sistemas web via desafio criptográfico (Challenge-Response ICP-Brasil).
### 3.5 `POST /ccsp/v1/authenticate`
Executa o login criptográfico de um usuário em sistemas web através do mecanismo de desafio e resposta (*Challenge-Response*).
#### Requisição
#### Payload da Requisição
```json
{
"version": "1",
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"request_id": "8f3b201a-8c9d-4e5f-b012-3456789abcde",
"application_id": "550e8400-e29b-41d4-a716-446655440000",
"operation": "authenticate",
"challenge": "server-session-challenge-nonce-2026",
"challenge": "session-nonce-random-server-token-998877",
"certificate_hint": "win-4340656a",
"purpose": "AUTHENTICATION",
"nonce": "c4ca4238a0b923820dcc509a6f75849b",
"expires_at": "2026-10-08T19:45:00Z"
"nonce": "d3b07384d113edec49eaa6238ad5ff00",
"expires_at": "2026-10-11T20:50:00Z"
}
```
#### Resposta de Sucesso (200 OK)
#### Resposta de Sucesso (`200 OK`)
```json
{
"version": "1",
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"request_id": "8f3b201a-8c9d-4e5f-b012-3456789abcde",
"status": "authenticated",
"signature": "MEUCIQDq...base64...",
"certificate": "MIIFazC...base64...",
"signature": "MEQCIF61pP...Base64...",
"certificate": "MIIFazCCBF...Base64...",
"certificate_chain": [
"MIIFazC...base64..."
"MIIFazCCBF...Base64...",
"MIIEazCCA1...Base64..."
],
"algorithm": "SHA256withRSA",
"subject_name": "CLAUDIO SILVA",
"subject_cpf_cnpj": "12345678900",
"document_type": "AUTH_CHALLENGE"
}
```
#### Resposta de Erro (400/403/404)
```json
{
"version": "1",
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"status": "error",
"error_code": "USER_CANCELLED",
"message": "Operação de assinatura cancelada pelo usuário."
"subject_name": "MARIA DA SILVA",
"subject_cpf_cnpj": "12345678900"
}
```
---
## 3. Tabela de Códigos de Erro Estruturados
## 4. Estrutura Padrão de Erro e Códigos HTTP
| Código | Significado |
|---|---|
| `CERTIFICATE_NOT_FOUND` | Certificado indicado no hint não foi encontrado. |
| `CERTIFICATE_EXPIRED` | O certificado selecionado está fora do período de vigência. |
| `CERTIFICATE_INVALID` | O certificado é inválido ou corrompido. |
| `PRIVATE_KEY_NOT_AVAILABLE` | Chave privada inacessível ou ausente. |
| `TOKEN_NOT_FOUND` | Nenhum dispositivo ou leitor compatível foi localizado. |
| `TOKEN_REMOVED` | Dispositivo de hardware foi removido durante a assinatura. |
| `PIN_REQUIRED` | PIN obrigatório para liberar chave privada em PKCS#11. |
| `PIN_INCORRECT` | PIN digitado está incorreto. |
| `PKCS11_ERROR` | Falha no middleware PKCS#11 do fabricante. |
| `SIGNATURE_FAILED` | Erro durante a geração da assinatura digital. |
| `APPLICATION_NOT_AUTHORIZED` | Aplicação não autorizada ou recusada pelo usuário. |
| `REQUEST_EXPIRED` | A data/hora de validade da requisição expirou. |
| `REPLAY_DETECTED` | O nonce informado já foi processado anteriormente. |
| `INVALID_ORIGIN` | O cabeçalho Origin não corresponde ao cadastro da aplicação. |
| `UNSUPPORTED_ALGORITHM` | Algoritmo não suportado (ex: diferente de SHA256withRSA). |
| `USER_CANCELLED` | O usuário clicou em Cancelar ou fechou a janela de confirmação. |
| `PROVIDER_NOT_AVAILABLE` | O provedor criptográfico necessário está inativo no SO. |
| `COMMUNICATION_ERROR` | Erro interno no agente de comunicação local. |
Quando qualquer operação falha, o servidor local CCSP/1 responde com um objeto JSON padronizado e o código de status HTTP correspondente:
```json
{
"version": "1",
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"status": "error",
"error_code": "PIN_INCORRECT",
"message": "O PIN informado para o token A3 é inválido."
}
```
### Mapeamento de Status HTTP
| Código HTTP | Erro Típico | Descrição |
|---|---|---|
| `400 Bad Request` | `USER_CANCELLED`, `PIN_INCORRECT`, `SIGNATURE_FAILED` | Requisição malformada, cancelamento pelo usuário ou falha de PIN |
| `401 Unauthorized` | `APPLICATION_NOT_AUTHORIZED` | Aplicação não autorizada ou sem cabeçalho `X-CyberCore-AppId` |
| `403 Forbidden` | `INVALID_ORIGIN` | Cabeçalho `Origin` não confere com o domínio cadastrado |
| `404 Not Found` | `CERTIFICATE_NOT_FOUND`, `TOKEN_NOT_FOUND` | Certificado ou dispositivo físico ausente |
| `409 Conflict` | `REPLAY_DETECTED` | Nonce já utilizado anteriormente na janela de validação |
| `422 Unprocessable`| `REQUEST_EXPIRED`, `CERTIFICATE_EXPIRED` | Parâmetros sintaticamente válidos mas expirados temporalmente |
| `500 Server Error` | `PKCS11_ERROR`, `PROVIDER_NOT_AVAILABLE` | Falha interna no middleware do fabricante ou driver criptográfico |
| `503 Service Unavail`| `TOKEN_REMOVED`, `COMMUNICATION_ERROR` | Hardware desconectado ou serviço em recuperação |
---
## 5. Diagrama de Sequência Completo
```mermaid
sequenceDiagram
autonumber
actor User as Usuário
participant Browser as Aplicação Web (Browser)
participant SDK as @cybercore/signer-sdk
participant CCSP as CyberCore CcspServer (127.0.0.1)
participant UI as CyberCore Desktop UI
participant HW as Hardware Token / Windows MY
Browser->>SDK: signer.sign({ digest, certId })
SDK->>CCSP: POST /ccsp/v1/sign (Headers, AppId, Nonce, Digest)
CCSP->>CCSP: Valida Origin, AppId e Nonce (anti-replay)
CCSP->>UI: Solicita confirmação visual (requestSignatureConfirmation)
UI->>User: Exibe Diálogo Nativo (Aplicação, Documento, Certificado)
User->>UI: Clica em "Assinar"
opt Certificado A3 exige PIN
UI->>User: Solicita PIN do Hardware
User->>UI: Digita PIN
end
UI-->>CCSP: Confirmação concedida
CCSP->>HW: signLock.lock() -> JCA/JCE Signature.sign()
HW-->>CCSP: Bytes da assinatura + Cadeia X.509
CCSP->>CCSP: signLock.unlock()
CCSP-->>SDK: 200 OK (signature Base64, cert, subject)
SDK-->>Browser: Retorna resultado para a página web
```
docs/README.md
+66
View File
@@ -0,0 +1,66 @@
# Documentação Técnica — CyberCore Signer
> **Índice Unificado e Guias Técnicos do Agente Desktop e Protocolo CCSP**
Bem-vindo à documentação oficial do **CyberCore Signer**. O agente foi desenvolvido em Java 21+ LTS (Java 25 LTS) com interface JavaFX e segurança criptográfica nativa JCA/JCE, permitindo que aplicações web autorizadas realizem operações de assinatura digital e autenticação com certificados ICP-Brasil (A1 em arquivo e A3 em tokens/smartcards físicos) mantendo as chaves privadas estritamente no dispositivo do usuário.
---
## 🗺️ Trilhas de Navegação por Perfil
Para facilitar a consulta, os documentos estão organizados de acordo com o seu perfil de atuação:
### 🌐 1. Para Desenvolvedores Web e Integradores
Se você desenvolve aplicações web (frontend/backend) que precisam interagir com o agente do usuário:
* **[Protocolo CCSP/1 (CyberCore Signing Protocol)](CCSP.md):** Especificação completa da API REST local (`127.0.0.1:21325`), endpoints, ciclo de handshake, proteção anti-replay e exemplos de requisição/resposta.
* **[SDK Web JavaScript (@cybercore/signer-sdk)](sdk.md):** Manual de instalação e uso da biblioteca oficial cliente para integração em aplicações web (Vite, Next.js, Vue, Angular, Vanilla JS).
* **[Autenticação e Login Digital ICP-Brasil](authentication-login.md):** Fluxo de autenticação segura via desafio criptográfico (*Challenge-Response*) para substituição ou complemento de senhas tradicionais.
* **[Catálogo Estruturado de Erros](errors.md):** Lista completa de códigos de erro (`CcspErrorCode`), status HTTP correspondentes e orientações de tratamento na interface web.
---
### ☕ 2. Para Desenvolvedores Desktop e Contribuidores
Se você atua no desenvolvimento, manutenção ou auditoria do código-fonte do agente desktop:
* **[Arquitetura do Sistema](architecture.md):** Organização modular Maven (`cybercore-core`, `cybercore-ui`, `cybercore-app`), fluxo de dados por digest, modelo de concorrência com fila FIFO (`signLock`) e isolamento de dependências.
* **[Certificados A1, A3 e PKCS#11](a1-a3-certificates.md):** Funcionamento dos provedores `Pkcs12CertificateProvider`, `WindowsCertificateStoreProvider` (SunMSCAPI/CNG) e `Pkcs11CertificateProvider` (SunPKCS11), monitoramento dinâmico PC/SC (`SmartCardWatcher`) e extração de OIDs ICP-Brasil.
* **[Assinaturas PDF (PAdES) e Selos Visuais SVG](pades.md):** Motor de assinatura PDFBox + Bouncy Castle, salvamento incremental, renderização de alta resolução (300 DPI Java2D) e gerenciamento de selos digitais.
* **[Assinaturas XML (XAdES-BES e XMLDSig)](xml-xmldsig.md):** Conformidade com o padrão ETSI TS 101 903 / DOC-ICP-15.03 e suporte a notas fiscais eletrônicas (NF-e, CT-e, MDF-e, eSocial).
* **[Layout Dual-Theme e Assinatura em Lote](serpro-layout-and-batch.md):** Especificação de interface gráfica moderna, alternância dinâmica de tema (Claro/Escuro) e fila de processamento em lote.
* **[Modo de Desenvolvimento](development-mode.md):** Guia de inicialização em modo `--dev`, políticas de não utilização de mocks em produção e geração de certificados A1 de teste locais.
---
### 🛡️ 3. Para DevOps, Infraestrutura e Segurança
Se você precisa implantar, homologar ou validar os aspectos de conformidade e segurança da solução:
* **[Modelo de Segurança e Privacidade](security.md):** Diretrizes de menor privilégio, proteção contra CSRF e DNS Rebinding, descarte seguro de senhas e PIN em memória e conformidade com a LGPD.
* **[Instalação e Empacotamento Nativo](installation.md):** Criação de instaladores autocontidos para Windows (MSI/EXE) via `jpackage`, requisitos do sistema e parâmetros de instalação corporativa silenciosa.
* **[Diagnóstico e Troubleshooting](diagnostics.md):** Subsistema de auto-teste, checklist de integridade de runtime e guia de resolução de problemas comuns de hardware/middleware.
* **[Limitações Técnicas Declaradas](limitations.md):** Declaração formal de requisitos de drivers, limitações de hardware mono-thread e dependências de sistema operacional (em conformidade com a Regra 23 do projeto).
---
## 📋 Sumário Geral de Arquivos
| Documento | Assunto Principal | Público-Alvo |
|---|---|---|
| [`CCSP.md`](CCSP.md) | Especificação técnica do protocolo local CCSP versão 1 | Integradores Web & Core Devs |
| [`architecture.md`](architecture.md) | Estrutura modular, threading e fluxo de operações | Desenvolvedores Desktop |
| [`a1-a3-certificates.md`](a1-a3-certificates.md) | Provedores A1/A3, PKCS#11, PC/SC e OIDs ICP-Brasil | Especialistas em Criptografia |
| [`pades.md`](pades.md) | Assinatura PAdES, envelope CMS e selos vetoriais | Desenvolvedores Desktop & Web |
| [`xml-xmldsig.md`](xml-xmldsig.md) | XAdES-BES, XMLDSig e documentos fiscais | Integradores de NF-e/XAdES |
| [`authentication-login.md`](authentication-login.md) | Login Challenge-Response via ICP-Brasil | Integradores Web |
| [`errors.md`](errors.md) | Tabela estruturada de erros e mapeamentos HTTP | Todos |
| [`security.md`](security.md) | Políticas de isolamento, memória e privacidade | Segurança & Compliance |
| [`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 |
| [`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 |
| [`serpro-layout-and-batch.md`](serpro-layout-and-batch.md) | Design de interface e processamento em lote | UI/UX & Desenvolvedores |
---
> Dúvidas ou inconsistências? Verifique os testes unitários e de arquitetura em `modules/cybercore-core/src/test` ou consulte o arquivo [README.md principal](../README.md).
docs/a1-a3-certificates.md
+77 -23
View File
@@ -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.
docs/architecture.md
+84 -39
View File
@@ -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.
docs/development-mode.md
+64 -23
View File
@@ -1,48 +1,89 @@
# Modo de Desenvolvimento e Diagnóstico Detalhado
# Modo de Desenvolvimento e Homologação
O **CyberCore Signer** opera exclusivamente com **certificados digitais e provedores criptográficos reais** (A1 via arquivos `.pfx`/`.p12`, repositório nativo do Windows `Windows-MY` e tokens/smart cards físicos PKCS#11). Em conformidade com a exigência de segurança de produção, **não existem mocks ou certificados sintéticos no agente**.
> **Diretrizes para Execução Local com Argumento `--dev`, Testes e Criação de Certificados A1 de Homologação**
O **CyberCore Signer** opera exclusivamente com certificados digitais e provedores criptográficos reais (arquivos `.pfx`/`.p12`, Windows-MY e tokens físicos PKCS#11). Em cumprimento às normas de integridade do projeto, **não existem mocks ou certificados artificiais no runtime de produção**.
---
## 1. Ativação do Modo de Desenvolvimento
Para iniciar o agente em modo de desenvolvimento (com logs detalhados e diagnósticos ampliados), utilize o argumento `--dev`:
Para iniciar o agente em ambiente de homologação e desenvolvimento com logs estendidos de auditoria e detalhamento de operações de rede, utilize o argumento de linha de comando `--dev`:
```bash
java -jar cybercore-signer.jar --dev
# Executando via script Linux / macOS:
./run.sh --dev
# Executando no Windows:
run.bat --dev
# Ou diretamente pelo JAR compilado:
java -jar modules/cybercore-app/target/cybercore-signer.jar --dev
```
Ao iniciar, uma mensagem informativa é registrada no log:
Ao ser iniciado com esta flag, o agente imprime no terminal o banner de diagnóstico:
```
=========================================================
MODO DE DESENVOLVIMENTO ATIVADO (--dev)
Logs detalhados ativos. Operação com certificados reais.
CYBERCORE SIGNER — MODO DE DESENVOLVIMENTO ATIVADO (--dev)
Logs detalhados ativos. Operação com certificados reais JCA/JCE.
Servidor local CCSP/1 pronto em: http://127.0.0.1:21325
=========================================================
```
---
## 2. Testando em Ambiente de Desenvolvimento
## 2. Geração de Certificados A1 de Teste com OpenSSL
Para desenvolvedores testarem fluxos completos de assinatura de PDF, XML, arquivos em geral e login digital:
Para desenvolvedores e testadores que precisam simular fluxos completos de assinatura digital (PAdES, XAdES, login digital) sem utilizar um certificado ICP-Brasil real de produção, é possível gerar um certificado digital de teste no formato `.pfx` protegido por senha utilizando o utilitário **OpenSSL**:
1. **Certificados A1 de Teste/Homologação:**
- Adicione um certificado A1 `.pfx` ou `.p12` emitido por uma autoridade de teste ou autoassinado.
- Pela interface desktop, clique no botão **"Importar A1 (.pfx/.p12)"** no Dashboard e informe o arquivo e a senha.
- O certificado ficará disponível imediatamente para todas as operações CCSP/1.
### Passo 1: Gerar a Chave Privada RSA (2048 bits)
```bash
openssl genrsa -out teste_signer.key 2048
```
2. **Repositório Nativo do Windows (Windows-MY):**
- Instale o certificado no repositório de certificados pessoais do Windows (`certmgr.msc`).
- O provedor `WindowsCertificateStoreProvider` detectará o certificado automaticamente.
### Passo 2: Gerar o Certificado X.509 Autoassinado
```bash
openssl req -new -x509 -key teste_signer.key -out teste_signer.crt -days 365 \
-subj "/C=BR/O=ICP-Brasil Teste/OU=Desenvolvimento CyberCore/CN=DESENVOLVEDOR TESTE:12345678900"
```
3. **Tokens USB / Smart Cards (PKCS#11):**
- Conecte o dispositivo físico com middleware homologado (SafeSign, GD Burti, SafeNet, OpenSC, etc.).
- O provedor `Pkcs11CertificateProvider` detectará o token e seus slots.
### Passo 3: Exportar o Certificado e Chave no Contêiner PKCS#12 (`.pfx`)
```bash
openssl pkcs12 -export -out certificado_teste.pfx \
-inkey teste_signer.key -in teste_signer.crt \
-name "DESENVOLVEDOR TESTE:12345678900" \
-passout pass:123456
```
### Passo 4: Importar no CyberCore Signer
1. Abra o CyberCore Signer.
2. Na tela principal, clique em **"Importar A1 (.pfx/.p12)"**.
3. Selecione o arquivo `certificado_teste.pfx` gerado e informe a senha `123456`.
4. O certificado aparecerá instantaneamente como disponível no Dashboard e poderá ser utilizado para todos os testes do SDK e CCSP/1.
---
## 3. Garantia de Operação Real
## 3. Execução da Suíte de Testes Automatizados
1. Toda assinatura é gerada criptograficamente através dos provedores JCA/JCE reais.
2. A resposta do protocolo CCSP/1 contém assinaturas válidas e certificados X.509 autênticos.
3. Não há certificados simulados ou flags artificiais nas respostas do agente.
O repositório do CyberCore Signer conta com suíte abrangente de testes unitários, testes de concorrência e testes de arquitetura (ArchUnit):
```bash
# Executar todos os testes unitários do projeto:
./mvnw test
# Executar testes específicos do protocolo CCSP/1:
./mvnw test -Dtest=CcspServerTest
# Executar testes de concorrência e trava FIFO (signLock):
./mvnw test -Dtest=CcspConcurrencyTest
# Executar testes de conformidade arquitetural (garante desacoplamento de UI no core):
./mvnw test -Dtest=ArchitectureTest
```
---
## 4. Garantia de Operação Real
1. **Assinaturas Autênticas:** Mesmo ao utilizar um certificado autoassinado de teste, os bytes da assinatura são calculados matematicamente pelos algoritmos reais do JCA/JCE (`SHA256withRSA`).
2. **Sem Falsos Positivos:** O comportamento do agente é 100% idêntico entre o ambiente de teste e o ambiente de produção com tokens físicos A3.
docs/diagnostics.md
+89 -20
View File
@@ -1,34 +1,103 @@
# Diagnóstico de Ambiente e Auto-Teste
# Diagnóstico de Ambiente e Resolução de Problemas
O **CyberCore Signer** possui um subsistema nativo de diagnóstico integrado (`DiagnosticService`), permitindo auditoria detalhada de saúde e integridade técnica da máquina do usuário.
> **Guia de Auto-Teste, Checklist de Integridade de Runtime e Troubleshooting de Hardware**
O **CyberCore Signer** conta com um subsistema nativo de diagnóstico e telemetria local (`DiagnosticService`), projetado para validar a integridade da estação de trabalho e identificar rapidamente falhas de drivers, certificados ou subsistemas criptográficos do sistema operacional.
---
## 1. Itens Inspecionados no Diagnóstico
## 1. Itens Inspecionados pelo Diagnóstico Automático
Ao abrir a aba **Diagnóstico** na interface ou invocar `diagnosticService.runDiagnostic()`, o agente avalia:
Ao acessar a aba **Diagnóstico** na interface do agente desktop ou ao inicializar em modo `--dev`, o agente executa uma auditoria completa nos seguintes componentes:
1. **Ambiente Java / Runtime:**
1. **Ambiente Java / Runtime Nativo:**
- Versão do Java (requer Java 21+ LTS, homologado em Java 25 LTS);
- Vendor do JDK (Temurin, Oracle, etc.);
- Arquitetura do processador e sistema operacional.
- Vendor do JDK (Eclipse Temurin, Oracle OpenJDK, Amazon Corretto);
- Arquitetura da CPU (x86_64 / amd64) e sistema operacional (Windows 10/11 ou Linux).
2. **Engine Criptográfica JCA/JCE:**
- Disponibilidade dos provedores de segurança registrados na JVM (`SUN`, `SunRsaSign`, `SunMSCAPI`, etc.);
- Suporte ao algoritmo de hash `SHA-256`;
- Suporte ao algoritmo de assinatura `SHA256withRSA`.
3. **Repositório de Chaves do Sistema Operacional:**
- Detecção do repositório `Windows-MY` (Windows CryptoAPI / CNG).
4. **Middlewares PKCS#11 e SmartCard:**
- Verificação de bibliotecas de smartcard registradas no sistema (`eps2003csp11.dll`, `aetpkss1.dll`, `opensc-pkcs11.dll`, etc.);
- Disponibilidade do subsistema PC/SC `javax.smartcardio`.
- Suporte aos algoritmos de hash criptográfico (`SHA-256`, `SHA-512`);
- Suporte aos algoritmos de assinatura digital (`SHA256withRSA`).
3. **Repositório de Certificados do Sistema Operacional:**
- Detecção do repositório de chaves `Windows-MY` via SunMSCAPI / CryptoAPI / CNG.
4. **Middlewares PKCS#11 e Subsistema PC/SC:**
- Presença das bibliotecas dinâmicas do fabricante (`aetpkss1.dll`, `eps2003csp11.dll`, `acospkcs11.dll`, `opensc-pkcs11.dll`);
- Disponibilidade do subsistema de leitoras de smartcard `javax.smartcardio` (PC/SC Daemon / Smart Card Service do Windows).
5. **Servidor Local CCSP/1:**
- Teste de bind do socket em `127.0.0.1:21325` e integridade do pool de threads.
---
## 2. Auto-Teste de Assinatura Local (Self-Test)
A aba de diagnóstico disponibiliza o botão **"Executar Auto-teste de Assinatura"**:
1. Seleciona o primeiro certificado operacional disponível na máquina.
2. Gera um hash SHA-256 interno de teste: `"Documento_Teste_CyberCore_<timestamp>"`.
3. Abre o diálogo de confirmação visual para validação do usuário.
4. Executa a assinatura real JCA/JCE e afere os bytes gerados.
5. Emite relatório de sucesso com tempo decorrido e tamanho da assinatura.
A tela de diagnóstico oferece a função **"Executar Auto-teste de Assinatura"**:
1. O agente identifica o primeiro certificado digital operacional conectado.
2. Gera um hash SHA-256 interno sintético para teste: `"Documento_Teste_CyberCore_<timestamp>"`.
3. Abre o diálogo nativo de confirmação visual para validação do usuário.
4. Executa a assinatura real através do provedor JCA/JCE correspondente (solicitando PIN se A3).
5. Valida os bytes da assinatura gerada e emite relatório com tempo decorrido em milissegundos e tamanho da assinatura.
---
## 3. Guia de Resolução de Problemas (Troubleshooting)
### 3.1 Token USB ou Smartcard A3 não é detectado
* **Sintoma:** O token está plugado na porta USB mas não aparece no CyberCore nem na lista de certificados.
* **Causa Comum:** O serviço de cartão inteligente do Windows (`ScardSvr`) está desativado ou o middleware do fabricante (SafeSign/SafeNet) não está instalado.
* **Solução:**
1. No Windows, pressione `Win + R`, digite `services.msc` e pressione Enter.
2. Localize o serviço **Cartão Inteligente (Smart Card)** e garanta que seu status esteja **Em Execução** (Tipo de Inicialização: Automático).
3. Verifique se o aplicativo de gerenciamento do token (ex: *SafeSign Token Utility* ou *SafeNet Authentication Client Tools*) reconhece o token.
4. Desconecte o token USB, aguarde 3 segundos e reconecte em outra porta USB.
### 3.2 Erro `NTE_BAD_KEYSET` ou `Chave Privada Não Acessível`
* **Sintoma:** O certificado aparece na lista, mas a assinatura falha com erro `PRIVATE_KEY_NOT_AVAILABLE` ou código Windows `0x80090016`.
* **Causa Comum:** O certificado foi importado no Windows sem a chave privada correspondente, ou o usuário não tem permissão de leitura sobre o contêiner de chaves.
* **Solução:**
1. Abra o gerenciador de certificados do Windows: `certmgr.msc`.
2. Navegue até **Pessoal -> Certificados** e dê um duplo clique sobre o certificado.
3. Verifique se na parte inferior da aba Geral consta a mensagem: *"Você tem uma chave privada correspondente a este certificado"*. Se não constar, reinstale o arquivo A1 com a opção "Marcar esta chave como exportável" ativada.
### 3.3 Porta local `21325` já em uso (`BindException`)
* **Sintoma:** O CyberCore Signer não inicializa e os logs acusam `Address already in use: bind`.
* **Causa Comum:** Outra instância do CyberCore Signer ou aplicativo conflitante já está em execução na porta `21325`.
* **Solução:**
1. No Windows, abra o Gerenciador de Tarefas (`Ctrl + Shift + Esc`) e encerre eventuais processos `cybercore-signer` ou `javaw.exe` órfãos.
2. No terminal (PowerShell), você pode identificar o processo ocupando a porta:
```powershell
Get-NetTCPConnection -LocalPort 21325 | Select-Object OwningProcess
```
3. No Linux:
```bash
sudo lsof -i :21325
```
### 3.4 Aplicação Web acusa "Agente não instalado" ou Falha de Conexão
* **Sintoma:** A chamada `signer.isInstalled()` no navegador retorna `false` ou dá timeout.
* **Causa Comum:** O CyberCore Signer está fechado, o antivírus bloqueou a conexão loopback local, ou a aplicação web tenta conectar com protocolo incorreto.
* **Solução:**
1. Verifique se o ícone do CyberCore Signer está ativo na barra de tarefas (System Tray).
2. Abra uma nova aba no navegador e acesse diretamente: `http://127.0.0.1:21325/ccsp/v1/status`.
3. O navegador deve exibir o JSON com `"status": "ready"`. Se não exibir, abra o executável do CyberCore Signer.
---
## 4. Comandos Úteis de Diagnóstico no Terminal
### No Windows:
```cmd
:: Testar leitura de smartcards e drivers via utilitário nativo do Windows:
certutil -scinfo
:: Listar certificados instalados no repositório Pessoal do usuário:
certutil -user -store My
```
### No Linux:
```bash
:: Verificar leitoras e cartões conectados via subsistema PC/SC:
pcsc_scan
:: Verificar status do serviço pcscd:
systemctl status pcscd
```
docs/errors.md
+74 -22
View File
@@ -1,28 +1,80 @@
# Catálogo Estruturado de Erros
O **CyberCore Signer** adota um sistema unificado e determinístico de códigos de erro (`CcspErrorCode`) compartilhados entre o agente Java desktop, o protocolo CCSP/1 e o SDK Web em JavaScript.
> **Especificação Unificada de Códigos de Erro (`CcspErrorCode`), Status HTTP e Tratamento no SDK**
O **CyberCore Signer** adota uma taxonomia estrita e estável de erros estruturados, garantindo que o agente desktop Java, a API REST do protocolo CCSP/1 e o SDK JavaScript manipulem falhas com previsibilidade e sem expor detalhes internos sensíveis ao usuário final.
---
## 1. Tabela de Erros Estruturados
## 1. Tabela Completa de Códigos de Erro
| Código de Erro | Descrição Detalhada | Ação Recomendada para a Aplicação Web |
|---|---|---|
| `CERTIFICATE_NOT_FOUND` | O certificado indicado pelo `certificate_hint` não foi localizado. | Solicite ao usuário selecionar novamente o certificado via `getCertificates()`. |
| `CERTIFICATE_EXPIRED` | O certificado selecionado expirou. | Oriente o usuário a renovar o certificado digital junto à autoridade certificadora. |
| `CERTIFICATE_INVALID` | O certificado possui estrutura corrompida ou ainda não é válido. | Verificar a data e integridade do arquivo/dispositivo. |
| `PRIVATE_KEY_NOT_AVAILABLE` | O certificado está presente mas a chave privada não está acessível. | Em tokens A3, verifique se o middleware/driver está instalado corretamente. |
| `TOKEN_NOT_FOUND` | Nenhum dispositivo ou leitor compatível foi localizado. | Solicite ao usuário conectar o token USB ou inserir o smartcard no leitor. |
| `TOKEN_REMOVED` | O token USB ou cartão foi removido fisicamente durante a assinatura. | Peça ao usuário reconectar o token e reiniciar a operação de assinatura. |
| `PIN_REQUIRED` | O token exige PIN para liberar a chave privada e nenhum PIN foi fornecido. | Exibir campo de solicitação de PIN na tela. |
| `PIN_INCORRECT` | O PIN digitado está incorreto. | Informar o usuário e alertar sobre o risco de bloqueio de PUK após 3 tentativas. |
| `PKCS11_ERROR` | Falha no driver ou biblioteca PKCS#11 do fabricante. | Verificar a instalação do SafeSign, SafeNet ou OpenSC. |
| `SIGNATURE_FAILED` | Erro durante a geração dos bytes da assinatura digital. | Tentar novamente ou reiniciar o agente desktop. |
| `APPLICATION_NOT_AUTHORIZED` | A aplicação web teve autorização recusada pelo usuário. | Informar o usuário que é necessário aceitar a notificação na tela do agente. |
| `REQUEST_EXPIRED` | O timestamp ou `expires_at` da requisição expirou. | Gerar nova requisição de assinatura com timestamp atualizado. |
| `REPLAY_DETECTED` | O nonce informado já foi processado anteriormente. | Sempre gerar um UUID único para cada chamada de assinatura. |
| `INVALID_ORIGIN` | O cabeçalho `Origin` não confere com o cadastro da aplicação. | Conectar-se com a URL e protocolo autorizados. |
| `UNSUPPORTED_ALGORITHM` | Algoritmo solicitado não é suportado pelo agente ou certificado. | Utilizar algoritmo padrão homologado (`SHA256withRSA`). |
| `USER_CANCELLED` | O usuário clicou em Cancelar ou fechou a janela do CyberCore. | Tratar como cancelamento voluntário sem mensagem de erro alarmante. |
| `PROVIDER_NOT_AVAILABLE` | O provedor criptográfico necessário não está ativo no sistema operacional. | Verificar a integridade do Windows Certificate Store ou Java Runtime. |
| `COMMUNICATION_ERROR` | Erro interno de socket ou timeout de rede local. | Verificar se a porta `21325` não está bloqueada por antivírus local. |
| Código de Erro (`CcspErrorCode`) | Status HTTP | Descrição do Erro | Ação Recomendada para a Aplicação Web |
|---|---|---|---|
| `CERTIFICATE_NOT_FOUND` | `404 Not Found` | O certificado indicado pelo `certificate_hint` não foi localizado na máquina. | Solicitar ao usuário selecionar novamente o certificado via `getCertificates()`. |
| `CERTIFICATE_EXPIRED` | `422 Unprocessable` | O certificado digital selecionado ultrapassou sua data limite de validade. | Orientar o usuário a renovar o certificado digital junto à autoridade certificadora (AC). |
| `CERTIFICATE_INVALID` | `400 Bad Request` | Estrutura ASN.1/X.509 corrompida ou ainda não iniciada (`NotBefore`). | Verificar integridade do arquivo `.pfx` ou relógio do sistema operacional. |
| `PRIVATE_KEY_NOT_AVAILABLE` | `404 Not Found` | O certificado está presente mas a chave privada não está acessível no repositório. | Em tokens A3, verificar se o middleware/driver do token está instalado corretamente. |
| `TOKEN_NOT_FOUND` | `404 Not Found` | Nenhum dispositivo criptográfico físico ou leitora de cartão foi detectado. | Solicitar ao usuário conectar o token USB ou inserir o smartcard no leitor. |
| `TOKEN_REMOVED` | `503 Service Unavail`| O token USB ou cartão foi desconectado fisicamente durante o processamento. | Orientar o usuário a reconectar o token e reiniciar a operação de assinatura. |
| `PIN_REQUIRED` | `400 Bad Request` | O token exige PIN para liberar a chave privada e nenhum PIN foi informado. | Exibir campo para inserção do PIN do dispositivo. |
| `PIN_INCORRECT` | `400 Bad Request` | O PIN digitado para o token A3 é incorreto. | Alertar o usuário sobre o risco de bloqueio do cartão (PUK) após tentativas consecutivas. |
| `PKCS11_ERROR` | `500 Server Error` | Falha na biblioteca DLL/SO do middleware ou driver do fabricante. | Verificar a instalação do SafeSign, SafeNet, GD Burti ou OpenSC. |
| `SIGNATURE_FAILED` | `400 Bad Request` | Falha criptográfica na geração dos bytes da assinatura digital. | Reiniciar a operação ou verificar integridade do algoritmo especificado. |
| `APPLICATION_NOT_AUTHORIZED` | `401 Unauthorized` | A aplicação web teve autorização recusada pelo usuário ou não foi cadastrada. | Notificar o usuário que é necessário aceitar a solicitação na janela do CyberCore. |
| `REQUEST_EXPIRED` | `422 Unprocessable` | A validade temporal (`expires_at`) da requisição foi ultrapassada. | Gerar nova requisição de assinatura com timestamp atualizado no backend/frontend. |
| `REPLAY_DETECTED` | `409 Conflict` | O `nonce` informado já foi processado anteriormente dentro da janela ativa. | Sempre gerar um UUID criptograficamente novo para cada chamada de assinatura. |
| `INVALID_ORIGIN` | `403 Forbidden` | O cabeçalho `Origin` não confere com o domínio autorizado da aplicação. | Conectar a partir da URL e domínio homologados pelo usuário. |
| `UNSUPPORTED_ALGORITHM` | `400 Bad Request` | O algoritmo de hash ou assinatura solicitado não é suportado pelo provedor. | Utilizar os algoritmos padrão homologados (`SHA256withRSA`). |
| `USER_CANCELLED` | `400 Bad Request` | O usuário clicou em Cancelar ou fechou o diálogo nativo de confirmação. | Tratar como cancelamento voluntário do usuário sem exibir alerta de erro crítico. |
| `PROVIDER_NOT_AVAILABLE` | `500 Server Error` | O provedor criptográfico necessário não está ativo no sistema operacional. | Verificar o Windows Certificate Store ou bibliotecas de runtime do Java. |
| `COMMUNICATION_ERROR` | `503 Service Unavail`| Erro de socket, timeout na confirmação visual ou porta ocupada. | Verificar se o CyberCore Signer está em execução e se a porta `21325` está livre. |
---
## 2. Estrutura do Payload JSON de Erro
Em qualquer resposta com status diferente de `200 OK`, o payload retornado pela API CCSP/1 adota o seguinte formato:
```json
{
"version": "1",
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"status": "error",
"error_code": "PIN_INCORRECT",
"message": "O PIN informado para o token A3 é incorreto."
}
```
---
## 3. Tratamento Tipado no SDK JavaScript
No SDK `@cybercore/signer-sdk`, cada código estruturado possui uma classe de erro correspondente herdando de `CyberCoreError`:
```javascript
import {
UserCancelledError,
PinIncorrectError,
TokenNotFoundError,
CertificateNotFoundError
} from '@cybercore/signer-sdk/errors';
try {
const result = await signer.sign({
certificateId: cert.id,
digest: documentoDigest
});
} catch (error) {
if (error instanceof UserCancelledError) {
console.info('Assinatura cancelada voluntariamente pelo usuário.');
} else if (error instanceof PinIncorrectError) {
alert('PIN incorreto! Verifique a senha do seu token para evitar o bloqueio.');
} else if (error instanceof TokenNotFoundError) {
alert('Dispositivo não detectado. Por favor, conecte seu token USB na porta do computador.');
} else if (error instanceof CertificateNotFoundError) {
alert('O certificado selecionado não foi encontrado ou expirou.');
} else {
console.error('Erro na operação de assinatura:', error.message);
}
}
```
docs/installation.md
+75 -19
View File
@@ -1,43 +1,99 @@
# Instalação e Empacotamento Nativo
O **CyberCore Signer** foi projetado para distribuição sem exigir que o usuário final tenha o Java ou JRE instalado em seu computador.
> **Guia de Distribuição com Runtime Embutido (`jpackage`), Instaladores MSI e Implantação Corporativa**
O **CyberCore Signer** foi projetado para distribuição nativa através da ferramenta `jpackage` (introduzida no JDK 14 e consolidada nas versões LTS 21/25). Isso significa que o usuário final **não precisa instalar o Java ou configurar variáveis de ambiente (JRE/JDK)** em sua máquina. O aplicativo carrega um runtime Java reduzido e isolado exclusivamente para sua execução.
---
## 1. Requisitos de Sistema
- **Sistema Operacional Homologado:** Windows 10 (64-bit) ou Windows 11 (64-bit).
- **Compatibilidade Adicional:** Linux x86_64 e macOS (arquitetura preparada).
- **Hardware:** Mínimo de 4 GB RAM, 150 MB de espaço em disco.
- **Porta de Rede Local:** A porta TCP `21325` deve estar livre em `127.0.0.1`.
* **Sistema Operacional Alvo:** Windows 10 (64-bit) ou Windows 11 (64-bit).
* **Compatibilidade Adicional:** Distribuições Linux modernas x86_64 (Ubuntu 20.04+, Debian 11+, Fedora 38+, RHEL 9+).
* **Memória RAM:** Mínimo de 4 GB (Recomendado: 8 GB).
* **Espaço em Disco:** 180 MB livres para os arquivos da aplicação e runtime embutido.
* **Rede Local:** A porta TCP `21325` deve estar livre no endereço de loopback `127.0.0.1`.
---
## 2. Geração do Instalador Windows (MSI / EXE) com `jpackage`
O empacotamento utiliza a ferramenta nativa `jpackage` incluída no JDK 21/25.
### 2.1 Pré-requisitos para a Máquina de Build
Para compilar e gerar o pacote de instalação no Windows:
1. **JDK 21+ LTS:** Com a variável `JAVA_HOME` devidamente configurada.
2. **WiX Toolset (v3.11+):** Necessário pelo `jpackage` para gerar instaladores `.msi`. Baixe em [wixtoolset.org](https://wixtoolset.org/) e adicione a pasta `bin` ao `PATH`.
### 2.2 Execução do Script de Empacotamento
Na raiz do projeto, execute o script em lote:
### No Windows:
Execute o script em lote localizado na raiz:
```cmd
scripts\package-windows.bat
```
### O que o script realiza:
1. Compila o projeto em modo release:
Ou execute manualmente os comandos do pipeline:
```cmd
:: 1. Compilação do projeto e geração do Fat JAR consolidado
mvnw clean package -DskipTests
:: 2. Geração do instalador nativo via jpackage
jpackage ^
--type msi ^
--name "CyberCore Signer" ^
--app-version 0.1.0 ^
--vendor "CyberCore Systems" ^
--input modules\cybercore-app\target ^
--main-jar cybercore-signer.jar ^
--main-class br.com.cybercore.signer.app.CyberCoreApp ^
--icon assets\cybercore.ico ^
--win-menu ^
--win-shortcut ^
--win-dir-chooser ^
--dest dist
```
2. Invoca o `jpackage` criando o instalador Windows:
- Extrai um runtime mínimo customizado contendo apenas os módulos necessários (`java.base`, `java.desktop`, `java.smartcardio`, `jdk.crypto.cryptoki`, etc.).
- Cria atalhos na Área de Trabalho e no Menu Iniciar.
- Gera um instalador padrão MSI ou EXE em `dist/`.
O instalador `CyberCore Signer-0.1.0.msi` será gerado dentro da pasta `dist/`.
---
## 3. Instalação e Inicialização com o Sistema
## 3. Empacotamento para Linux (DEB / RPM / AppImage)
1. Execute o instalador `CyberCore-Signer-0.1.0.msi`.
2. Siga as instruções do assistente de instalação.
3. Ao concluir, o ícone do **CyberCore Signer** aparecerá na Área de Notificação (System Tray) ao lado do relógio do Windows.
4. O serviço local `http://127.0.0.1:21325` estará imediatamente disponível para atender as aplicações web autorizadas.
No ambiente Linux x86_64:
```bash
# Executar o script nativo:
./scripts/package-jpackage.sh
```
O script utiliza o `jpackage` com o parâmetro `--type deb` ou `--type app-image`, empacotando os binários nativos e dependências do JavaFX com suporte ao subsistema gráfico X11/Wayland.
---
## 4. Implantação Corporativa e Instalação Silenciosa
Para administradores de rede (AD / GPO / SCCM / Intune) que precisam instalar o agente em centenas de estações de trabalho de forma automatizada:
### Instalação Silenciosa via Linha de Comando (MSI):
```cmd
msiexec /i "CyberCore Signer-0.1.0.msi" /qn /norestart
```
### Instalação com Registro de Log de Auditoria:
```cmd
msiexec /i "CyberCore Signer-0.1.0.msi" /qn /l*v "C:\Temp\cybercore_install.log"
```
### Desinstalação Silenciosa:
```cmd
msiexec /x "CyberCore Signer-0.1.0.msi" /qn /norestart
```
---
## 5. Inicialização com o Sistema e Área de Notificação (System Tray)
1. **Atalhos Criados:** O instalador cria automaticamente atalhos no Menu Iniciar e na Área de Trabalho.
2. **Inicialização Automática:** Durante a instalação, pode ser adicionada uma entrada no registro do Windows:
`HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run`
Chave: `CyberCoreSigner` -> Caminho: `"C:\Program Files\CyberCore Systems\CyberCore Signer\CyberCore Signer.exe" --minimized`
3. **Área de Notificação:** Quando iniciado, o agente minimiza para a bandeja do sistema (System Tray) ao lado do relógio do Windows, garantindo que o servidor local `127.0.0.1:21325` esteja sempre pronto para atender as solicitações das aplicações web homologadas.
docs/limitations.md
+32 -15
View File
@@ -1,25 +1,42 @@
# Limitações Técnicas e Dependências Declaradas
Conforme estabelecido na **Regra 23** do projeto (*"Não invente suporte a certificados, tokens, providers, algoritmos ou hardware que não tenham sido realmente implementados/testados. Quando algo depender de fabricante, middleware, Windows ou hardware físico, declare a dependência"*), as seguintes limitações são formalmente declaradas:
> **Declaração Formal de Dependências de Plataforma, Limitações de Hardware e Concorrência (Regra 23)**
Em estrita conformidade com a **Regra 23** do projeto CyberCore Signer (*"Não invente suporte a certificados, tokens, providers, algoritmos ou hardware que não tenham sido realmente implementados/testados. Quando algo depender de fabricante, middleware, Windows ou hardware físico, declare a dependência"*), as seguintes limitações técnicas e dependências são formalmente declaradas:
---
## 1. Dependências de Sistema Operacional e Hardware
## 1. Dependências de Sistema Operacional e Repositório Nativo
1. **Windows Certificate Store (Windows-MY):**
- Disponível apenas em sistemas operacionais Microsoft Windows (Windows 10/11).
- Em Linux e macOS, o provedor `WindowsCertificateStoreProvider` declara-se automaticamente indisponível (`isAvailable() == false`), operando via arquivos A1 ou PKCS#11 direto.
2. **Tokens A3 e Middlewares Proprietários:**
- O reconhecimento de smartcards e tokens USB depende da instalação prévia dos drivers do fabricante do dispositivo físico (ex: SafeSign Identity Client, SafeNet Authentication Client, drivers de leitoras Gemalto/Omnikey).
- O CyberCore Signer não instala drivers de hardware nem substitui o middleware do fabricante.
3. **Bloqueio de Cartão por Tentativas de PIN:**
- A política de bloqueio por tentativas consecutivas de PIN incorreto (geralmente 3 tentativas) é governada estritamente pelo chip físico do dispositivo A3 e pelo driver do fabricante, estando fora do controle do software do agente.
1. **Repositório Nativo do Windows (`Windows-MY`):**
- O provedor `WindowsCertificateStoreProvider` depende exclusivamente das APIs Win32/CryptoAPI e CNG expostas pelo provedor `SunMSCAPI` do JDK.
- **Disponibilidade:** Suportado exclusivamente em Microsoft Windows (Windows 10 e Windows 11).
- **Comportamento em Linux e macOS:** O provedor declara-se indisponível (`isAvailable() == false`) em sistemas não-Windows, operando através de arquivos A1 (PKCS#12) ou acesso PKCS#11 direto.
2. **Arquitetura de CPU dos Middlewares Proprietários:**
- A maioria dos drivers comerciais de tokens USB no Brasil (ex: SafeSign Identity Client da AET Europe e SafeNet da Thales) é compilada nativamente para a arquitetura **x86_64 (64-bit)**.
- Ambientes executando em processadores ARM64 (como novos computadores Windows on ARM ou Apple Silicon) requerem a camada de emulação x64 do sistema operacional para carregar essas bibliotecas dinâmicas legadas.
---
## 2. Limitações de Rede e Concorrência
## 2. Dependências de Hardware e Middlewares de Terceiros
1. **Escuta Exclusiva em Loopback:**
- O agente não oferece nem oferece suporte para escuta em endereços de rede externa (IPs locais de LAN ou WAN). Essa restrição é um elemento fundamental do modelo de segurança.
2. **Operações Concorrentes no Mesmo Token Físico:**
- Drivers PKCS#11 e smartcards ICP-Brasil frequentemente operam em modo mono-thread ou canal serial exclusivo. Por essa razão, o CyberCore Signer serializa as assinaturas em fila FIFO (`signLock`) para impedir corrupção de sessão no chip do cartão.
1. **Tokens A3 e Leitores de Smartcard Físicos:**
- O CyberCore Signer **não substitui os drivers do fabricante do token**. É indispensável que os drivers de hardware e o middleware do fabricante (SafeSign, SafeNet, GD Burti, Certisign, OpenSC, etc.) estejam instalados na estação de trabalho para que o sistema operacional e a leitora USB reconheçam o chip físico.
- O agente detecta a presença da biblioteca e interage com o dispositivo através de interfaces padronizadas (PKCS#11 ou CAPI/CNG).
2. **Política de Bloqueio por PIN Incorreto (Controle do Chip Físico):**
- O chip criptográfico de qualquer smartcard ou token ICP-Brasil possui um contador de segurança interno em hardware (geralmente limitado a 3 tentativas incorretas consecutivas).
- O bloqueio do cartão e a exigência do código de desbloqueio (PUK) são governados com exclusividade pelo hardware do fabricante. O software do CyberCore Signer não tem como burlar, redefinir ou impedir esse bloqueio.
---
## 3. Concorrência e Acesso a Dispositivos Mono-Thread
1. **Serialização Mandatória de Operações (`signLock`):**
- A especificação PKCS#11 e a maioria das implementações de drivers de smartcard operam sob canal serial exclusivo de I/O por leitora.
- Requisições simultâneas de assinatura contra o mesmo token físico causam erro de sessão ou congelamento no driver caso executadas em paralelo.
- **Solução Arquitetural:** O CyberCore Signer enfileira todas as operações criptográficas através de uma trava FIFO (`signLock`), processando cada assinatura individualmente e garantindo a estabilidade do hardware.
2. **Isolamento de Origem e Rede Loopback:**
- O servidor local CCSP/1 vincula-se estritamente ao endereço `127.0.0.1:21325`. O agente não suporta e deliberadamente rejeita conexões de computadores remotos da rede local (LAN), priorizando a segurança e a inviolabilidade da máquina do usuário.
docs/sdk.md
+142 -55
View File
@@ -1,17 +1,30 @@
# SDK Web JavaScript (@cybercore/signer-sdk)
O `@cybercore/signer-sdk` é a biblioteca oficial cliente em JavaScript para integrar aplicações web modernas com o agente desktop **CyberCore Signer** via protocolo **CCSP/1**.
> **Manual de Integração de Aplicações Web Modernas com o Agente Desktop CyberCore Signer**
O **`@cybercore/signer-sdk`** é a biblioteca cliente oficial em JavaScript (TypeScript ready) desenvolvida para permitir que aplicações web modernas (React, Next.js, Vue, Angular ou JavaScript nativo) se comuniquem com o agente desktop **CyberCore Signer** através do protocolo local **CCSP/1**.
---
## 1. Instalação e Importação
## 1. Instalação e Configuração
### Via Módulo ES6 (Browser ou Bundler Vite/Webpack/Next.js)
### 1.1 Instalação via Gerenciador de Pacotes
```bash
npm install @cybercore/signer-sdk
# ou
yarn add @cybercore/signer-sdk
# ou
pnpm add @cybercore/signer-sdk
```
### 1.2 Inicialização do Cliente
```javascript
import { CyberCoreSigner } from '@cybercore/signer-sdk';
const signer = new CyberCoreSigner({
applicationName: 'Portal Meu Negócio'
applicationName: 'Portal Meu Negócio', // Nome exibido no diálogo nativo do usuário
port: 21325, // Porta padrão do agente local (opcional)
timeoutMs: 30000 // Timeout padrão para operações (opcional)
});
```
@@ -19,99 +32,173 @@ const signer = new CyberCoreSigner({
## 2. Métodos da API
### `isInstalled(timeoutMs = 2000): Promise<boolean>`
Testa rapidamente se o agente desktop está ativo na porta local `21325`.
### 2.1 Verificação de Disponibilidade e Conexão
### `connect(): Promise<boolean>`
Realiza o handshake inicial de autorização. Se for a primeira vez que a aplicação tenta se conectar, abre uma caixa de diálogo nativa no desktop do usuário para concessão de acesso.
### `getCertificates(): Promise<Array<Object>>`
Retorna todos os certificados A1 e A3 disponíveis e operacionais na máquina do usuário.
#### `isInstalled(timeoutMs = 2000): Promise<boolean>`
Testa de forma rápida e silenciosa se o agente desktop está ativo na máquina do usuário.
```javascript
const certs = await signer.getCertificates();
certs.forEach(cert => {
console.log(`[${cert.type}] ${cert.common_name} (Validade: ${cert.valid_to})`);
const disponivel = await signer.isInstalled();
if (!disponivel) {
alert('O CyberCore Signer não foi detectado em sua máquina. Por favor, instale o aplicativo para continuar.');
}
```
#### `connect(): Promise<boolean>`
Inicia o handshake de autorização com o agente. Se a aplicação ainda não foi homologada pelo usuário, abre um diálogo nativo na tela do computador para autorização expressa.
```javascript
const autorizado = await signer.connect();
if (!autorizado) {
console.warn('O usuário recusou a autorização da aplicação.');
}
```
---
### 2.2 Descoberta de Certificados Digitais
#### `getCertificates(): Promise<Array<CertificateInfo>>`
Retorna a lista de certificados digitais válidos e disponíveis na máquina (A1 importados e A3 conectados via USB).
```javascript
const certificados = await signer.getCertificates();
certificados.forEach(cert => {
console.log(`[${cert.type}] ${cert.common_name}`);
console.log(`Titular: ${cert.subject_dn}`);
console.log(`Validade até: ${cert.valid_to}`);
console.log(`CPF/CNPJ: ${cert.cpf || cert.cnpj}`);
});
```
### `sign(options): Promise<Object>`
Solicita a assinatura digital local de um digest ou conteúdo bruto.
---
### `signPdf(pdfFile, options): Promise<Object>`
Assina um documento PDF (PAdES / Assinatura desacoplada). Recebe `File`, `Blob`, `ArrayBuffer` ou `Uint8Array`.
Calcula o SHA-256 no próprio navegador e transmite metadados do documento (`PDF`) ao agente para exibição clara na janela de confirmação.
### 2.3 Operações de Assinatura Digital
#### `sign(options): Promise<SignatureResult>`
Assina o hash SHA-256 (digest) de qualquer informação. A chave privada nunca sai do computador e apenas o digest é assinado.
```javascript
const pdfResult = await signer.signPdf(fileInput.files[0], {
certificateId: certs[0].id
const resultado = await signer.sign({
certificateId: 'win-4340656a',
digest: '47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=', // Hash SHA-256 em Base64
documentName: 'contrato_prestacao_servicos.pdf',
documentType: 'PDF'
});
console.log('Assinatura gerada (Base64):', resultado.signature);
console.log('Certificado do signatário:', resultado.certificate);
console.log('Cadeia de certificação:', resultado.certificate_chain);
```
### `signXml(xmlContent, options): Promise<Object>`
Assina um documento XML (XMLDSig / NF-e). Aceita string com o XML formatado ou objeto de arquivo `File`/`Blob`.
#### `signPdf(file, options): Promise<SignatureResult>`
Calcula o hash do documento PDF no próprio navegador e solicita a assinatura ao CyberCore Signer.
```javascript
const xmlResult = await signer.signXml(xmlString, {
certificateId: certs[0].id,
const inputElement = document.getElementById('arquivo-pdf');
const arquivoPdf = inputElement.files[0];
const resultadoPdf = await signer.signPdf(arquivoPdf, {
certificateId: certificados[0].id
});
console.log('PDF assinado digitalmente com sucesso!');
```
#### `signXml(xmlContent, options): Promise<SignatureResult>`
Assina o hash de documentos XML ou notas fiscais eletrônicas (NF-e, CT-e, MDF-e, XAdES). Aceita `string` com o XML ou arquivo `File`/`Blob`.
```javascript
const xmlString = '<infNFe Id="NFe3524...">...</infNFe>';
const resultadoXml = await signer.signXml(xmlString, {
certificateId: certificados[0].id,
documentName: 'nfe-3524.xml'
});
```
### `signFile(file, options): Promise<Object>`
Assina qualquer arquivo (ZIP, DOCX, imagens, binários, executáveis) gerando pacote de assinatura detached / CAdES.
#### `signFile(file, options): Promise<SignatureResult>`
Assina arquivos genéricos de qualquer formato (ZIP, DOCX, XLSX, imagens, binários).
```javascript
const fileResult = await signer.signFile(fileInput.files[0], {
certificateId: certs[0].id
const fileInput = document.getElementById('input-qualquer-arquivo');
const resultadoArquivo = await signer.signFile(fileInput.files[0], {
certificateId: certificados[0].id
});
```
### `authenticate(options): Promise<Object>` (ou `login(options)`)
Executa login seguro com certificado digital via desafio criptográfico (Challenge-Response).
---
### 2.4 Autenticação e Login Digital (Challenge-Response)
#### `authenticate(options): Promise<AuthResult>`
Realiza o login seguro de um usuário através de seu certificado digital ICP-Brasil. O backend da sua aplicação fornece um desafio único (*challenge / nonce*) e o CyberCore assina esse desafio.
```javascript
const auth = await signer.authenticate({
certificateId: certs[0].id,
challenge: 'server-nonce-12345'
// 1. Obter desafio único do backend da sua aplicação
const { challenge } = await fetch('/api/auth/challenge').then(res => res.json());
// 2. Solicitar assinatura do desafio ao CyberCore Signer
const authResult = await signer.authenticate({
certificateId: certificados[0].id,
challenge: challenge
});
console.log('Bem-vindo,', auth.subjectName);
console.log('CPF/CNPJ:', auth.subjectCpfCnpj);
console.log('Assinatura do Desafio:', auth.signature);
// 3. Enviar a assinatura e o certificado para o backend validar e autenticar a sessão
const response = await fetch('/api/auth/validate-login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
challenge: authResult.challenge,
signature: authResult.signature,
certificate: authResult.certificate
})
});
if (response.ok) {
console.log(`Login aprovado para: ${authResult.subjectName} (${authResult.subjectCpfCnpj})`);
window.location.href = '/dashboard';
}
```
### `extractSubjectInfo(certificateBase64): { name, cpfCnpj }`
Decodifica o certificado X.509 e extrai os dados do titular ICP-Brasil (Nome, CPF ou CNPJ).
### `verify(options): Promise<boolean>`
Validação sintática e criptográfica da integridade da assinatura gerada.
---
## 3. Tratamento Estruturado de Erros
O SDK expõe classes de erro dedicadas que herdam de `CyberCoreError`:
O SDK expõe classes de erro dedicadas que herdam de `CyberCoreError`, permitindo tratar cenários de forma elegante na interface:
```javascript
import {
UserCancelledError,
CertificateNotFoundError,
PinIncorrectError,
TokenNotFoundError
TokenNotFoundError,
CertificateNotFoundError,
CertificateExpiredError
} from '@cybercore/signer-sdk/errors';
try {
await signer.sign({ certificateId: 'cert-1', data: 'Contrato' });
} catch (err) {
if (err instanceof UserCancelledError) {
alert('Você cancelou a assinatura no CyberCore Signer.');
} else if (err instanceof PinIncorrectError) {
alert('O PIN do token informado está incorreto.');
} else if (err instanceof TokenNotFoundError) {
alert('Conecte o seu token USB na máquina para assinar.');
const res = await signer.sign({
certificateId: certId,
digest: documentoDigest
});
} catch (error) {
if (error instanceof UserCancelledError) {
// Usuário cancelou a assinatura voluntariamente na janela nativa
console.info('Operação cancelada pelo usuário.');
} else if (error instanceof PinIncorrectError) {
// PIN do token A3 incorreto
alert('PIN incorreto! Por favor, digite o PIN correto do seu token.');
} else if (error instanceof TokenNotFoundError) {
// Token USB desconectado
alert('Token não encontrado! Por favor, conecte seu dispositivo USB para assinar.');
} else if (error instanceof CertificateExpiredError) {
// Certificado ultrapassou a data de validade
alert('O certificado selecionado expirou. Entre em contato com sua autoridade certificadora.');
} else {
console.error('Erro na assinatura:', err);
// Demais falhas
console.error('Falha na operação com o CyberCore Signer:', error);
}
}
```
docs/security.md
+49 -24
View File
@@ -1,46 +1,71 @@
# Modelo de Segurança e Privacidade
O **CyberCore Signer** foi projetado seguindo as diretrizes rigorosas da ICP-Brasil e os princípios de *Security by Design* e *Least Privilege*.
> **Diretrizes de Segurança em Profundidade, Proteção Criptográfica e Conformidade LGPD**
O **CyberCore Signer** foi concebido sob os princípios de *Security by Design* (Segurança desde a Concepção) e *Least Privilege* (Menor Privilégio), seguindo as normas da **Infraestrutura de Chaves Públicas Brasileira (ICP-Brasil)** e as exigências da **Lei Geral de Proteção de Dados (LGPD — Lei nº 13.709/2018)**.
---
## 1. Isolamento de Rede
## 1. Isolamento de Rede e Proteção Local
1. **Loopback Estrito:** O socket do servidor HTTP local vincula-se exclusivamente ao endereço IP `127.0.0.1`. Nenhuma interface de rede externa (LAN ou WAN) escuta a porta de serviço `21325`.
2. **Prevenção contra Exposição Acidental:** Testes unitários e de arquitetura garantem que conexões fora de `127.0.0.1` sejam bloqueadas imediatamente no nível de bind do socket.
### 1.1 Ligação Estrita ao Loopback (`127.0.0.1`)
O servidor HTTP do protocolo CCSP/1 vincula-se exclusivamente ao endereço IPv4 local `127.0.0.1`.
* **Sem Escuta Externa:** O agente nunca realiza bind em `0.0.0.0` ou em interfaces de rede de área local (LAN) ou externa (WAN).
* **Bloqueio no Socket:** Tentativas de acesso originadas fora da própria estação de trabalho são sumariamente recusadas pelo subsistema de rede do sistema operacional antes de qualquer processamento da aplicação.
### 1.2 Proteção Contra Ataques de DNS Rebinding
Para neutralizar ataques em que domínios externos tentam resolver para `127.0.0.1` e burlar a política de mesma origem do navegador:
* O `CcspServer` valida expressamente o cabeçalho HTTP `Host`.
* Somente requisições com `Host: 127.0.0.1:21325` ou `Host: localhost:21325` são aceitas; qualquer outro valor é rejeitado com status `403 Forbidden`.
### 1.3 Controle de Origem (CORS) e Preflight
* Requisições prévias HTTP `OPTIONS` são validadas contra as origens web homologadas.
* O cabeçalho `Access-Control-Allow-Origin` é devolvido estritamente com a origem solicitante autorizada (nunca com wildcard `*`).
---
## 2. Autenticação e Autorização de Aplicações
Nenhuma aplicação desconhecida tem autorização para obter certificados ou assinar documentos sem consentimento expresso:
Nenhuma aplicação web externa tem acesso a certificados digitais ou serviços de assinatura sem autorização prévia e explícita do usuário:
1. **Handshake de Autorização (`POST /ccsp/v1/authorize`):**
- A aplicação web identifica-se enviando seu `application_id` (UUID estável) e seu nome amigável.
- O CyberCore Signer suspende a requisição e abre uma janela modal nativa na tela principal do sistema operacional perguntando se o usuário autoriza aquele domínio web.
2. **Armazenamento Seguro das Autorizações:**
- As aplicações autorizadas são gravadas em `~/.cybercore/authorized-apps.json`.
- O usuário pode visualizar e **revogar a qualquer momento** qualquer permissão através da aba **Configurações** na interface gráfica.
1. **Handshake de Aprovação (`POST /ccsp/v1/authorize`):**
- Ao tentar comunicar-se pela primeira vez, a aplicação web deve fornecer seu `application_id` (UUID estável) e seu nome amigável.
- O CyberCore Signer suspende a requisição e exibe um modal nativo no desktop informando o nome da aplicação e solicitando autorização do usuário.
2. **Armazenamento Seguro de Permissões:**
- As aplicações autorizadas são gravadas no arquivo local `~/.cybercore/authorized-apps.json`.
- O usuário pode visualizar e **revogar a qualquer momento** a autorização de qualquer aplicação através da aba **Configurações** na interface gráfica.
---
## 3. Proteção Contra Ataques de Replay
Cada solicitação de assinatura enviada pelo SDK deve incluir:
- Um `nonce` (UUID criptograficamente aleatório);
- Um campo `expires_at` (ou `timestamp`).
O componente `NonceManager`:
- Armazena os nonces recentes em memória protegida com expiração temporal (TTL);
- Rejeita com código estruturado `REPLAY_DETECTED` caso o mesmo nonce seja submetido mais de uma vez;
- Rejeita com código `REQUEST_EXPIRED` requisições cuja data/hora de validade já tenha sido ultrapassada.
Para impedir que requisições de assinatura capturadas por softwares maliciosos na máquina sejam reenviadas:
1. **Identificador Único (`nonce`):** Toda requisição ao `/ccsp/v1/sign` deve conter um UUID aleatório criptograficamente forte gerado pelo chamador.
2. **Janela de Validade Temporal (`expires_at`):** A requisição inclui uma estampa de tempo limite (TTL).
3. **Gerenciador de Nonces (`NonceManager`):**
- Mantém uma estrutura em memória com os identificadores recentes;
- Se o mesmo `nonce` for submetido mais de uma vez dentro da janela de validade, a operação é rejeitada com erro estruturado `REPLAY_DETECTED` (HTTP `409 Conflict`);
- Se a data/hora atual ultrapassar `expires_at`, a operação é rejeitada com erro `REQUEST_EXPIRED` (HTTP `422 Unprocessable Entity`).
---
## 4. Confirmação Visual Obrigatória e Proteção de PIN/Chaves
1. **Confirmação Manual do Usuário:** Toda e qualquer assinatura exige intervenção física e visual do usuário. Não é possível assinar "silenciosamente" por chamadas de API em segundo plano.
2. **Inviolabilidade da Chave Privada:** A chave privada nunca é exportada nem manipulada em forma de bytes puros. Todas as operações utilizam handles JCA/JCE ou comandos de hardware nativo.
3. **Proteção de PIN e Senhas:**
- O PIN de smartcards e a senha de arquivos A1 nunca são transmitidos para a aplicação web e nunca aparecem em logs de auditoria.
- Em caso de remoção do hardware, o `SmartCardWatcher` limpa e zera os buffers de memória de PIN imediatamente.
1. **Assinatura Exclusivamente Assistida:** Toda operação de assinatura exige interação humana voluntária. O agente nunca assina documentos em segundo plano de forma silenciosa ou desassistida via API.
2. **Inviolabilidade da Chave Privada:** As chaves privadas ICP-Brasil nunca são exportadas em formato de bytes brutos. Operações em certificados A3 utilizam handles criptográficos do hardware, garantindo que a chave nunca deixe o chip criptográfico.
3. **Higienização Segura de Memória Volátil:**
- O PIN de smartcards e senhas de certificados A1 nunca são convertidos para strings imutáveis do Java (`java.lang.String`).
- São manipulados estritamente como arrays de caracteres mutáveis `char[]`.
- Imediatamente após o carregamento da chave, o array é sobrescrito com zeros através de `Arrays.fill(pinBuffer, (char) 0)`.
4. **Remoção de Hardware (`TOKEN_REMOVED`):** Se o usuário desconectar o token USB ou retirar o cartão do leitor durante ou após a assinatura, o `SmartCardWatcher` força a limpeza imediata do cache de sessão e dos buffers do sistema operacional.
---
## 5. Privacidade de Dados e Conformidade com a LGPD
1. **Assinatura Descentralizada por Digest:** O CyberCore Signer opera prioritariamente recebendo apenas o hash SHA-256 do arquivo. O conteúdo completo do documento (contrato, laudo, prontuário) não transita pela API local nem é gravado em logs.
2. **Mascaramento e Sigilo de CPF:** Nos selos visuais em PDF, o usuário pode configurar o modo de exibição de seu CPF (`CpfDisplayMode`):
- `FULL`: Exibição completa (`123.456.789-00`);
- `MASKED`: Dígitos sensíveis ocultados (`***.456.789-**`);
- `NONE`: Remoção completa do CPF do gráfico visual do selo.
3. **Auditoria e Logs Transparentes:** Os logs do agente registram apenas identificadores de correlação (`request_id`), algoritmo utilizado e status da operação, sem armazenar hashes de documentos sigilosos ou dados pessoais desnecessários.