209 lines
7.0 KiB
Markdown
209 lines
7.0 KiB
Markdown
# 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**.
|
|
|
|
A versão inicial descrita neste documento é a **CCSP/1**.
|
|
|
|
---
|
|
|
|
## 1. Princípios de Segurança
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## 2. Endpoints do Protocolo (CCSP/1)
|
|
|
|
### 2.1 `GET /ccsp/v1/status`
|
|
Verifica se o agente está instalado, em execução e pronto para operações.
|
|
|
|
#### Resposta de Sucesso (200 OK)
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"status": "ready",
|
|
"agent": "CyberCore Signer",
|
|
"agent_version": "0.1.0",
|
|
"os": "Windows 11",
|
|
"timestamp": "2026-10-08T19:40:00Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 2.2 `GET /ccsp/v1/certificates`
|
|
Retorna a lista de certificados digitais atualmente disponíveis e aptos para assinatura.
|
|
|
|
#### Headers / Parâmetros
|
|
- `X-CyberCore-AppId`: UUID da aplicação autorizada (ou query param `?application_id=uuid`).
|
|
- `Origin`: Origem web autorizada.
|
|
|
|
#### Resposta de Sucesso (200 OK)
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"status": "success",
|
|
"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",
|
|
"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",
|
|
"serial_number": "72910482910482019482",
|
|
"can_sign": true,
|
|
"status": "AVAILABLE"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 2.3 `POST /ccsp/v1/authorize`
|
|
Handshake inicial de uma nova aplicação web para solicitar autorização ao usuário.
|
|
|
|
#### 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
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
|
"application_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"operation": "sign",
|
|
"algorithm": "SHA256withRSA",
|
|
"digest": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
|
|
"certificate_hint": "win-4340656a",
|
|
"document_name": "contrato_locacao.pdf",
|
|
"document_type": "PDF",
|
|
"nonce": "c4ca4238a0b923820dcc509a6f75849b",
|
|
"expires_at": "2026-10-08T19:45:00Z"
|
|
}
|
|
```
|
|
|
|
#### Resposta de Sucesso (200 OK)
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
|
"status": "signed",
|
|
"signature": "MEUCIQDq...base64...",
|
|
"certificate": "MIIFazC...base64...",
|
|
"certificate_chain": [
|
|
"MIIFazC...base64...",
|
|
"MIIEazC...base64..."
|
|
],
|
|
"algorithm": "SHA256withRSA",
|
|
"subject_name": "CLAUDIO SILVA",
|
|
"subject_cpf_cnpj": "12345678900",
|
|
"document_name": "contrato_locacao.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).
|
|
|
|
#### Requisição
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
|
"application_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"operation": "authenticate",
|
|
"challenge": "server-session-challenge-nonce-2026",
|
|
"certificate_hint": "win-4340656a",
|
|
"purpose": "AUTHENTICATION",
|
|
"nonce": "c4ca4238a0b923820dcc509a6f75849b",
|
|
"expires_at": "2026-10-08T19:45:00Z"
|
|
}
|
|
```
|
|
|
|
#### Resposta de Sucesso (200 OK)
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
|
"status": "authenticated",
|
|
"signature": "MEUCIQDq...base64...",
|
|
"certificate": "MIIFazC...base64...",
|
|
"certificate_chain": [
|
|
"MIIFazC...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."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Tabela de Códigos de Erro Estruturados
|
|
|
|
| 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. |
|