104 lines
5.7 KiB
Markdown
104 lines
5.7 KiB
Markdown
# Diagnóstico de Ambiente e Resolução de Problemas
|
|
|
|
> **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 pelo Diagnóstico Automático
|
|
|
|
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 Nativo:**
|
|
- Versão do Java (requer Java 21+ LTS, homologado em Java 25 LTS);
|
|
- 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 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 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
|
|
```
|