docs: update documentation files and project README structure
This commit is contained in:
Claudecio Martins
+89
-20
@@ -1,34 +1,103 @@
|
||||
# Diagnóstico de Ambiente e Auto-Teste
|
||||
# Diagnóstico de Ambiente e Resolução de Problemas
|
||||
|
||||
O **CyberCore Signer** possui um subsistema nativo de diagnóstico integrado (`DiagnosticService`), permitindo auditoria detalhada de saúde e integridade técnica da máquina do usuário.
|
||||
> **Guia de Auto-Teste, Checklist de Integridade de Runtime e Troubleshooting de Hardware**
|
||||
|
||||
O **CyberCore Signer** conta com um subsistema nativo de diagnóstico e telemetria local (`DiagnosticService`), projetado para validar a integridade da estação de trabalho e identificar rapidamente falhas de drivers, certificados ou subsistemas criptográficos do sistema operacional.
|
||||
|
||||
---
|
||||
|
||||
## 1. Itens Inspecionados no Diagnóstico
|
||||
## 1. Itens Inspecionados pelo Diagnóstico Automático
|
||||
|
||||
Ao abrir a aba **Diagnóstico** na interface ou invocar `diagnosticService.runDiagnostic()`, o agente avalia:
|
||||
Ao acessar a aba **Diagnóstico** na interface do agente desktop ou ao inicializar em modo `--dev`, o agente executa uma auditoria completa nos seguintes componentes:
|
||||
|
||||
1. **Ambiente Java / Runtime:**
|
||||
1. **Ambiente Java / Runtime Nativo:**
|
||||
- Versão do Java (requer Java 21+ LTS, homologado em Java 25 LTS);
|
||||
- Vendor do JDK (Temurin, Oracle, etc.);
|
||||
- Arquitetura do processador e sistema operacional.
|
||||
- Vendor do JDK (Eclipse Temurin, Oracle OpenJDK, Amazon Corretto);
|
||||
- Arquitetura da CPU (x86_64 / amd64) e sistema operacional (Windows 10/11 ou Linux).
|
||||
2. **Engine Criptográfica JCA/JCE:**
|
||||
- Disponibilidade dos provedores de segurança registrados na JVM (`SUN`, `SunRsaSign`, `SunMSCAPI`, etc.);
|
||||
- Suporte ao algoritmo de hash `SHA-256`;
|
||||
- Suporte ao algoritmo de assinatura `SHA256withRSA`.
|
||||
3. **Repositório de Chaves do Sistema Operacional:**
|
||||
- Detecção do repositório `Windows-MY` (Windows CryptoAPI / CNG).
|
||||
4. **Middlewares PKCS#11 e SmartCard:**
|
||||
- Verificação de bibliotecas de smartcard registradas no sistema (`eps2003csp11.dll`, `aetpkss1.dll`, `opensc-pkcs11.dll`, etc.);
|
||||
- Disponibilidade do subsistema PC/SC `javax.smartcardio`.
|
||||
- Suporte aos algoritmos de hash criptográfico (`SHA-256`, `SHA-512`);
|
||||
- Suporte aos algoritmos de assinatura digital (`SHA256withRSA`).
|
||||
3. **Repositório de Certificados do Sistema Operacional:**
|
||||
- Detecção do repositório de chaves `Windows-MY` via SunMSCAPI / CryptoAPI / CNG.
|
||||
4. **Middlewares PKCS#11 e Subsistema PC/SC:**
|
||||
- Presença das bibliotecas dinâmicas do fabricante (`aetpkss1.dll`, `eps2003csp11.dll`, `acospkcs11.dll`, `opensc-pkcs11.dll`);
|
||||
- Disponibilidade do subsistema de leitoras de smartcard `javax.smartcardio` (PC/SC Daemon / Smart Card Service do Windows).
|
||||
5. **Servidor Local CCSP/1:**
|
||||
- Teste de bind do socket em `127.0.0.1:21325` e integridade do pool de threads.
|
||||
|
||||
---
|
||||
|
||||
## 2. Auto-Teste de Assinatura Local (Self-Test)
|
||||
|
||||
A aba de diagnóstico disponibiliza o botão **"Executar Auto-teste de Assinatura"**:
|
||||
1. Seleciona o primeiro certificado operacional disponível na máquina.
|
||||
2. Gera um hash SHA-256 interno de teste: `"Documento_Teste_CyberCore_<timestamp>"`.
|
||||
3. Abre o diálogo de confirmação visual para validação do usuário.
|
||||
4. Executa a assinatura real JCA/JCE e afere os bytes gerados.
|
||||
5. Emite relatório de sucesso com tempo decorrido e tamanho da assinatura.
|
||||
A tela de diagnóstico oferece a função **"Executar Auto-teste de Assinatura"**:
|
||||
1. O agente identifica o primeiro certificado digital operacional conectado.
|
||||
2. Gera um hash SHA-256 interno sintético para teste: `"Documento_Teste_CyberCore_<timestamp>"`.
|
||||
3. Abre o diálogo nativo de confirmação visual para validação do usuário.
|
||||
4. Executa a assinatura real através do provedor JCA/JCE correspondente (solicitando PIN se A3).
|
||||
5. Valida os bytes da assinatura gerada e emite relatório com tempo decorrido em milissegundos e tamanho da assinatura.
|
||||
|
||||
---
|
||||
|
||||
## 3. Guia de Resolução de Problemas (Troubleshooting)
|
||||
|
||||
### 3.1 Token USB ou Smartcard A3 não é detectado
|
||||
* **Sintoma:** O token está plugado na porta USB mas não aparece no CyberCore nem na lista de certificados.
|
||||
* **Causa Comum:** O serviço de cartão inteligente do Windows (`ScardSvr`) está desativado ou o middleware do fabricante (SafeSign/SafeNet) não está instalado.
|
||||
* **Solução:**
|
||||
1. No Windows, pressione `Win + R`, digite `services.msc` e pressione Enter.
|
||||
2. Localize o serviço **Cartão Inteligente (Smart Card)** e garanta que seu status esteja **Em Execução** (Tipo de Inicialização: Automático).
|
||||
3. Verifique se o aplicativo de gerenciamento do token (ex: *SafeSign Token Utility* ou *SafeNet Authentication Client Tools*) reconhece o token.
|
||||
4. Desconecte o token USB, aguarde 3 segundos e reconecte em outra porta USB.
|
||||
|
||||
### 3.2 Erro `NTE_BAD_KEYSET` ou `Chave Privada Não Acessível`
|
||||
* **Sintoma:** O certificado aparece na lista, mas a assinatura falha com erro `PRIVATE_KEY_NOT_AVAILABLE` ou código Windows `0x80090016`.
|
||||
* **Causa Comum:** O certificado foi importado no Windows sem a chave privada correspondente, ou o usuário não tem permissão de leitura sobre o contêiner de chaves.
|
||||
* **Solução:**
|
||||
1. Abra o gerenciador de certificados do Windows: `certmgr.msc`.
|
||||
2. Navegue até **Pessoal -> Certificados** e dê um duplo clique sobre o certificado.
|
||||
3. Verifique se na parte inferior da aba Geral consta a mensagem: *"Você tem uma chave privada correspondente a este certificado"*. Se não constar, reinstale o arquivo A1 com a opção "Marcar esta chave como exportável" ativada.
|
||||
|
||||
### 3.3 Porta local `21325` já em uso (`BindException`)
|
||||
* **Sintoma:** O CyberCore Signer não inicializa e os logs acusam `Address already in use: bind`.
|
||||
* **Causa Comum:** Outra instância do CyberCore Signer ou aplicativo conflitante já está em execução na porta `21325`.
|
||||
* **Solução:**
|
||||
1. No Windows, abra o Gerenciador de Tarefas (`Ctrl + Shift + Esc`) e encerre eventuais processos `cybercore-signer` ou `javaw.exe` órfãos.
|
||||
2. No terminal (PowerShell), você pode identificar o processo ocupando a porta:
|
||||
```powershell
|
||||
Get-NetTCPConnection -LocalPort 21325 | Select-Object OwningProcess
|
||||
```
|
||||
3. No Linux:
|
||||
```bash
|
||||
sudo lsof -i :21325
|
||||
```
|
||||
|
||||
### 3.4 Aplicação Web acusa "Agente não instalado" ou Falha de Conexão
|
||||
* **Sintoma:** A chamada `signer.isInstalled()` no navegador retorna `false` ou dá timeout.
|
||||
* **Causa Comum:** O CyberCore Signer está fechado, o antivírus bloqueou a conexão loopback local, ou a aplicação web tenta conectar com protocolo incorreto.
|
||||
* **Solução:**
|
||||
1. Verifique se o ícone do CyberCore Signer está ativo na barra de tarefas (System Tray).
|
||||
2. Abra uma nova aba no navegador e acesse diretamente: `http://127.0.0.1:21325/ccsp/v1/status`.
|
||||
3. O navegador deve exibir o JSON com `"status": "ready"`. Se não exibir, abra o executável do CyberCore Signer.
|
||||
|
||||
---
|
||||
|
||||
## 4. Comandos Úteis de Diagnóstico no Terminal
|
||||
|
||||
### No Windows:
|
||||
```cmd
|
||||
:: Testar leitura de smartcards e drivers via utilitário nativo do Windows:
|
||||
certutil -scinfo
|
||||
|
||||
:: Listar certificados instalados no repositório Pessoal do usuário:
|
||||
certutil -user -store My
|
||||
```
|
||||
|
||||
### No Linux:
|
||||
```bash
|
||||
:: Verificar leitoras e cartões conectados via subsistema PC/SC:
|
||||
pcsc_scan
|
||||
|
||||
:: Verificar status do serviço pcscd:
|
||||
systemctl status pcscd
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user