275 lines
10 KiB
Markdown
275 lines
10 KiB
Markdown
# CyberCore Signing Protocol (CCSP/1)
|
|
|
|
> **Especificação Técnica do Protocolo de Comunicação Local e API REST (Versão 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 e Isolamento
|
|
|
|
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. Visão Geral dos Endpoints (CCSP/1)
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## 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",
|
|
"status": "ready",
|
|
"agent": "CyberCore Signer",
|
|
"agent_version": "0.1.0",
|
|
"os": "Windows 11",
|
|
"timestamp": "2026-10-11T20:45:00Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 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.
|
|
|
|
#### 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`)
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"status": "success",
|
|
"certificates": [
|
|
{
|
|
"id": "win-4340656a",
|
|
"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 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"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.4 `POST /ccsp/v1/sign`
|
|
Solicita a assinatura digital local do digest informado com o certificado escolhido.
|
|
|
|
#### Payload da 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_prestacao_servicos.pdf",
|
|
"document_type": "PDF",
|
|
"nonce": "c4ca4238a0b923820dcc509a6f75849b",
|
|
"expires_at": "2026-10-11T20:50:00Z"
|
|
}
|
|
```
|
|
|
|
#### Resposta de Sucesso (`200 OK`)
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
|
"status": "signed",
|
|
"signature": "MEUCIQDq95kZc...Base64...",
|
|
"certificate": "MIIFazCCBF...Base64...",
|
|
"certificate_chain": [
|
|
"MIIFazCCBF...Base64...",
|
|
"MIIEazCCA1...Base64..."
|
|
],
|
|
"algorithm": "SHA256withRSA",
|
|
"subject_name": "MARIA DA SILVA",
|
|
"subject_cpf_cnpj": "12345678900",
|
|
"document_name": "contrato_prestacao_servicos.pdf",
|
|
"document_type": "PDF"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 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*).
|
|
|
|
#### Payload da Requisição
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"request_id": "8f3b201a-8c9d-4e5f-b012-3456789abcde",
|
|
"application_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"operation": "authenticate",
|
|
"challenge": "session-nonce-random-server-token-998877",
|
|
"certificate_hint": "win-4340656a",
|
|
"purpose": "AUTHENTICATION",
|
|
"nonce": "d3b07384d113edec49eaa6238ad5ff00",
|
|
"expires_at": "2026-10-11T20:50:00Z"
|
|
}
|
|
```
|
|
|
|
#### Resposta de Sucesso (`200 OK`)
|
|
```json
|
|
{
|
|
"version": "1",
|
|
"request_id": "8f3b201a-8c9d-4e5f-b012-3456789abcde",
|
|
"status": "authenticated",
|
|
"signature": "MEQCIF61pP...Base64...",
|
|
"certificate": "MIIFazCCBF...Base64...",
|
|
"certificate_chain": [
|
|
"MIIFazCCBF...Base64...",
|
|
"MIIEazCCA1...Base64..."
|
|
],
|
|
"algorithm": "SHA256withRSA",
|
|
"subject_name": "MARIA DA SILVA",
|
|
"subject_cpf_cnpj": "12345678900"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Estrutura Padrão de Erro e Códigos HTTP
|
|
|
|
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
|
|
```
|