cybercore-signer/docs/CCSP.md

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)

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

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

{
  "version": "1",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Portal Assinaturas Jurídicas"
}

Resposta (200 OK)

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

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

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

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

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

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