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, no repositório de certificados do Windows dessa estação ou, quando a implantação optar por isso, num cofre no servidor administrado pela própria plataforma. O certificado pode ser o e-CPF da própria pessoa ou o e-CNPJ de uma Empresa do qual ela é a responsável.

O TrustBridge implementa o SignSession Contract, um contrato de API já existente com o qual as aplicações cliente já estão integradas. A especificação atual do contrato foi escrita a partir da implementação do TrustBridge e adotada pelo autor do contrato, então a página API REST descreve o contrato como a aplicação cliente deve esperá-lo.

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, os tokens que a máquina enxerga, digitação do PIN e o PIN do Certificado A1. Nunca fala diretamente com o Servidor.

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

O protocolo 5 é a exceção. O Servidor 1.13.0 e o Workstation 1.5.0 falam esse protocolo e são atualizados juntos: uma máquina ainda no protocolo 4 se conecta a um Servidor 1.13.0, mas nunca recebe pedido de PIN, então não atende sessões novas, e uma máquina com o Workstation 1.5.0 não consegue se conectar a um Servidor anterior à 1.13.0. Atualize o Servidor e faça upload do Workstation 1.5.0 para ele na mesma mudança, para que a frota possa começar a se atualizar logo. O Histórico de versões diz quais releases do Servidor e das estações de trabalho funcionam juntas.

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 por meio de uma Prova de PIN vinda da estação de trabalho do titular, e responde com um id de sessão opaco. Toda chamada seguinte identifica a sessão por esse id.
Sessões em nome de uma Empresa, assinadas com o e-CNPJ dela. Um cliente que também envia um cnpj recebe uma sessão que só assina com o e-CNPJ dessa Empresa do qual essa pessoa é a responsável. Uma sessão sem cnpj nunca assina com um e-CNPJ, então uma integração que nunca o envia não vê nada de novo.
O PIN nunca sai do Servidor. Nenhuma estação de trabalho recebe o PIN informado pela aplicação cliente. O Servidor desafia cada máquina candidata com um nonce, e a máquina responde com uma Prova de PIN, um HMAC cuja chave é o PIN que o titular digitou no Tray App. Quem decide se a prova confere é o Servidor. Um valor errado vindo de um cliente não consegue esgotar o contador de tentativas do token.
Tentativas que falham têm limite. PINs errados bloqueiam a criação de sessões para um CPF por um tempo. Além disso, cada estação de trabalho só pode dar um certo número de Provas de PIN que não conferem para um titular, e o Cofre de Certificados só pode tentar um certo número de senhas que não abrem nada para um titular; depois disso, essa máquina ou o cofre deixa de ser consultado para esse titular até que as falhas expirem.
Um A1 numa estação de trabalho pode assinar. O titular define um PIN do Certificado A1 no Tray App, e o PIN da aplicação cliente é verificado contra ele da mesma forma que o PIN de um 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.
Uma licença da PKI, guardada pelo Servidor. A licença do Lacuna PKI SDK é uma configuração do Servidor. O Servidor a entrega a cada máquina admitida sempre que ela se conecta, então renovar a licença é uma mudança no Servidor, sem visitar nenhuma máquina.
Atualizações das estações de trabalho entregues pelo Servidor. Um Administrador faz upload de uma Versão da Estação de Trabalho assinada na tela Versões da Estação de Trabalho e a oferece às máquinas que escolher. Uma máquina com o Workstation 1.4.0 ou posterior baixa a versão, confere a assinatura contra a lista de signatários compilada no serviço que ela já executa e a instala no primeiro momento ocioso. A Diretiva de Grupo pode desligar isso.
Um instalador assinado. O MSI e todos os executáveis do TrustBridge dentro dele têm a assinatura Authenticode da Lacuna Software, com carimbo de tempo, então o Windows mostra o nome do fornecedor e uma política que exija assinatura aceita o pacote.
Console administrativo em inglês ou em português do Brasil. Frota, fila de admissão, Versões da Estação de Trabalho, 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 guardados como hash e um acesso de emergência (break-glass) no nível da implantação.
Acesso com Certificado opcional para administradores. Quando a implantação o ativa, um Administrador ou Auditor entra com um e-CPF ICP-Brasil lido pelo Lacuna Web PKI, conferido com o CPF vinculado que outro Administrador definiu na conta. A implantação pode então desligar a entrada com senha.
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, um Protetor do Chaveiro e uma licença da PKI; 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 para todas as máquinas e pode desligar as atualizações entregues pelo Servidor.

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, para uma Empresa, um CNPJ) e um PIN. O Servidor tenta primeiro os Certificados do Cofre correspondentes. Se não der certo, desafia ao mesmo tempo todas as estações de trabalho que têm um certificado correspondente, e cada uma responde com uma Prova de PIN feita sobre o PIN que tem em cache ou diz que não tem nenhum. Se nenhum PIN em cache provar que confere e alguma máquina não tinha com o que provar, o titular recebe um pedido de PIN no Tray App, e a máquina responde com uma prova sobre o que ele digitar. O PIN em si fica no Servidor, que verifica cada prova. O certificado cuja prova confere é 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

# The Lacuna PKI SDK licence (required on every deployment; the whole fleet runs on it)
echo "PKI_LICENSE=$(base64 -w0 LacunaPkiLicense.config)" >> .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.5.0-x64.msi /qn SERVER_URL=https://trustbridge.example.com

A máquina aparece na fila de admissão em /admin/admission. Um Administrador a admite, e ela se conecta e recebe a licença da PKI do Servidor. As releases seguintes podem chegar a ela pelo Servidor, em vez de serem instaladas à mão. Veja Instalação das estações de trabalho.

Documentação

Assunto	Página
Uma integração em uma página: chave de API, sessões, assinatura, erros	Referência rápida
O vocabulário: sessões, Provas de PIN, custódias, empresas, registro, cofre, admissão, chaveiros, âncoras de confiança, a licença, versões	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 (inclusive a entregue pelo Servidor) 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	API REST
Protetor do Chaveiro, chaves de API, segundo fator e Acesso com Certificado, 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
Notas de release das linhas do Servidor e das estações de trabalho, com a compatibilidade entre elas	Histórico de versões

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
Atualizar o Servidor ou a frota	Histórico de versões → Operação → Instalação das estações de trabalho
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​