Lacuna TrustBridge

Lacuna TrustBridge is a remote digital-signature platform for ICP-Brasil certificates held by people. It lets a client application sign PDF documents with a user's certificate through a REST API, while the certificate's private key stays exactly where it lives: on a smart card or USB token plugged into the holder's Windows workstation, or, when a deployment opts in, in a server-side vault the platform administers.

TrustBridge implements the SignSession Contract, an existing API contract that client applications already integrate against. It is the second implementation of that contract, and it matches the first on the wire wherever it can. Where it deliberately differs, the differences are listed on the REST API page.

The three components

Component	Runs on	What it does
Server	A Linux container: Docker on a Linux host, or Azure App Service	The central web application. Serves the SignSession Contract to client applications, coordinates the fleet of workstations, holds the Certificate Registry, the Audit Log and the optional Certificate Vault, and hosts the admin console.
Workstation Service	A Windows Service on each user's machine	The only path to the certificates on that machine and to their private keys, through PKCS#11 and the Lacuna PKI SDK. Connects outbound to the Server over SignalR/WebSockets, announces the certificates it sees, validates them, and signs hashes when a session authorizes it.
Tray App	The same Windows machine, in the user's session	The holder's window onto the service: certificate status, the certificate list, PIN entry. It never talks to the Server directly.

The Workstation Service and the Tray App ship together in one MSI. The Server ships as a container image. The two lines release on their own schedules, and a Server accepts the current workstation protocol version and the one before it, so a fleet is upgraded after its Server and within one release of it.

Features

Two custodies for a certificate, one API. A Workstation Certificate is on a token or in the Windows store of a machine, and its key never leaves that machine. A Vault Certificate is an A1 file an Administrator imported into the Server's Certificate Vault. A client application calls the same endpoints either way and never learns which custody answered.
CPF-bound Signing Sessions. A client supplies a CPF and the holder's PIN once. TrustBridge confirms the PIN against a certificate for that CPF, either by opening a Vault Certificate or by comparing against the PIN entered at the holder's Tray App, and answers an opaque session id. Every later call names the session by that id.
The PIN never reaches the token from the network. On a workstation, the PIN a client sends is compared against the PIN the holder typed locally. A wrong value from a client cannot burn the token's retry counter.
Synchronous document signing, single or batch. POST /v1/signatures signs one PDF inside the request. POST /v1/signatures/batch signs up to 50 in one call. Documents are held only in transit: TrustBridge signs hashes and never stores documents.
Lacuna Signer does the document work. Hash computation, PDF assembly and download of the signed document are delegated to Lacuna Signer.
Real certificate validation. Trust chain, validity period and revocation are checked, with a configurable grace window when a certification authority cannot be reached. Only an ACTIVE certificate can open a session or sign.
Administered trust. An Administrator adds a Trusted CA from a screen. It takes effect on the running Server with no restart and is pushed to every admitted workstation.
Machine admission with no shared secret. A workstation mints its own key, ideally in the TPM, announces itself and waits in a queue. An Administrator admits it. Nothing an installer writes to a machine can join the fleet by itself.
Admin console in English or Brazilian Portuguese. Fleet, admission queue, Certificate Registry, Signing Sessions, Signing Operations, Client Applications and API keys, Vault Certificates, Trusted CAs, Settings, the Audit Log and the Server log.
Local admin accounts with a mandatory second factor. Two roles, Administrator and Auditor, TOTP enrollment, recovery codes, and a deployment-level break-glass.
An append-only Audit Log of API access, session and signing lifecycle, workstation and PIN events and every administrative action, with a configurable retention.
No writable state on local disk. Both of the Server's key rings live in its own SQL Server database, sealed under a certificate you supply. A deployment is an image, a connection string and a Key Ring Protector; an upgrade is a new image tag, and the Server applies its own schema migrations at start.
Group Policy support for the fleet. An ADMX template publishes the Server URL and the PKI SDK licence to every machine.

How it works

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

A Workstation Service connects outbound to the Server, announces the certificates on its machine and their validation verdicts, and keeps the connection open.
A client application calls POST /v1/sessions with a CPF and a PIN. The Server tries the Vault Certificates for that CPF first; failing that, it relays the PIN to the workstations that hold a certificate for the CPF. If no workstation has that PIN cached, the holder is prompted at the Tray App. Whichever certificate confirms the PIN binds the Signing Session.
The client calls POST /v1/signatures with the session id and a PDF. The Server uploads the document to Lacuna Signer, gets the hash to sign, has it signed where the key lives, completes the signature at Signer, and answers the signature id.
The client fetches the signed PDF with GET /v1/signatures/{signatureId}/document.

Every step lands in the Audit Log, and the admin console reads the same records.

Quickstart: the Server on Docker

Using the deployment package and image provided by 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

Then sign in at https://trustbridge.example.com/admin, enroll the second factor, and remove the two bootstrap variables from .env. The full procedure, with what each step is for, is on Server installation.

Quickstart: a workstation

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

The machine appears in the admission queue at /admin/admission. An Administrator admits it, and it connects. See Workstation installation.

Documentation

Topic	Page
The vocabulary: sessions, custodies, registry, vault, admission, key rings, trust anchors	Concepts
Deploying the Server on Docker, what to back up, upgrades	Server installation
Deploying the Server on Azure App Service with Azure SQL	Azure App Service
Every Server setting, its default and an example	Server configuration
Installing, admitting, upgrading and removing workstations; Group Policy	Workstation installation
Every Workstation Service setting and how a fleet supplies it	Workstation configuration
The admin console, screen by screen	Admin console
The SignSession Contract: endpoints, error codes, examples, divergences	REST API
Key Ring Protector, API keys, second factor, PIN handling, admission, audit	Security
Day-2 operations: health, logs, restarts, rotation, licence renewal, rollout order	Operations
Failure modes and how to read them	Troubleshooting

While the Server is running, the machine-readable contract is served at /openapi/v1.json and a browsable reference at /scalar. Both answer without a credential.

Reading order

If you are…	Start at
Deploying the Server for the first time	Concepts → Server installation → Server configuration
Deploying on Azure	Server installation → Azure App Service → Security
Rolling out workstations	Workstation installation → Admin console → Workstation configuration
Integrating a client application	Concepts → REST API → Troubleshooting
Turning on server-held certificates	Concepts → Security → Server configuration
Operating an existing deployment	Operations → Admin console → Troubleshooting
Trusting a private certification authority	Concepts → Admin console → Workstation configuration

View as Markdown

The three components​

Features​

How it works​

Quickstart: the Server on Docker​

Quickstart: a workstation​

Documentation​

Reading order​