docs: update documentation files and project README structure
This commit is contained in:
Claudecio Martins
+49
-24
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user