---
title: "Lacuna TrustBridge"
description: "O Lacuna TrustBridge é uma plataforma de assinatura remota para certificados ICP-Brasil de pessoas, que assina PDFs pela API REST do SignSession Contract."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-12"
---

# Lacuna TrustBridge

O Lacuna TrustBridge é uma **plataforma de assinatura digital remota para certificados ICP-Brasil de
pessoas físicas**. Ele permite que uma aplicação cliente assine documentos PDF com o certificado de um
usuário por meio de uma API REST, enquanto a chave privada do certificado fica exatamente onde está:
num smart card ou token USB conectado à estação de trabalho Windows do titular ou, quando a
implantação optar por isso, num cofre no servidor administrado pela própria plataforma.

O TrustBridge implementa o **SignSession Contract**, um contrato de API já existente com o qual as
aplicações cliente já estão integradas. Ele é a segunda implementação desse contrato e se comporta
como a primeira no protocolo sempre que possível. Onde ele diverge de propósito, as diferenças estão
listadas na página [API REST](https://docs.lacunasoftware.com/articles/trustbridge/rest-api#onde-este-servidor-difere-da-implementação-de-referência).

## Os três componentes

| Componente | Onde roda | O que faz |
|------------|-----------|-----------|
| **Servidor** | Um container Linux: Docker num host Linux ou Azure App Service | A aplicação web central. Atende as aplicações cliente pelo SignSession Contract, coordena a frota de estações de trabalho, guarda o Registro de Certificados, a Trilha de Auditoria e o Cofre de Certificados opcional, e hospeda o console administrativo. |
| **Workstation Service** | Um serviço do Windows na máquina de cada usuário | O único caminho para os certificados daquela máquina e para as chaves privadas deles, via PKCS#11 e o Lacuna PKI SDK. Conecta-se **de saída** ao Servidor por SignalR/WebSockets, anuncia os certificados que encontra, valida esses certificados e assina hashes quando uma sessão autoriza. |
| **Tray App** | A mesma máquina Windows, na sessão do usuário | A janela do titular para o serviço: status dos certificados, lista de certificados, digitação do PIN. Nunca fala diretamente com o Servidor. |

O Workstation Service e o Tray App são distribuídos juntos num único MSI. O Servidor é distribuído
como uma imagem de container. As duas linhas têm calendários de release independentes, e um Servidor
aceita a versão atual do protocolo das estações de trabalho e a anterior; por isso, uma frota é
atualizada **depois** do seu Servidor e no máximo uma release atrás dele.

## Recursos

- **Duas formas de custódia para um certificado, uma única API.** Um **Certificado de Estação de
  Trabalho** fica num token ou no repositório do Windows de uma máquina, e a chave dele nunca sai
  dessa máquina. Um **Certificado do Cofre** é um arquivo A1 que um Administrador importou para o
  Cofre de Certificados do Servidor. A aplicação cliente chama os mesmos endpoints nos dois casos e
  nunca fica sabendo qual custódia respondeu.
- **Sessões de Assinatura vinculadas a um CPF.** O cliente informa um CPF e o PIN do titular uma única
  vez. O TrustBridge confirma o PIN contra um certificado desse CPF, abrindo um Certificado do Cofre ou
  comparando com o PIN digitado no Tray App do titular, e responde com um id de sessão opaco. Toda
  chamada seguinte identifica a sessão por esse id.
- **O PIN nunca chega ao token pela rede.** Numa estação de trabalho, o PIN enviado pelo cliente é
  *comparado* com o PIN que o titular digitou localmente. Um valor errado vindo de um cliente não
  consegue esgotar o contador de tentativas do token.
- **Assinatura síncrona de documentos, individual ou em lote.** `POST /v1/signatures` assina um PDF
  dentro da própria requisição. `POST /v1/signatures/batch` assina até 50 numa única chamada. Os
  documentos só passam pela plataforma em trânsito: o TrustBridge assina hashes e nunca armazena
  documentos.
- **O Lacuna Signer cuida do trabalho com o documento.** O cálculo do hash, a montagem do PDF e o
  download do documento assinado são delegados ao [Lacuna Signer](https://docs.lacunasoftware.com/articles/signer).
- **Validação real dos certificados.** Cadeia de confiança, prazo de validade e revogação são
  verificados, com uma janela de tolerância configurável para quando uma autoridade certificadora
  estiver inacessível. Só um certificado `ACTIVE` pode abrir uma sessão ou assinar.
- **Confiança administrada.** Um Administrador adiciona uma **Autoridade Certificadora Confiável** por
  uma tela. Ela entra em vigor no Servidor em execução, sem reinício, e é enviada a todas as estações
  de trabalho admitidas.
- **Admissão de máquinas sem segredo compartilhado.** A estação de trabalho gera a própria chave, de
  preferência no TPM, anuncia-se e aguarda numa fila. Um Administrador a admite. Nada que um
  instalador grave numa máquina consegue colocá-la na frota por conta própria.
- **Console administrativo em inglês ou em português do Brasil.** Frota, fila de admissão, Registro de
  Certificados, Sessões de Assinatura, Operações de Assinatura, Aplicações Cliente e chaves de API,
  Certificados do Cofre, Autoridades Certificadoras Confiáveis, configurações, a Trilha de Auditoria e
  o Log do Servidor.
- **Contas administrativas locais com segundo fator obrigatório.** Dois perfis, Administrador e
  Auditor, inscrição de TOTP, códigos de recuperação e um acesso de emergência (break-glass) no nível
  da implantação.
- **Uma Trilha de Auditoria somente de acréscimo (append-only)** com o acesso à API, o ciclo de vida
  das sessões e das assinaturas, os eventos de estações de trabalho e de PIN e toda ação
  administrativa, com retenção configurável.
- **Nenhum estado gravável em disco local.** Os dois chaveiros do Servidor ficam no próprio banco de
  dados SQL Server dele, selados por um certificado que você fornece. Uma implantação é uma imagem,
  uma connection string e um Protetor do Chaveiro; uma atualização é uma nova tag de imagem, e o
  Servidor aplica as próprias migrações de schema ao iniciar.
- **Suporte a Diretiva de Grupo para a frota.** Um modelo ADMX publica a URL do Servidor e a licença
  do PKI SDK para todas as máquinas.

## Como funciona

```text
                                     ┌──────────────────────────────┐
  Client application ── X-API-Key ──▶│           Server             │──▶ Lacuna Signer
   POST /v1/sessions  (CPF + PIN)    │  SignSession Contract  /v1   │    (hash, PDF assembly,
   POST /v1/signatures               │  Certificate Registry        │     signed document)
   GET  /v1/signatures/{id}/document │  Certificate Vault (opt-in)  │
                                     │  Audit Log · admin console   │
                                     └──────────────┬───────────────┘
                                                    │ SignalR / WebSockets (outbound from the machine)
                          ┌─────────────────────────┼─────────────────────────┐
                          ▼                         ▼                         ▼
                 ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
                 │ Workstation Svc │       │ Workstation Svc │  ...  │ Workstation Svc │
                 │ + Tray App      │       │ + Tray App      │       │ + Tray App      │
                 │ token / A1 cert │       │ token / A1 cert │       │ token / A1 cert │
                 └─────────────────┘       └─────────────────┘       └─────────────────┘
```

1. Um **Workstation Service** se conecta de saída ao Servidor, anuncia os certificados da sua máquina
   e o veredito de validação de cada um, e mantém a conexão aberta.
2. Uma **aplicação cliente** chama `POST /v1/sessions` com um CPF e um PIN. O Servidor tenta primeiro
   os Certificados do Cofre desse CPF; se não der certo, repassa o PIN às estações de trabalho que têm
   um certificado do CPF. Se nenhuma estação de trabalho tiver esse PIN em cache, o titular recebe um
   pedido de PIN no Tray App. O certificado que confirmar o PIN é o que fica vinculado à **Sessão de
   Assinatura**.
3. O cliente chama `POST /v1/signatures` com o id da sessão e um PDF. O Servidor faz o upload do
   documento para o Lacuna Signer, obtém o hash a assinar, manda assiná-lo onde a chave está, conclui
   a assinatura no Signer e responde com o id da assinatura.
4. O cliente obtém o PDF assinado com `GET /v1/signatures/{signatureId}/document`.

Cada etapa fica registrada na Trilha de Auditoria, e o console administrativo lê esses mesmos
registros.

## Início rápido: o Servidor no Docker

Com o pacote de implantação e a imagem fornecidos pela Lacuna Software:

```bash
sudo mkdir -p /etc/trustbridge/tls /opt/trustbridge
sudo cp your-certificate.pfx /etc/trustbridge/tls/server.pfx     # TLS, trusted by every workstation
sudo chown 1654:1654 /etc/trustbridge/tls/server.pfx && sudo chmod 400 /etc/trustbridge/tls/server.pfx

cd /opt/trustbridge
cp <package>/docker-compose.yml . && cp <package>/.env.example .env && chmod 600 .env

# Mint the Key Ring Protector (required, keep the .pfx forever, off this host)
openssl req -x509 -newkey rsa:2048 -nodes -days 18250 -keyout protector.key -out protector.crt \
  -subj "/CN=TrustBridge Key Ring Protector"
openssl pkcs12 -export -inkey protector.key -in protector.crt -out protector.pfx -passout pass:
echo "KEY_RING_PROTECTOR_CERTIFICATE=$(base64 -w0 protector.pfx)" >> .env

# Edit .env: MSSQL_SA_PASSWORD, TLS_CERT_PASSWORD, SIGNER_BASEADDRESS, SIGNER_APIKEY,
#            ADMIN_BOOTSTRAP_EMAIL, ADMIN_BOOTSTRAP_PASSWORD
docker compose up -d
curl -s https://trustbridge.example.com/healthz     # Healthy
```

Em seguida, entre em `https://trustbridge.example.com/admin`, faça a inscrição do segundo fator e
remova as duas variáveis de bootstrap do `.env`. O procedimento completo, com a finalidade de cada
passo, está em **[Instalação do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/server-installation)**.

## Início rápido: uma estação de trabalho

```powershell
msiexec /i TrustBridge-Workstation-1.0.1-x64.msi /qn SERVER_URL=https://trustbridge.example.com PKI_LICENSE=<base64>
```

A máquina aparece na fila de admissão em `/admin/admission`. Um Administrador a admite, e ela se
conecta. Veja **[Instalação das estações de trabalho](https://docs.lacunasoftware.com/articles/trustbridge/workstation-installation)**.

## Documentação

| Assunto | Página |
|---------|--------|
| O vocabulário: sessões, custódias, registro, cofre, admissão, chaveiros, âncoras de confiança | [Conceitos](https://docs.lacunasoftware.com/articles/trustbridge/concepts) |
| Implantação do Servidor no Docker, o que incluir no backup, atualizações | [Instalação do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/server-installation) |
| Implantação do Servidor no Azure App Service com Azure SQL | [Azure App Service](https://docs.lacunasoftware.com/articles/trustbridge/azure) |
| Cada configuração do Servidor, com o padrão e um exemplo | [Configuração do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/configuration) |
| Instalação, admissão, atualização e remoção de estações de trabalho; Diretiva de Grupo | [Instalação das estações de trabalho](https://docs.lacunasoftware.com/articles/trustbridge/workstation-installation) |
| Cada configuração do Workstation Service e como uma frota a fornece | [Configuração das estações de trabalho](https://docs.lacunasoftware.com/articles/trustbridge/workstation-configuration) |
| O console administrativo, tela por tela | [Console administrativo](https://docs.lacunasoftware.com/articles/trustbridge/admin-console) |
| O SignSession Contract: endpoints, códigos de erro, exemplos, divergências | [API REST](https://docs.lacunasoftware.com/articles/trustbridge/rest-api) |
| Protetor do Chaveiro, chaves de API, segundo fator, tratamento do PIN, admissão, auditoria | [Segurança](https://docs.lacunasoftware.com/articles/trustbridge/security) |
| Operação do dia a dia: saúde, logs, reinícios, rotação, renovação de licença, ordem de atualização | [Operação](https://docs.lacunasoftware.com/articles/trustbridge/operations) |
| Modos de falha e como interpretá-los | [Solução de problemas](https://docs.lacunasoftware.com/articles/trustbridge/troubleshooting) |

Com o Servidor em execução, o contrato em formato legível por máquina é servido em `/openapi/v1.json`,
e uma referência navegável em `/scalar`. Os dois respondem sem credencial.

## Ordem de leitura

| Se você vai… | Comece por |
|--------------|------------|
| Implantar o Servidor pela primeira vez | [Conceitos](https://docs.lacunasoftware.com/articles/trustbridge/concepts) → [Instalação do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/server-installation) → [Configuração do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/configuration) |
| Implantar no Azure | [Instalação do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/server-installation#antes-de-escolher-a-forma-de-hospedagem) → [Azure App Service](https://docs.lacunasoftware.com/articles/trustbridge/azure) → [Segurança](https://docs.lacunasoftware.com/articles/trustbridge/security#o-protetor-do-chaveiro) |
| Distribuir as estações de trabalho | [Instalação das estações de trabalho](https://docs.lacunasoftware.com/articles/trustbridge/workstation-installation) → [Console administrativo](https://docs.lacunasoftware.com/articles/trustbridge/admin-console#fila-de-admissão) → [Configuração das estações de trabalho](https://docs.lacunasoftware.com/articles/trustbridge/workstation-configuration) |
| Integrar uma aplicação cliente | [Conceitos](https://docs.lacunasoftware.com/articles/trustbridge/concepts#sessão-de-assinatura-signing-session) → [API REST](https://docs.lacunasoftware.com/articles/trustbridge/rest-api) → [Solução de problemas](https://docs.lacunasoftware.com/articles/trustbridge/troubleshooting#erros-na-aplicação-cliente) |
| Ativar certificados guardados no servidor | [Conceitos](https://docs.lacunasoftware.com/articles/trustbridge/concepts#certificado-do-cofre-vault-certificate) → [Segurança](https://docs.lacunasoftware.com/articles/trustbridge/security#o-cofre-de-certificados) → [Configuração do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/configuration#o-cofre-de-certificados) |
| Operar uma implantação existente | [Operação](https://docs.lacunasoftware.com/articles/trustbridge/operations) → [Console administrativo](https://docs.lacunasoftware.com/articles/trustbridge/admin-console) → [Solução de problemas](https://docs.lacunasoftware.com/articles/trustbridge/troubleshooting) |
| Confiar numa autoridade certificadora privada | [Conceitos](https://docs.lacunasoftware.com/articles/trustbridge/concepts#autoridade-certificadora-confiável-e-conjunto-de-âncoras-de-confiança) → [Console administrativo](https://docs.lacunasoftware.com/articles/trustbridge/admin-console#autoridades-certificadoras-confiáveis) → [Configuração das estações de trabalho](https://docs.lacunasoftware.com/articles/trustbridge/workstation-configuration#certificatesvalidationuseservertrustedcas) |