cybercore-systems/cybercore-signer
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
d8d2e6ee467158714252aab9c606f5847f4afc02
cybercore-signer/docs/CCSP.md
T

10 KiB
Raw Blame History

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

GET /ccsp/v1/status HTTP/1.1
Host: 127.0.0.1:21325
Origin: https://meusistema.empresa.com.br

Resposta de Sucesso (200 OK)

{
  "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

{
  "version": "1",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Portal Jurídico e Tributário"
}

Resposta de Sucesso (200 OK)

{
  "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)

{
  "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)

{
  "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

{
  "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)

{
  "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

{
  "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)

{
  "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:

{
  "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

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
Reference in New Issue View Git Blame Copy Permalink