Pular para o conteúdo principal

Lacuna PSC

O Lacuna PSC é o sistema que realiza as tarefas de um Prestador de Serviço de Confiança (PSC): ele permite que o titular de um certificado digital em nuvem use esse certificado para assinar documentos em qualquer aplicação que ele autorizar, sem instalar nada no computador e sem token criptográfico. O Lacuna PSC funciona em conjunto com o Amplia, que emite os certificados e guarda as chaves privadas.

O Lacuna PSC é 100% compatível com o DOC-ICP-17.01, o que significa que a interface do serviço é implementada com o framework OAuth 2.0 (RFC 6749), com PKCE (RFC 7636). Uma aplicação que já se integra a outros PSCs da ICP-Brasil usa o Lacuna PSC da mesma forma.

Certificados em nuvem na ICP-Brasil​

Em um certificado ICP-Brasil comum, a chave privada fica com o titular: em um arquivo no computador (A1) ou em um token criptográfico ou smart card (A3). Em um certificado em nuvem, o par de chaves é gerado e guardado em um HSM no ambiente de um Prestador de Serviço de Confiança, e o titular usa a chave remotamente, de qualquer dispositivo.

Para isso, o titular se autentica no PSC e autoriza cada aplicação que vai usar o certificado. A assinatura produzida é uma assinatura digital ICP-Brasil como qualquer outra; o que muda é onde a chave privada fica e como o titular dá o consentimento para usá-la:

Certificado no computador ou em tokenCertificado em nuvem
Onde fica a chave privadaNo computador, token ou smart card do titularEm um HSM do PSC, sem nunca sair dele
O que o titular precisa terO arquivo do certificado ou o dispositivo conectadoUma conta no PSC e o aplicativo móvel (ou um celular para SMS)
Como a aplicação assinaPelo navegador, com o Web PKI, ou no servidor, com o arquivo do certificadoPela API do PSC, com um token de acesso que o titular autorizou
O que protege o uso da chaveA senha do arquivo ou o PIN do tokenO PIN do certificado e um segundo fator (OTP ou SMS)

Componentes​

  • Amplia: emite o certificado e gera e guarda a chave privada em um repositório de chaves, como um HSM (veja gerenciamento de certificados em nuvem). As assinaturas são calculadas dentro dele.
  • Lacuna PSC: o portal do titular, onde ele emite o certificado, define o PIN e o PUK e gerencia dispositivos e autorizações, e o servidor OAuth 2.0 que as aplicações clientes usam para obter autorização e pedir assinaturas.
  • Aplicativo móvel Lacuna PSC: o autenticador do titular. Ele gera os códigos OTP usados como segundo fator e recebe notificações do certificado e de pedidos de assinatura (veja o histórico de versões do aplicativo).
  • Aplicação cliente: o seu sistema, registrado no PSC com um client_id, um client_secret e as URIs de redirecionamento autorizadas.

Ciclo de vida do certificado em nuvem​

  1. Pedido: o titular faz o pedido em uma Autoridade de Registro, por exemplo no Amplia Reg com um tipo de certificado de mídia Nuvem. Quando o pedido é aprovado, o titular recebe um link de emissão em nuvem (veja emissão de certificados).
  2. Emissão: no Lacuna PSC, o titular informa o número do pedido e o código de emissão, define o PIN (e o PUK, que substitui o PIN se ele for bloqueado) e pareia o aplicativo móvel. O Amplia gera o par de chaves no HSM e emite o certificado.
  3. Uso: a cada aplicação que for usar o certificado, o titular dá uma autorização com o PIN e o segundo fator, como mostra a seção abaixo.
  4. Gestão: pelo portal, o titular troca o PIN e o PUK, gerencia os dispositivos pareados e recebe avisos de vencimento do certificado.

Fluxo de uma assinatura com certificado em nuvem​

O diagrama abaixo mostra uma aplicação cliente assinando um documento com o certificado em nuvem de um titular. A aplicação nunca recebe a chave privada nem o PIN: ela recebe um token de acesso, envia o hash a ser assinado e recebe de volta a assinatura.

Fluxo de uma assinatura com certificado em nuvem pelo Lacuna PSC

  1. Localizar o titular (opcional): a aplicação consulta POST /v0/oauth/user-discovery com as suas credenciais e o CPF ou CNPJ do titular para saber se ele tem certificado no PSC. A resposta traz status (S ou N) e, em slots, os certificados encontrados.
  2. Autorizar a aplicação: a aplicação redireciona o navegador do titular para GET /v0/oauth/authorize, com o scope desejado, o lifetime (em segundos) e um code_challenge PKCE com code_challenge_method=S256. No PSC, o titular entra, escolhe o certificado e informa o PIN e o código OTP do aplicativo (ou o código recebido por SMS). Com isso, o PSC abre no Amplia uma sessão de uso da chave e redireciona o navegador de volta para a redirect_uri da aplicação com um code.
  3. Obter o token de acesso: a aplicação troca o code por um token de acesso em POST /v0/oauth/token, enviando o code_verifier, o client_id e o client_secret. A resposta traz o access_token (um token de portador), o expires_in, o scope e o identificador do titular que autorizou (authorized_identification).
  4. Obter o certificado: com o token, GET /v0/oauth/certificate-discovery devolve o certificado do titular, necessário para montar assinaturas como CAdES, PAdES e XAdES antes de calcular o hash.
  5. Assinar: a aplicação envia um ou mais hashes para POST /v0/oauth/signature. O PSC pede ao Amplia que assine cada hash com a chave do titular e devolve as assinaturas, que a aplicação incorpora ao documento.

Escopos de autorização​

O escopo pedido em /v0/oauth/authorize define o que o token de acesso permite:

EscopoO que permite
single_signatureAssinar um único hash em uma única requisição. O token é invalidado depois do uso
multi_signatureAssinar vários hashes em uma única requisição. O token é invalidado depois do uso
signature_sessionAssinar vários hashes em várias requisições, enquanto o token não expirar nem for revogado
authentication_sessionApenas autenticar o titular, sem permitir assinaturas. É o escopo usado quando nenhum é informado

Duração da autorização​

Quando o lifetime não é informado, o token de acesso vale por 60 minutos. O valor pedido é limitado pelo tipo do certificado: por padrão, até 7 dias para certificados de pessoa física (CPF) e até 30 dias para certificados de pessoa jurídica (CNPJ). Em uma instalação on-premises, esses valores são definidos nas seções Lifetimes e AccessTokenLifetimeLimits da configuração.

Formatos de assinatura​

Cada hash enviado a /v0/oauth/signature tem um id, um alias, o hash em Base64, o OID do algoritmo de hash em hash_algorithm (por exemplo, 2.16.840.1.101.3.4.2.1 para SHA-256) e o signature_format:

FormatoO que o PSC devolve em raw_signature
RAWO valor da assinatura do hash, em Base64, para a aplicação montar a assinatura final (por exemplo, com o PKI SDK)
CMSUma assinatura CMS (PKCS #7) destacada, já montada pelo PSC no padrão CAdES da ICP-Brasil: política AD-RB, ou AD-RT, com carimbo de tempo, quando o PSC tem um servidor de carimbo de tempo configurado

Uma resposta de /v0/oauth/signature tem o seguinte formato:

{
	"certificate_alias": "c15fb4ac-9463-45ec-88c3-01891c6d1369",
	"signatures": [
		{ "id": "documento-1", "raw_signature": "..." }
	]
}

Registro da aplicação cliente​

Antes de usar a API, a aplicação cliente precisa ser registrada no PSC, uma única vez. No registro, informe o nome da aplicação, as URIs para as quais o PSC pode redirecionar o titular depois da autorização e um e-mail de contato. Em troca, a aplicação recebe um client_id, que é público, e um client_secret, que deve ser guardado com segurança e nunca enviado ao navegador. Para registrar uma aplicação no Lacuna PSC em nuvem, entre em contato com a Lacuna.

Integrando com produtos da Lacuna​

Você não precisa implementar o protocolo do zero:

On premises​

O Lacuna PSC pode ser utilizado em nuvem (SaaS) ou você pode ter uma instância na sua própria infraestrutura ("on premises"). Veja o artigo Lacuna PSC on premises para mais informações. A documentação de integração completa, com todos os parâmetros e códigos de erro da API, é publicada pela própria instância do Lacuna PSC, na rota /docs.

Veja também​

Ver em Markdown