From d8d2e6ee467158714252aab9c606f5847f4afc02 Mon Sep 17 00:00:00 2001 From: Claudecio Martins Date: Sun, 11 Oct 2026 18:04:46 -0300 Subject: [PATCH] docs: update documentation files and project README structure --- README.md | 185 ++++++++++++++---------- docs/CCSP.md | 282 +++++++++++++++++++++++-------------- docs/README.md | 66 +++++++++ docs/a1-a3-certificates.md | 100 ++++++++++--- docs/architecture.md | 123 +++++++++++----- docs/development-mode.md | 87 +++++++++--- docs/diagnostics.md | 109 +++++++++++--- docs/errors.md | 96 ++++++++++--- docs/installation.md | 100 ++++++++++--- docs/limitations.md | 47 +++++-- docs/sdk.md | 197 ++++++++++++++++++-------- docs/security.md | 73 ++++++---- 12 files changed, 1040 insertions(+), 425 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index bae019f..1cc1a3d 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/CCSP.md b/docs/CCSP.md index ae4aec0..0ef3c4f 100644 --- a/docs/CCSP.md +++ b/docs/CCSP.md @@ -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 +``` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5d492fd --- /dev/null +++ b/docs/README.md @@ -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). diff --git a/docs/a1-a3-certificates.md b/docs/a1-a3-certificates.md index be529d3..558149f 100644 --- a/docs/a1-a3-certificates.md +++ b/docs/a1-a3-certificates.md @@ -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. diff --git a/docs/architecture.md b/docs/architecture.md index 150052c..6fe8a25 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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. diff --git a/docs/development-mode.md b/docs/development-mode.md index 71d3ce9..8481eac 100644 --- a/docs/development-mode.md +++ b/docs/development-mode.md @@ -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. diff --git a/docs/diagnostics.md b/docs/diagnostics.md index 8aeb6f7..192cdc3 100644 --- a/docs/diagnostics.md +++ b/docs/diagnostics.md @@ -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_"`. -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_"`. +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 +``` diff --git a/docs/errors.md b/docs/errors.md index 7f2fb9d..d1b3b8e 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -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); + } +} +``` diff --git a/docs/installation.md b/docs/installation.md index a7559a6..b1e3f97 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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: - ```cmd - mvnw clean package -DskipTests - ``` -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/`. +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 +``` + +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. diff --git a/docs/limitations.md b/docs/limitations.md index a48553f..af19f3f 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -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. diff --git a/docs/sdk.md b/docs/sdk.md index ee2a17c..8fc60d4 100644 --- a/docs/sdk.md +++ b/docs/sdk.md @@ -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` -Testa rapidamente se o agente desktop está ativo na porta local `21325`. +### 2.1 Verificação de Disponibilidade e Conexão -### `connect(): Promise` -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>` -Retorna todos os certificados A1 e A3 disponíveis e operacionais na máquina do usuário. +#### `isInstalled(timeoutMs = 2000): Promise` +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` +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>` +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` -Solicita a assinatura digital local de um digest ou conteúdo bruto. +--- -### `signPdf(pdfFile, options): Promise` -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` +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` -Assina um documento XML (XMLDSig / NF-e). Aceita string com o XML formatado ou objeto de arquivo `File`/`Blob`. +#### `signPdf(file, options): Promise` +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` +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 = '...'; + +const resultadoXml = await signer.signXml(xmlString, { + certificateId: certificados[0].id, documentName: 'nfe-3524.xml' }); ``` -### `signFile(file, options): Promise` -Assina qualquer arquivo (ZIP, DOCX, imagens, binários, executáveis) gerando pacote de assinatura detached / CAdES. +#### `signFile(file, options): Promise` +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` (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` +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` -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); } } ``` diff --git a/docs/security.md b/docs/security.md index adb637a..e93b602 100644 --- a/docs/security.md +++ b/docs/security.md @@ -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.