---
title: "Lacuna PSC"
description: "Lacuna PSC: Prestador de Serviço de Confiança que guarda certificados ICP-Brasil em nuvem com o Amplia e os disponibiliza às aplicações pela interface OAuth 2.0 do DOC-ICP-17.01."
canonical: "https://docs.lacunasoftware.com/articles/psc"
locale: "pt-BR"
product: "PSC"
last_updated: "2026-10-12"
---

# 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](https://docs.lacunasoftware.com/articles/amplia), que emite os certificados e
guarda as chaves privadas.

O Lacuna PSC é 100% compatível com o [DOC-ICP-17.01](https://www.gov.br/iti/pt-br/central-de-conteudo/doc-icp-17-01-verso-2-0-pdf), 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 token | Certificado em nuvem |
|---|---|---|
| Onde fica a chave privada | No computador, token ou smart card do titular | Em um HSM do PSC, sem nunca sair dele |
| O que o titular precisa ter | O arquivo do certificado ou o dispositivo conectado | Uma conta no PSC e o aplicativo móvel (ou um celular para SMS) |
| Como a aplicação assina | Pelo navegador, com o [Web PKI](https://docs.lacunasoftware.com/articles/web-pki), ou no servidor, com o arquivo do certificado | Pela API do PSC, com um token de acesso que o titular autorizou |
| O que protege o uso da chave | A senha do arquivo ou o PIN do token | O PIN do certificado e um segundo fator (OTP ou SMS) |

## Componentes

* **[Amplia](https://docs.lacunasoftware.com/articles/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](https://docs.lacunasoftware.com/articles/amplia/on-premises/configure-cert-management)). 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](https://docs.lacunasoftware.com/articles/psc/app-changelog)).
* **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](https://docs.lacunasoftware.com/articles/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](https://docs.lacunasoftware.com/articles/amplia-reg/issuance)).
1. **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.
1. **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.
1. **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](https://docs.lacunasoftware.com/images/psc/cloud-signature-flow-pt.svg)

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.
1. **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`.
1. **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`).
1. **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.
1. **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:

| Escopo | O que permite |
|---|---|
| `single_signature` | Assinar um único hash em uma única requisição. O token é invalidado depois do uso |
| `multi_signature` | Assinar vários hashes em uma única requisição. O token é invalidado depois do uso |
| `signature_session` | Assinar vários hashes em várias requisições, enquanto o token não expirar nem for revogado |
| `authentication_session` | Apenas 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](https://docs.lacunasoftware.com/articles/psc/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`:

| Formato | O que o PSC devolve em `raw_signature` |
|---|---|
| `RAW` | O valor da assinatura do hash, em Base64, para a aplicação montar a assinatura final (por exemplo, com o [PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk)) |
| `CMS` | Uma 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:

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

* O [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core) aceita certificados em nuvem nas
  [sessões de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions): a sua aplicação redireciona o usuário para uma
  página hospedada, onde ele assina com o Web PKI ou com um certificado em nuvem.
* No [PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk), o pacote [BrazilTrustServices](https://docs.lacunasoftware.com/articles/pki-sdk/cloud-certificates/brazil-trust-services) faz o acesso
  a PSCs que seguem o DOC-ICP-17.01 (veja [assinatura com certificado digital em nuvem](https://docs.lacunasoftware.com/articles/pki-sdk/cloud-certificates)).

## *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*](https://docs.lacunasoftware.com/articles/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

* [Histórico de versões](https://docs.lacunasoftware.com/articles/psc/changelog)
* [Histórico de versões do aplicativo móvel](https://docs.lacunasoftware.com/articles/psc/app-changelog)
* [Configuração de gerenciamento de certificados em nuvem no Amplia](https://docs.lacunasoftware.com/articles/amplia/on-premises/configure-cert-management)
* [DOC-ICP-17.01](https://www.gov.br/iti/pt-br/central-de-conteudo/doc-icp-17-01-verso-2-0-pdf)