cybercore-signer/docs/authentication-login.md

Autenticação e Login Digital via CyberCore Signer

Este documento descreve o fluxo de Login e Autenticação de Usuários com Certificado Digital ICP-Brasil (A1 e A3) através do agente desktop CyberCore Signer e o protocolo CCSP/1.

---

1. Visão Geral do Modelo de Autenticação

O login por certificado digital no CyberCore Signer adota o padrão de mercado Challenge-Response Criptográfico:

1. O backend da sua aplicação web gera um desafio único (challenge / nonce) para a sessão atual.
2. A aplicação web solicita a assinatura desse desafio ao CyberCore Signer através do SDK JavaScript.
3. O CyberCore Signer apresenta ao usuário na tela nativa do computador uma solicitação visual com destaque de LOGIN / AUTENTICAÇÃO:
   • Identifica a aplicação solicitante e a origem;
   • Mostra o certificado selecionado e o titular;
   • Solicita aprovação expressa do usuário (e a digitação do PIN caso seja token ou smart card A3).
4. O CyberCore assina o desafio com a chave privada do certificado local e devolve:
   • A assinatura digital do desafio;
   • O certificado X.509 completo (DER Base64) e cadeia;
   • O nome e CPF/CNPJ do titular extraídos do certificado.
5. O frontend web envia a resposta de volta ao backend, que:
   • Valida criptograficamente a assinatura com a chave pública do certificado recebido;
   • Confirma a validade e cadeia do certificado junto à ICP-Brasil;
   • Localiza o usuário correspondente no banco de dados pelo CPF/CNPJ;
   • Cria a sessão autenticada do usuário no sistema.

---

2. Exemplo de Integração Frontend com o SDK

import { CyberCoreSigner } from '@cybercore/signer-sdk';

const signer = new CyberCoreSigner({
  applicationName: 'Portal Corporativo'
});

async function realizarLoginComCertificado(certificateId) {
  // 1. Obter desafio único gerado pelo seu backend
  const { challenge } = await fetch('/api/auth/challenge').then(r => r.json());

  // 2. Solicitar autenticação ao CyberCore Signer
  const authResult = await signer.authenticate({
    certificateId: certificateId,
    challenge: challenge
  });

  // 3. Enviar assinatura e certificado ao backend para validação e abertura de sessão
  const sessionResponse = await fetch('/api/auth/login-certificate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      challenge: authResult.challenge,
      signature: authResult.signature,
      certificate: authResult.certificate
    })
  });

  if (sessionResponse.ok) {
    console.log('Usuário autenticado com sucesso:', authResult.subjectName);
    window.location.href = '/dashboard';
  }
}

---

3. Segurança e Prevenção de Ataques

• Prevenção de Ataques de Replay: Cada desafio deve possuir tempo de expiração curto (ex: 60 a 90 segundos) e ser descartado no servidor após uma única tentativa.
• Proteção da Chave Privada: A chave privada e o PIN do usuário permanecem exclusivamente sob custódia do hardware/computador local do usuário.
• Consentimento Explícito: O CyberCore Signer nunca assina desafios em segundo plano sem a exibição do diálogo e autorização do usuário na tela nativa.