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, com SQL Server ou PostgreSQL, ou Azure App Service, com Azure SQL	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 e o Painel dele.
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, assina hashes quando uma sessão autoriza e informa a própria situação.
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 e as leitoras que a máquina enxerga, digitação do PIN (inclusive o PIN pedido quando um token é inserido) 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 par atual é o Servidor 1.24.0 (protocolos 5–6) e o Workstation 1.10.0 (protocolo 6). O Workstation 1.10.0 é distribuído com o Servidor 1.20.0 ou posterior, e com o Servidor 1.23.0 ou posterior para que o console administrativo mostre quem está no console de cada máquina. Do Servidor 1.22.0 ao 1.24.0, todos funcionam com qualquer release das estações de trabalho que a janela aceite. O Servidor 1.15.0 e posteriores recusam o Workstation 1.4.x; por isso, uma frota ainda na 1.4.x passa para a 1.5.0 antes da atualização do Servidor, e para a 1.10.0 depois dela. Uma máquina na 1.5.0 continua atendendo todas as sessões, exceto as que pedem o PIN a cada chamada de assinatura. 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.
• PIN por transação, por Aplicação Cliente. Um Administrador pode fazer uma Aplicação Cliente pedir o PIN do titular a cada chamada de assinatura: o titular autoriza cada chamada no Tray App, que mostra a aplicação e o que ela vai assinar, ou, para um Certificado do Cofre, a aplicação envia o PIN em cada chamada. Uma aplicação assim também pode ter o PIN dispensado na criação das sessões, para que o titular o digite no Tray App e em nenhum outro lugar.
• Uma Franquia de Assinaturas por Aplicação Cliente. Um Administrador pode limitar quantas chamadas de assinatura cada sessão criada por uma aplicação pode fazer; uma franquia de 1 dá sessões de uso único.
• Assinatura de hash para integradores que montam as próprias assinaturas. Uma Aplicação Cliente a que um Administrador concedeu esse recurso pode fazer a chave do titular assinar hashes que ela mesma calculou, com POST /v1/signatures/hashes, em torno do certificado e da cadeia que a sessão responde.
• Uma Assinatura de teste pelo navegador. Um Administrador pode assinar um documento de uma página de ponta a ponta pelo console administrativo para comprovar que a implantação funciona, e a implantação pode oferecer o mesmo formulário na sua página inicial (Landing Page). A partir do Servidor 1.23.0, uma execução pode assinar até 50 cópias numa única chamada em lote, como um integrador faria, e o formulário mantém o que foi digitado, para que a execução seguinte seja um único clique.
• O Lacuna Signer ou o REST PKI Core 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 ou, para uma Aplicação Cliente que um Administrador configura para usá-lo, ao REST PKI Core, que guarda os documentos assinados. A API é a mesma nos dois casos.
• 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 e pode depois revogá-la ou removê-la da frota. Nada que um instalador grave numa máquina consegue colocá-la na frota por conta própria.
• Estações de trabalho que informam a própria situação. A partir do Workstation 1.8.0, cada máquina informa ao Servidor os tokens dela e quão perto cada PIN está de bloquear, o middleware, as leitoras que o Windows não conseguiu iniciar e os erros que registrou, e o console administrativo mostra isso ao suporte. O Workstation Service também reinicia uma leitora de cartão USB que o Windows não conseguiu iniciar. A partir do Workstation 1.10.0, o relatório também traz a Conta no console, a conta do Windows conectada na máquina, e diz se o Tray App dela está rodando.
• Os problemas de uma estação de trabalho, vistos no console administrativo. A partir do Servidor 1.23.0, a tela Estações de Trabalho mostra quem está no console de cada máquina e destaca as máquinas em que há alguém conectado sem nenhum Tray App rodando, antes que a chamada de assinatura de alguém falhe. Ela conta as recusas de cada máquina nas últimas 24 horas, e o painel dela descreve cada uma em palavras, com o que perguntar ao titular. As telas Sessões de Assinatura e Operações de Assinatura mostram o titular, a Aplicação Cliente e a máquina, e dizem por que uma execução falhou. A partir do Servidor 1.24.0, a Trilha de Auditoria mostra o código de erro com que cada chamada à API foi respondida.
• O Tray App reaberto pelo menu Iniciar. A partir do Workstation 1.9.0, um atalho TrustBridge no menu Iniciar abre a janela do Tray App e substitui um Tray App que parou de responder; assim, o titular cujo Tray App foi fechado não precisa mais esperar a próxima entrada no Windows.
• O PIN pedido quando um token é inserido. A partir do Workstation 1.7.0, o Tray App pode receber o PIN de um token na hora em que ele é inserido, para que as assinaturas seguintes não precisem de pedido de PIN.
• 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 Política 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. Um Painel com a Atividade de assinatura e o que precisa de um Administrador, frota, fila de admissão, Relatórios das Estações de Trabalho, 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, Assinatura de teste, a Trilha de Auditoria e o Log do Servidor.
• Contas administrativas locais com segundo fator obrigatório. Dois perfis, Administrador e Auditor, cadastro 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 dele, SQL Server ou, no Docker, PostgreSQL 16 ou posterior, 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 à Política 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, o PIN pedido na inserção, o reinício das leitoras e o relatório da máquina.

Como funciona

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, 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.
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. Para uma Aplicação Cliente configurada para o REST PKI Core, o REST PKI Core valida o certificado, prepara o PDF e o conclui em torno da mesma única assinatura, e guarda o documento assinado.
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:

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 o cadastro 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. Essa página também trata da forma com PostgreSQL e do deploy-docker.ps1 do pacote de implantação, que faz todo o procedimento para ela e coloca o REST PKI Core ao lado do Servidor.

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

msiexec /i TrustBridge-Workstation-1.10.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 da estação 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 e remoção, chaveiros, âncoras de confiança, a licença, versões, Atividade de assinatura, Relatórios das Estações de Trabalho, Contas no console e Recusas da Estação de Trabalho	Conceitos
Implantação do Servidor no Docker, com SQL Server ou PostgreSQL, 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 desinstalação de estações de trabalho; Política de Grupo	Instalação da estação de trabalho
Cada configuração do Workstation Service e como uma frota a fornece	Configuração da estação 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, REST PKI Core, admissão e remoção, o que uma estação de trabalho informa, 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	Resoluçã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 da estação de trabalho → Console administrativo → Configuração da estação de trabalho
Integrar uma aplicação cliente	Conceitos → API REST → Resolução de problemas
Ativar certificados guardados no servidor	Conceitos → Segurança → Configuração do Servidor
Operar uma implantação existente	Operação → Console administrativo → Resolução de problemas
Atualizar o Servidor ou a frota	Histórico de versões → Operação → Instalação da estação de trabalho
Confiar numa autoridade certificadora privada	Conceitos → Console administrativo → Configuração da estação de trabalho