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.

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

                                     ┌──────────────────────────────┐
  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 │
                 └─────────────────┘       └─────────────────┘       └─────────────────┘

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.
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.
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.
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:

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.

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

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.

Documentação

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

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 → Instalação do Servidor → Configuração do Servidor
Implantar no Azure	Instalação do Servidor → Azure App Service → Segurança
Distribuir as estações de trabalho	Instalação das estações de trabalho → Console administrativo → Configuração das estações de trabalho
Integrar uma aplicação cliente	Conceitos → API REST → Solução de problemas
Ativar certificados guardados no servidor	Conceitos → Segurança → Configuração do Servidor
Operar uma implantação existente	Operação → Console administrativo → Solução de problemas
Confiar numa autoridade certificadora privada	Conceitos → Console administrativo → Configuração das estações de trabalho

Ver em Markdown

Os três componentes​

Recursos​

Como funciona​

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

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

Documentação​

Ordem de leitura​