Concepts

TrustBridge uses a small, precise vocabulary, and the admin console, the API and the logs all use it the same way. This page defines each term once. The Portuguese term shown beside some entries is what the admin console and the Tray App display when read in Brazilian Portuguese.

The platform

TrustBridge

The platform as a whole: the Server, the Workstation Service and the Tray App. The SignSession specification uses "Trust Bridge" for the certificate-monitoring Windows service specifically; in this documentation the unqualified name means the platform, and the service is always the Workstation Service.

Server (Servidor)

The central web application: the SignSession Contract REST API, the admin console, the Landing Page, the workstation channel, the Workstation Release downloads and the health probe, all on one port and told apart by path. It holds the platform's only database, on SQL Server or, on Docker, PostgreSQL (Server 1.20.0): sessions, operations, the Certificate Registry, the Certificate Vault, the Audit Log, admin accounts, both key rings, the Workstation Releases, Signing Activity, each workstation's last Workstation Report and the settings an Administrator saved. It also holds the deployment's PKI Licence, as configuration, and hands it to the fleet.

Workstation Service

The Windows Service installed on a user's machine. It is the only access path to the certificates on that machine and to their private keys, through PKCS#11 vendor middleware and the Lacuna PKI SDK. It connects outbound to the Server over SignalR/WebSockets, so no inbound port is opened on the machine. The private key of a Workstation Certificate never leaves the workstation. From Workstation 1.4.0 it can also install a Workstation Release its Server offers it. From Workstation 1.8.0 it sends the Server a Workstation Report of its own condition, and restarts a USB smart-card reader that Windows could not start. From Workstation 1.10.0 that report also says who is at the machine's console, the Console Account.

Workstation (Estação de Trabalho)

A machine the platform knows by its Workstation Key: one Windows computer running one Workstation Service and its Tray App, in one of Admission's states. Unqualified "workstation" means the machine, never its service and never a certificate on it, so a count of workstations counts machines, however many certificates each one holds. The Certificate Vault is not a workstation, and nothing it signs is attributed to one.

Tray App

The Windows tray application running in the signed-in user's session on the same machine. It shows certificate status and the certificate list, a Tokens tab with each token the service sees and the certificates on it, collects the PIN when a Signing Session needs one or a token is inserted (the Insertion Prompt), sets and changes an A1 PIN, shows whether the machine is waiting to be admitted or why it has no PKI Licence, and has a diagnostics pane with recent log lines. It talks to the Workstation Service over a local named pipe and never to the Server.

Each sign-in starts it as an icon with no window. From Workstation 1.9.0 the Start menu's TrustBridge shortcut opens its window: it brings forward a Tray App already running in the session, starts one where none runs, and replaces one that does not answer within 5 seconds, so a holder whose Tray App was closed or stopped answering gets it back without signing out.

Landing Page

The Server's unauthenticated front door at /. It says what this Server is and links to the admin console, the published documentation and Lacuna Software. It names no platform state, because everyone who can reach the Server can read it. Where the deployment turned it on, it also leads to the public Test Signature page. Distinct from where a signed-in admin lands, which is the Dashboard.

Dashboard (Painel)

The admin console's home (Server 1.17.0): the screen a signed-in admin lands on. It reads the platform's Signing Activity (today's, this month's and the last 30 days') beside what needs an Administrator, the fleet's standing and how long signing takes. It reads and changes nothing, and nothing it shows is gathered on the way through a signing call: a signature is never slower because the Dashboard exists. Its days and months are the deployment's, in the time zone Dashboard:TimeZone names. Distinct from the Landing Page, which is outside the login and names no platform state.

Test Signature (Assinatura de teste)

A signature asked for to watch the platform sign: an operator proving a deployment works end to end, or a demonstration. Whoever asks types a Client Application's API key, a CPF and, unless that application creates its sessions without a PIN, its PIN on a page the Server serves for it. It is real in every respect except who asked for it: a real Signing Session, bound the way any other is, a real document at the Signer, or at REST PKI Core where that application signs with it, so that the test proves the path its integrator uses, and a valid signed PDF, a page the Server writes describing the certificate. From Server 1.23.0 whoever asks may have up to fifty copies of that page signed at once, fewer where Signing:MaxBatchItems is lower, in the one batch call an integrator would make; a batch where some copies sign and some do not still counts as made. The session is ended as soon as the signature succeeds or fails. It is asked for from the admin console by an Administrator, always, or from the Landing Page by anyone, only where the deployment turned it on. Its calls are made as the Client Application whose key was typed; the Server holds no key of its own for them. Like any session's creation, it replaces a session already active for the same CPF and CNPJ, and a wrong PIN counts towards the holder's lockout. It is counted apart from the rest of Signing Activity.

Signer

Lacuna Signer, the external signature service that owns document flow: it computes the hash to sign, assembles the signed PDF and serves it for download. By default TrustBridge signs hashes and the Signer does the rest. For a Client Application that signs its documents with REST PKI Core, REST PKI Core does the rest instead, and the Signer takes no part in that document. Either way TrustBridge never assembles or stores a signed document.

REST PKI Core

Lacuna REST PKI Core, an external service that signs PDFs around a key it does not hold (Server 1.18.0). For a Client Application an Administrator switched to it (Sign documents with REST PKI Core), it does for that application's documents what the Signer does for everyone else's: it computes the hash to sign, assembles the signed PDF once the holder's key has signed that hash, and keeps and serves the signed document. The same calls answer with the same shapes, so the integrator cannot tell which of the two signed. Which one signs is decided on each signing call by the application whose key makes it, never by the one that created the Signing Session. It changes who builds the document and nothing about who signs it: the holder's certificate still makes exactly one signature, under the same custody, PIN and Signing Authorization rules. Which signature policy it applies, whether it marks the pages, which certificates it trusts and how long it keeps a document are settings of the REST PKI Core the deployment uses, not of TrustBridge. Its verdict on a certificate is a second one beside the platform's, and the two can disagree. Not Hash Signing, where the Client Application builds the signed container itself.

Sessions and signatures

Signing Session (Sessão de Assinatura)

The CPF-bound authorization that permits signing with a user's certificate, optionally on behalf of a Company: a session created with a CPF and a CNPJ signs only with that Company's e-CNPJ held by that person, and one created with a CPF alone signs only with the person's e-CPF. At most one is active per CPF, or per CPF and CNPJ pair; creating a new one replaces it, so a holder's own session and one for their Company can be active at once. It is addressed by an opaque sessionId that its creation answers. The CPF binds a session but does not address one, and no call recovers the id from a CPF.

A session is created when the PIN supplied by the client application proves the holder of a matching certificate:

• for a Workstation Certificate, by a PIN Proof from a single workstation that checks against it, made over the PIN cached or entered at that machine's Tray App, or over an A1 PIN;
• for a Vault Certificate, by opening the certificate's own key.

Wrong PINs lock the holder's CPF out of session creation for a while, whichever CNPJ was asked for. The one exception to proving the PIN is a Client Application with Sessions without a PIN on (see Per-Transaction PIN): a session it creates without a PIN binds only where exactly one certificate could serve it.

From creation it is bound to that one certificate and its holder, and signing under it routes only there. It expires after an idle window that only signing activity extends; reading its status never extends it. Where the Client Application that created it has a Signature Allowance, it also ends after that many signing calls.

A workstation-bound session survives the workstation disconnecting (it is inert while the machine is offline) and survives Server restarts. A session whose workstation was removed never signs again and expires on its own. A vault-bound session does not survive a Server restart, because the secret that opens the certificate is held only in memory; such sessions end as Stranded and the client creates a new one. The exception is a vault-bound Per-Transaction PIN session, which keeps no secret between calls and so survives a restart: its next call's PIN opens the certificate again.

"Session" on its own always means Signing Session. A PKCS#11 token session, a Windows logon session and an admin's web login session are different things and are always qualified.

Signing Operation (Operação de Assinatura)

The Server-side record of one document's signing run under a Signing Session, created at submission and driven to completed or failed. One session may cover many Signing Operations. The id a client is answered with, and fetches the signed document by, is the Signer document's own id, or, where REST PKI Core built the document, REST PKI Core's, exposed the same way. The Server mints none. A Signing Operation records which of the two built its document. One whose workstation was later removed keeps its record and says only that its workstation was removed.

Signature Allowance (Franquia de Assinaturas)

An optional second bound on a Signing Session: how many signing calls may be made under it. It is granted at creation from the figure an Administrator set on the Client Application that created the session, on the Client Applications screen (Server 1.17.0), and fixed for that session's life: changing the application's figure governs only sessions created afterwards. It is absent by default, on every Client Application, and a session granted none is bounded by its idle window alone. It was once one figure for the whole deployment (Sessions:SignatureAllowance, no longer read since Server 1.17.0). One charge is spent per call, whatever the number of documents: a batch of fifty spends one, and a call whose documents all failed before the key was used spends none. A session that runs out is Exhausted. An allowance of 1 makes every session single-use.

The bound is a policy bound rather than a security boundary: concurrent calls are each authorized before any of them has spent a charge. The Audit Log's per-signature rows are the exact record. Not Signing Activity, which counts what was signed rather than signing calls.

Per-Transaction PIN (PIN por transação)

A Client Application's posture, switched on by an Administrator, under which every signing call of the Signing Sessions it creates needs the holder's PIN for that call alone. For a Workstation Certificate, token or A1, the holder types it at the bound machine's Tray App, which shows who is signing what: that is a Signing Authorization, and the client application sends no PIN. For a Vault Certificate, where nobody can be prompted, the client application sends it with the call, and it opens the key for that call only. A session records at creation whether it is one, and which of the two, and keeps that for life (the contract's transactionPin: null, "workstation" or "client"); moving the switch changes no session already created. Session creation is unchanged, with the PIN still proven there, unless an Administrator has also switched the application to Sessions without a PIN (PIN dispensado na criação, Server 1.18.0), a second switch offered only while this one is on: then a PIN it sends is still proven, and without one the session binds only where exactly one certificate could serve it, leaving the PIN to each call. Either way such a session no longer authorizes a signature on its own, which is why a client using it keeps one long-lived session per user. One call asks once, however many documents or digests it carries. Not a Signature Allowance, which bounds how many calls a session may make and asks nobody anything. Needs workstation protocol 6 (Workstation 1.6.0 or later).

Signing Authorization (Autorização de assinatura)

A holder's approval of one signing call under a Per-Transaction PIN session bound to a Workstation Certificate. The Tray App, in the Console Session only, shows the Client Application's name and what the call will sign (the documents by name, or how many digests), and the holder types the PIN, which the token checks, or which is checked against the A1 PIN for an A1 Certificate. The Workstation Service then holds that PIN in memory for that call's signatures and no others, and wipes it when the call ends, when its uses are spent or when its time is up. A sign that names no open authorization is refused: it never falls back to the PIN Cache, and the PIN typed for it never reaches that cache. The Audit Log records each authorization requested, granted or refused, and names it on each signature it allowed; never the PIN. A machine holds at most Signing:MaxPendingAuthorizations calls waiting for their holder.

Hash Signing (Assinatura de hash)

A signing call that hands the holder of a Signing Session digests a Client Application computed itself, and answers the signatures: no document, no Signer, nothing to fetch afterwards (POST /v1/signatures/hashes). The Client Application builds whatever signed container it wants around them, which is why a session answers its certificate and chain before anything is signed. It produces no Signing Operation. One Hash Signing call spends one Signature Allowance charge however many digests it carries, and either every signature is answered or none is. Because it lets the Client Application choose exactly what the holder's key signs, which nothing can inspect, only a Client Application an Administrator granted it may make one.

Console Session (sessão de console)

The Windows logon session attached to the machine's physical console. A workstation can hold several logon sessions at once (remote desktop, fast user switching); a PIN prompt is shown only in this one, a PIN may be entered only from it, and the Workstation Service's log can be read only from it.

Console Account (Conta no console)

The Windows account signed in to a workstation's Console Session: whoever is in front of the machine, as far as Windows knows (Workstation 1.10.0, Server 1.23.0). An account, not a person: the platform knows that somebody signed in as that account and nothing about who typed its password. It is identified by its Windows security identifier (SID), and its DOMAIN\user name is a label for whoever reads the screen. A machine has none while nobody is signed in at its console, and it changes when somebody signs out or another user switches in. It is there whether or not a Tray App is running in that session, which is what lets an operator tell "nobody is at the machine" from "somebody is, and their Tray App is gone". The accounts signed in to the machine's other logon sessions, over Remote Desktop or by fast user switching, are not it, and no PIN prompt reaches them. It is never a certificate's holder, though one person may be both. The Workstation Report carries it, and the Workstations screen shows it in its Console Account column.

PIN Cache (Cache de PIN)

The Workstation Service's secure store of token PINs, keyed per certificate and populated only by PIN entry at the Tray App: at the prompt for a session's creation, at an Insertion Prompt, or when the holder asks to enter one. Entering a PIN once covers every certificate on the same token. Entries expire after a sliding idle TTL and are purged on explicit forget, on deactivation of the session they authorized, or when the token rejects the PIN, but not on token removal. The cache is memory-only by default and can optionally survive reboots. A cached PIN is what the machine proves with when the Server challenges it at session creation, and what unlocks the token when it signs; an entry's idle time slides when the Server tells the machine a session bound to it. Neither lifetime governs the other. A per-transaction signature never uses it: the PIN typed for a Signing Authorization is neither read from it nor written to it, and slides none of its entries. The PIN Cache is only about tokens: an A1 Certificate's PIN is an A1 PIN, kept as a verifier.

Insertion Prompt (Pedido de PIN na inserção)

The Tray App's offer, made when a token arrives in a reader, to take that token's PIN into the PIN Cache, so that the signatures that follow need no prompt (Workstation 1.7.0). It is made once per token, however many certificates it carries, and only for a token whose PIN is not already cached and on which at least one certificate that can sign is read. Only in the Console Session, and only while it is unlocked: a token that arrives while the machine is locked is offered at unlock, if it is still in and its PIN still not cached. Never for the tokens already present when the Tray App attaches, never for a locked token, and never for an A1 Certificate. It names the token, the reader and the holder of each certificate on it, gives way to any prompt the Server opens, and comes back afterwards if the token is still in and its PIN still not cached. The holder may decline it, and it lapses if left alone. A deployment may turn it off per machine (Tray:InsertionPrompt), and a token's arrival is then announced and not prompted for. It approves nothing and proves nothing: no Signing Session is created by it, and no Signing Authorization is ever given by it, so a Per-Transaction PIN session still prompts for each call. A PIN entered there is recorded on the workstation and not in the Audit Log, which hears of it only when a session uses it.

PIN Proof

A workstation's answer to the Server's challenge for one certificate at session creation. The Server sends the machine a fresh nonce and never the PIN; the machine answers with an HMAC over that nonce, keyed by the PIN it has cached for the certificate, by the PIN its holder just typed at the Tray App, or by an A1 PIN's verifier, or says it has nothing to prove with. The Server computes the expected proof from the PIN the client application sent and decides whether it matches; the machine is told only the verdict. So the client's PIN goes no further than the Server, and a machine learns nothing about it. Proofs are kept out of every log and out of the Audit Log, as the PIN is. Needs workstation protocol 5 or later.

Failed-Proof Budget

How many PIN Proofs one workstation may give for one holder's CPF that do not check, inside the same window and up to the same count as the CPF's failed-PIN lockout (Sessions:MaxPinFailures and Sessions:PinFailureWindow). Every failed proof counts, even when another machine matched. Once a machine has spent its budget for a CPF it is neither challenged nor prompted for that CPF, and counts as unreachable for that holder, until its failures age out. That is logged at Warning and audited as pin.proof-budget-spent. It is charged to that machine alone and is not the lockout, but a wrong PIN costs the holder's own machine one failed proof per certificate of theirs it holds, so it can be passed over before the lockout trips. The Certificate Vault has the same budget for passwords that open nothing, per CPF and on the same figures.

Certificates and custody

Workstation Certificate (Certificado de Estação de Trabalho)

A certificate held on a machine, reachable only through that machine's Workstation Service, and recorded in the Certificate Registry. Its private key never leaves the workstation, and signing with it happens there. An A3 Certificate (smart card or USB token) is always a Workstation Certificate. An A1 Certificate installed in the machine's Windows store is also one, and it can sign once its holder has set an A1 PIN for it on that machine.

Vault Certificate (Certificado do Cofre)

A certificate the Server itself holds, private key and all, imported by an Administrator as a PKCS#12 and kept in the Certificate Vault. It belongs to no machine and needs nothing online to open a session or sign. The password that unlocks it is supplied by the client application as the pin at every session creation and is never written down: the platform persists what it cannot sign without, and nothing that would let it sign unasked.

This is deliberately the more convenient and the weaker of the two custodies. Which custody a certificate uses is an operator's and an auditor's concern and is not told to a client application. An Administrator may take a Vault Certificate out of use (Fora de uso), which stops it opening sessions and signing while keeping the certificate and its history, or destroy its key material, which cannot be undone. There is no export or download path anywhere on the platform.

Certificate Registry (Registro de Certificados)

The Server-side, persisted mapping of certificate to workstation: which certificates (thumbprint, holder CPF, for an e-CNPJ its Company's CNPJ, and status) are present on which connected Workstation Services. Each service announces its certificates on connect and on every insertion or removal. A certificate's status is the latest validation verdict its workstation reported, and only ACTIVE can open sessions or sign. Entries are last-known state: a disconnected workstation's certificates stay visible, flagged offline with a last-seen time. The same certificate may legitimately be registered on several workstations.

Certificate Vault (Cofre de Certificados)

The Server-side store of Vault Certificates: what the platform holds, for whom (a holder's CPF, and for an e-CNPJ its Company's CNPJ), the latest verdict on each, and whether it is out of use. The counterpart of the Certificate Registry. A certificate may be in one, the other, or both.

Certificate Directory and Signing Target

The Server's reading of both stores as one: what can sign for a CPF, or for a CPF on a Company's behalf (matching both exactly), and in what order the platform tries them. Vault Certificates are tried first, then workstations. A Signing Target is one thing that can sign, resolved once per call: a certificate, the verdict it last carried and the custody that holds it. Past that point the two custodies are one thing to the rest of the Server.

Certificate verdicts

Every certificate carries one of five verdicts, and they stay English on every screen because they also travel on the wire:

Verdict	Meaning
ACTIVE	Chain builds to a trust anchor, inside its validity period, revocation checked and clear. The only verdict that can open a session or sign.
EXPIRED	Outside its validity period.
REVOKED	Revoked by its certification authority.
UNTRUSTED	Its chain does not build to any anchor this component trusts. Also what every certificate reports while the component has no usable PKI Licence: a lapsed licence, or a workstation the Server has not licensed yet.
STALE	No successful revocation check within the grace window; the CA has been unreachable too long.

A3 Certificate and A1 Certificate

ICP-Brasil certificate classes. An A3 private key lives on removable hardware that performs signatures itself and never yields the key; reaching it takes the holder's PIN, and the hardware counts wrong entries. An A1 is a software file whose private key is data, travelling under a password; once installed it presents no PIN. The same A1 may live on several machines at once, each a Workstation Certificate, or be imported to the Certificate Vault.

A1 PIN (PIN do Certificado A1)

A PIN the holder sets at the Tray App for one A1 Certificate on one workstation, so that the certificate can bind Signing Sessions the way a token certificate does: the machine answers the Server's challenge with a PIN Proof over it. The Workstation Service keeps a verifier and never the PIN, per certificate and per machine, so the same A1 on three machines has three A1 PINs. It can be set or changed only from the Console Session, and a change asks for the current one. It is deleted when the certificate leaves the machine, and also when a token turns up holding the same certificate. Until one is set, sessions over that A1 end in PIN_NOT_AVAILABLE. It is not a protection of the key, which stays in the Windows store as usable as it was; it decides who may sign through TrustBridge.

Token and middleware

A token is the removable hardware that holds A3 keys and signs with them: a smart card in a reader, or a USB token. The middleware is the token vendor's software, installed on the machine; TrustBridge never talks to a token directly, only through a middleware's PKCS#11 module, and only through the modules it knows where to find or an operator lists. The Tray App's Tokens tab shows each token the service saw, the middleware that read it and the certificates on it, and names a reader holding a card that no middleware read.

A failed reader is a smart-card reader plugged into the workstation that Windows could not start: no middleware can look through it and no token in it can be seen, and for a USB token, which is its own reader, it is the token itself failing to appear. From Workstation 1.8.0 the Tokens tab names it, and the Workstation Service restarts a USB reader Windows left in problem code 10 (failed to start) up to three times on its own, unless the deployment turned that off (Certificates:RestartFailedReaders). Each plugging-in earns a fresh set of tries, and a reader still failed after them is the holder's to unplug and plug back in. A reader left failed is reported in the Workstation Report, and the Workstations screen marks its machine Reader failed (Leitora com falha).

e-CPF and e-CNPJ

The two kinds of ICP-Brasil certificate a person can hold, each in A1 or A3 form. An e-CPF is issued to a natural person and names its holder by CPF. An e-CNPJ is issued to a Company and names two parties: the Company, by CNPJ, and the natural person responsible for it, by CPF. That person is the e-CNPJ's holder, exactly as for an e-CPF: it is their card, their PIN and their signature. A person with both holds two certificates that are not interchangeable, even when both sit on one token behind one PIN: a session for their CPF alone never signs with the e-CNPJ, and a session for the Company never signs with the e-CPF.

Company (Empresa) and its holder (Responsável)

The legal entity (pessoa jurídica) an e-CNPJ is issued to, identified by its CNPJ. A Company is never a holder: it has no PIN, and nothing is signed for it except by the person its e-CNPJ names. A Company may have several e-CNPJs held by different people. The admin console and the Tray App read in Portuguese call that person the Responsável, never the Titular, because in ICP-Brasil's Portuguese the titular of an e-CNPJ is the Company.

CPF

The Brazilian natural-person taxpayer id, eleven digits with two check digits. It is the key that binds a Signing Session to a certificate: alone for a session for that person, or with a CNPJ for a session on a Company's behalf, where it is still the person's. TrustBridge verifies the check digits of a CPF a client sends and refuses the eleven repeated-digit values; it never asks the Receita Federal whether the CPF was issued.

CNPJ

The Brazilian legal-entity taxpayer id, which names the Company an e-CNPJ is issued to. Fourteen characters, sent unpunctuated: twelve that identify the Company and two check digits. The twelve may include uppercase letters as well as digits (the alphanumeric CNPJ), and both forms are accepted. TrustBridge verifies the check digits of a CNPJ a client sends, and refuses a workstation's announcement whose CNPJ disagrees with the certificate it carries.

Actors and credentials

Client Application (Aplicação Cliente)

An external system integrating against the SignSession Contract, registered in the admin console. It holds one or more API keys, presented as X-API-Key, any of which authenticates it to the full contract surface. Signing Sessions are not bound to the Client Application that created them: any key may check, use or end a session whose id it holds. What a session demands is still decided by its creator and fixed at creation: the creator's Signature Allowance and its Per-Transaction PIN switches travel with the session to whichever key signs under it. Whether documents are signed by the Signer or REST PKI Core is the other way round: it is a choice about what the caller receives, not about what the holder agreed to, so it is read from the application making each signing call.

Admin Account (Conta Administrativa)

A person's local login to the admin console. There is no external identity provider. It holds one of two roles: Administrator may change platform state; Auditor may only read. Every account also carries a Second Factor. It opens with its password and Second Factor or, where the deployment allows it, with a Certificate Sign-In alone; a deployment can switch the password path off, and then the certificate is the only way in. An administrator never signs a document here: a certificate used to sign in only proves who the person is.

Second Factor (Segundo Fator) and Recovery Code (Código de Recuperação)

The TOTP code an Admin Account presents besides its password, enrolled by its owner on their own device. No administrator can read, set or hand over somebody else's; the only thing another Administrator can do is clear it, which forces re-enrollment. Recovery Codes are single-use substitutes issued as a set at enrollment and shown once; a new set replaces the whole old one, and clearing the Second Factor invalidates them. They are stored hashed, so the database holds no usable copy. A deployment may declare that it requires no second factor, and that is a deployment-wide posture set in configuration, never a per-account exemption. A Certificate Sign-In presents none and is complete without it, but every account still holds one, because the password path is the way back in.

Certificate Sign-In (Acesso com Certificado)

An Admin Account signing in to the admin console by proving it holds the key of an ICP-Brasil e-CPF that claims the account's Bound CPF, read through Lacuna Web PKI in the person's own browser. It is complete on its own: neither a password nor a Second Factor is presented. It is off unless a deployment turns it on, and is offered beside the password path unless the deployment switches passwords off. Any certificate the Server trusts for that CPF works, A1 or A3, including a renewal, so an expired certificate means a trip to the certification authority rather than a lockout. An e-CNPJ never signs anybody in, although it names its holder's CPF. The certificate signs a one-time challenge to prove who the person is and never signs a document.

Bound CPF (CPF vinculado)

The CPF an Administrator recorded as that of the person an Admin Account belongs to: what a Certificate Sign-In must match. It is typed on the accounts screen, never proved by presenting a certificate, so it is exactly as trustworthy as the Administrator who typed it; the account's owner sees on their own page which CPF it is, who set it and when. It is a CPF and never a certificate, so any trusted certificate claiming it signs the account in. It is unique across accounts. Only an Administrator sets, replaces or clears one, and never on their own account, so a deployment that switches passwords off needs at least two Administrators. Replacing or clearing it ends the owner's sign-ins within five minutes. It is unrelated to the CPF a Signing Session is bound to, even when one person is both.

Workstation Key (Chave da Estação de Trabalho)

The key a machine makes for itself, in its TPM where one is usable and otherwise in software, and cannot give up. It is the machine's identity: nothing is issued to it in exchange, so there is no workstation secret to copy off a disk. A machine that keeps its key across a reinstall is the same workstation; a machine that lost its key is a new one asking to join. The one exception is the Server's own choice: a machine that was Removed is forgotten with its key, so the same key asking again is a new machine. Whether the key is in hardware or software is the machine's key posture, which an Administrator reads before admitting it.

Workstation Assertion

What an admitted machine puts on the wire in place of a secret when it connects: a short-lived statement of its key's fingerprint, when it was minted, when it expires and a nonce, signed by the Workstation Key. One assertion opens one connection; presented again it is refused. It is a proof, not a credential, so a captured copy is worthless. Each download of a Workstation Release carries a fresh one too.

Admission (admissão)

The lifecycle a workstation is in. A machine announces itself (its key, hostname, operating system, versions and key posture) and waits for a person. It is in exactly one of three states:

State	Portuguese	Meaning
Pending	Pendente	Has asked and not yet been answered.
Admitted	Admitida	May connect.
Revoked	Revogada	Refused for as long as its row stands. A revoked machine that asks again is refused and never walks back to Pending. Only a Remove, which forgets the row and the refusal with it, lets its key ask again, as a new machine.

A machine may be sent from Admitted back to Pending without losing its key or its history; its request then never lapses, and it waits in the queue until somebody admits it again or removes it. An abandoned Pending request from a machine nobody ever admitted lapses after a configurable period and is deleted; the machine simply asks again as a machine the platform has never seen.

A machine's first seen time is when its row was written, which is its first request. A Pending row that lapsed and is written again gets a new one. In the database it is the FirstSeenAt column of Workstations, called EnrolledAt before Server 1.11.0, so a query or report on the old name has to change.

Admitting is a rate-limited human gate over a queue: with no out-of-band channel to check a fingerprint against, a machine is noticed rather than verified. That is acceptable because admission is not optional and nothing a machine holds admits it on its own.

Remove (Remover)

What an Administrator does when the Server should forget a machine it once admitted (Server 1.21.0): its row, what it last claimed and reported, and its block on its Workstation Key. It applies to a machine in any of Admission's states, provided somebody admitted it once; a request nobody ever admitted lapses instead. A removed machine that is still installed and asks again is a machine the platform has never seen, with no history, waiting to be admitted.

Housekeeping, not a security control. A lost, stolen or compromised machine is Revoked, which shuts it out and keeps its key refused. Removing a Revoked machine lifts that refusal along with the row.

What happened stays told. The Audit Log keeps every entry about the machine, and the removal adds one naming it in full. Signing Sessions and Signing Operations made through it remain, and say only that their workstation was removed. The Dashboard's counts of what it signed stay as they were.

Not uninstalling. Uninstalling is done on the machine and destroys its key; removing is done on the Server and forgets the machine. Either may happen without the other.

Installer Key

A key the Workstation Service signs its admission request with, besides its own, to show that the request came from the genuine product. Every copy of TrustBridge holds the same private half, so it is anti-abuse and not authentication of anything. A deployment may be given a key of its own instead.

Secrets and trust

Key Ring (Chaveiro)

The set of keys one part of the platform encrypts a secret with. There are three and no two are the same: the Workstation Service's, protecting PIN Cache entries; and the Server's two, one protecting the Certificate Vault (certificate-vault) and one protecting its own web sessions (web-sessions). Losing the vault's makes every Vault Certificate unopenable by anyone, this platform included; losing the web-session one costs a round of sign-ins.

Key Ring Protector (Protetor do Chaveiro)

The X.509 certificate with an RSA private key that makes the Server's two key rings readable, supplied as configuration and never kept by the platform. Required of every Server, including one with no Vault Certificates, because the web-session ring needs it too. Losing it is the most expensive way to misoperate the platform. It may be rotated, but a retired protector is never discarded: the Server still needs every protector any stored key was ever sealed under, permanently.

Trusted CA and Trust Anchor Set

A Trusted CA (Autoridade Certificadora Confiável) is one certification authority an Administrator told this Server to trust, added and removed on the admin console, in force without a restart on the Server and on every admitted machine that has heard from it since. It is not a synonym for "certification authority": every CA in ICP-Brasil is trusted and none of them is a Trusted CA. Removing one can turn certificates UNTRUSTED, so the platform says how many depend on it first.

Where a deployment turns Certificate Sign-In on, a Trusted CA also decides who can sign in to the admin console. A sign-in matches a CPF rather than a certificate, so an authority somebody adds can issue a certificate for any administrator's Bound CPF and sign in as them, with no password and no Second Factor. Adding one is trusting whoever holds its key with every Bound CPF on the platform; the Audit Log still names who added it. Removing one can likewise refuse the sign-ins of administrators whose certificates it issued, and the Trusted CAs screen gives an approximate count of them.

A component's Trust Anchor Set is what a chain must build to before that component calls a certificate trusted. It is composed from several sources, any one of which suffices: the ICP-Brasil roots the PKI SDK carries, optionally the machine's own root store, anchor files configured on a workstation, and the Trusted CAs from the Server. A workstation holding a non-empty Trusted CA set from the Server composes it instead of its own anchor files. Only a self-signed certificate can terminate a chain, so a set holding only intermediates anchors nothing.

Licensing and updates

PKI Licence (licença da PKI)

The permission the Lacuna PKI SDK needs before it reads a certificate at all. There is one per deployment, and the Server holds it as configuration (Certificates:Validation:License): a Server without one does not start. The Server validates its own Vault Certificates with it and hands it to every Admitted machine each time that machine connects, so renewing it is an edit and a restart on the Server and a visit to no machine. No machine keeps it across a restart, and nothing a workstation installation writes supplies it. A machine that is Pending, or that started while its Server was unreachable, has none until the Server licenses it, and reads every certificate UNTRUSTED meanwhile; the Tray App says which unlicensed state it is in. A lapsed licence does not stop the Server, but nothing in the fleet or the vault can sign until it is renewed, and every admin page says so. It is not a credential: it authenticates nobody and says nothing about which certificates are trusted.

Workstation protocol version

The version of the channel between the Workstation Service and the Server, which each side states in the handshake. A Server accepts a window of two versions, its own and the one before. A machine below the window is refused as update required; a machine above it is refused with update the Server first, gets no PKI Licence, and reads every certificate UNTRUSTED until the Server is upgraded. That is why, as a rule, the Server is upgraded first and the fleet within one release of it.

Protocol	First Server	Workstation releases	What it added
3	1.7.0	1.1.0 to 1.3.0	The Server licenses the machine in the handshake.
4	1.9.0	1.4.0 to 1.4.2	Release Offers: the machine can take updates from its Server.
5	1.13.0 (window 4–5)	1.5.0	PIN Proofs replace sending the PIN to the machine.
6	1.15.0 (window 5–6)	1.6.0 to 1.10.0	Signing Authorizations, for Per-Transaction PIN.

Protocol 5 asked for the two to move together: a protocol 4 machine still connected to a Server 1.13.0 or 1.14.x, but was never sent a PIN challenge or prompt, so for new sessions it counted as offline. Protocol 6 is Server first again: a protocol 5 machine connects to Server 1.15.0 and serves every session as before, but is never chosen for a per-transaction one. Workstation 1.7.0 to 1.10.0 stay on protocol 6; 1.8.0 and later are delivered with Server 1.20.0 or later, the first whose workstation channel takes a Workstation Report of up to 1 MB. What later releases added on either side rides protocol 6 as optional fields that an older counterpart ignores: Workstation 1.10.0's console shows from Server 1.23.0, and on a Server from 1.23.0 a machine that sends none reads Needs Workstation 1.10.0. A Workstation Release's MSI states the protocol it speaks, and a Server refuses to store one outside its window.

Workstation Release (Versão da Estação de Trabalho)

A signed package of the workstation components, the Workstation Service and the Tray App, that an Administrator uploaded on the Workstation Releases screen so the Server can offer it to the fleet. The Server keeps one per version, in its database, and reads the version, the protocol it speaks and its signer out of the file itself, so nobody types them. It refuses, with nothing stored, an unsigned file, a signer its Publisher Pin does not list, a protocol outside its window, or a version it already holds. Storing a release changes no machine: only a Release Offer does. Distinct from a Server release, which is a separate line with versions of its own.

Release Offer (oferta)

A Workstation Release offered to one Admitted machine by an Administrator. A machine holds at most one: offering another replaces it, and withdrawing it leaves none. A machine acts only on an offer above the version it runs and only if its Group Policy leaves updates on. It downloads the release, checks it (the announced hash, the Authenticode signature and timestamp, a signer on its own Publisher Pin, revocation, the product and the version), waits for an idle moment with no signing and no PIN prompt in progress, installs it without asking the holder, and reports whether it installed, failed or was refused. A release that failed or was refused is not tried again until an Administrator offers it again. Offering to every machine below a release is a one-time selection, so a machine admitted later is offered nothing until somebody offers again. A machine on Workstation 1.3.0 or older cannot take an offer; the Workstations screen names it as needing a manual update.

Publisher Pin

The list of certificates a Workstation Release may be signed by, compiled into the product, both the Server and every Workstation Service, so that no Server, Administrator, policy or setting can change it. A machine installs nothing whose signer the pin it already runs does not list, so the worst a compromised Server or admin account can do through updates is install a genuine, newer release early. Each machine reports its pin, and the Server offers a release only to machines whose pin lists its signer. Because the pin names certificates rather than a publisher, a renewal of Lacuna Software's code-signing certificate goes out first as a bridge release, signed with the old certificate and listing both; a machine that misses it is updated by hand or by Group Policy.

Records

Audit Log (Trilha de Auditoria)

The Server's append-only record of platform events: API access, session and signing lifecycle (Hash Signing and Signing Authorizations included), workstation and PIN events, Test Signatures, and admin actions, one entry per event with actor, subject identifiers and outcome. An API call's entry also keeps the Error Code it was answered with (Server 1.24.0), and only the code. PINs, PIN Proofs, document content and signature bytes never appear in it. An entry the database will not take is written to the Server log at Critical, carrying the row itself.

Error Code (código de erro)

The SignSession Contract's machine-readable name for why a call was not answered as asked, such as SESSION_EXPIRED or SERVER_BUSY: the code of the error envelope, beside a message meant for people. It is one of a set the contract publishes and may grow. It stays English wherever it is shown, because it is the string an integrator quotes to support. From Server 1.24.0 the Audit Log keeps it with the call it answered, and shows it after the HTTP status (GET /v1/certificates/info 401 SESSION_EXPIRED), since one status can stand for several codes; the message and the details are not kept, because the details can echo what the client sent. A call answered without an error envelope has none. Not the reason behind a Workstation Refusal, which the operator is told and the integrator is not, and not an error in the Workstation Report, which the machine's software logged.

Signing Activity (Atividade de assinatura)

The platform's count of what holders' keys signed and the platform answered (Server 1.17.0), kept in two units that are never added together: documents signed, Signing Operations that completed, and digests signed by Hash Signing calls that succeeded, a Vault Certificate's included. Signed means answered to the Client Application: a failed or stranded run is not activity. Failures are counted beside it, never inside it. It names no holder: who signed is the Audit Log's to answer. A Test Signature is a real signature but is counted apart, so that proving a deployment works never reads as anybody using it. It is attributed to the Client Application that asked and to the Workstation, or the Certificate Vault, that signed, and counted from the installation onward, not only for as long as the Audit Log keeps its rows. It is settled rather than live: a background fold reads it off the Audit Log some minutes behind, so a figure may trail the Audit Log but never contradicts it. The Dashboard shows it. Not a Signature Allowance charge, which counts signing calls.

Workstation Report (Relatório da Estação de Trabalho)

What a Workstation last told the Server about its own condition (Server 1.20.0, Workstation 1.8.0), so that support can see a machine's trouble without being at it and an administrator can see the same trouble across the fleet. Six kinds: its failed readers left failed; each token it sees, by vendor, model and serial, with how close its PIN is to locking; the middleware it looks through, with versions; the errors the Workstation Service and the Tray App logged; facts about the machine support asks for, such as the PKI Licence it holds and the switches it runs with; and, from Workstation 1.10.0 and Server 1.23.0, its console: the Console Account, whether that session is locked, whether a Tray App runs in the Console Session and which version, and how many other logon sessions have one, without naming their accounts. The machine tells it unasked, whenever it connects and whenever it changes: the Server keeps what it heard last, never asks for it, and a machine that is offline keeps its last report. The Workstations screen, the Dashboard and the Workstation Reports screen show it. It is not the Audit Log, which records who did what, and not the machine's own log, which stays on the machine. A deployment may turn it off on a machine (WorkstationReport:Enabled), which then reports only that it does not report and reads Not reported, so that silence is never read as a healthy machine.

Workstation Refusal (Recusa da Estação de Trabalho)

A holder's call that a Workstation did not complete: a Signing Authorization it refused, or the PIN prompt for a Signing Session's creation that it could not show, that lapsed, or whose PIN did not match. The Audit Log records each one with its reason and, where no Tray App could be reached, why not: from Server 1.22.0 with Workstation 1.9.0 for a Signing Authorization, and from Server 1.23.0 with Workstation 1.10.0 for a creation's prompt. Two are somebody's choice, the holder declining or the Client Application giving up the wait, and are shown but are not a problem with the machine; so is a call the holder authorized after its Signing Session had ended. Every other one is, a PIN that did not match included, since a few of those in a row lock a token. From Server 1.23.0 the Workstations screen counts each machine's problem refusals of the last 24 hours, N refusals (24h), and its Events tab says each one in words, with what to ask the holder. Not an error in the Workstation Report, which the machine's software logged whether or not anybody was asking, and not the refusal the Client Application receives, which says less: the integrator is told the PIN was not available, and the operator is told why.

Server log (Log do Servidor)

The Server's own account of what it was doing, one line per event with a level, a category and a correlation id that also appears on every HTTP response and ties a line to its Audit Log rows. The console is the record; a rolling file under the temporary directory feeds the admin console's Server log screen, and Application Insights is the retained copy when configured. Log lines, Audit Log rows, certificate verdicts and the API's error.message stay English permanently, whatever language a screen is read in.