Workstation configuration

Every setting the Workstation Service takes, and how a fleet install supplies it. The Server's settings are on Server configuration; the two hosts share no configuration. The Tray App has no configuration file at all (see the last section). This page describes Workstation 1.10.0.

Every value here has a default, and most fleet machines change none of it. Six values travel by registry, five of them from the MSI (which Group Policy may override) and one from Group Policy only; the rest live in the settings file the MSI installs beside the binaries.

How a value reaches a machine

The last one to set a key wins:

	Source	What supplies it
1	appsettings.json beside the binaries	Installed by the MSI under Program Files. Nothing in the service ever rewrites it.
2	appsettings.Development.json, user secrets	A developer's console run only. The MSI does not install this file.
3	HKLM\Software\TrustBridge, the preference	The MSI, from SERVER_URL, INSTALLER_KEY, INSERTION_PROMPT, RESTART_FAILED_READERS and WORKSTATION_REPORT. A repair or an elevated hand writes the same values to the same place.
4	Environment variables, __ for :	A console run or a service wrapper. Not how a fleet install works.
5	Command-line arguments	A console run only.
6	HKLM\Software\Policies\TrustBridge, the policy	Group Policy, through the shipped ADMX template. Only the policy engine may write there.

Six values travel by registry. In either location, ServerUrl becomes Server:Url and InstallerKey becomes Server:InstallerKey. ServerUpdates becomes ServerUpdates:Enabled and is read at the policy location only: no MSI property writes it, and a ServerUpdates put under HKLM\Software\TrustBridge by hand is not read. Three switches are read in either location, the policy beating the preference the MSI wrote: InsertionPrompt becomes Tray:InsertionPrompt, RestartFailedReaders becomes Certificates:RestartFailedReaders, and WorkstationReport becomes WorkstationReport:Enabled. A string value published in the wrong registry type (a REG_DWORD where a string was meant) refuses the start, naming the location. The four switches are not guessed at either, but a machine that cannot read one can still sign, so a ServerUpdates that is not a REG_DWORD of 0 or 1 reads as off and is logged at Error (see its entry); the other three are read the same way, with one more form allowed, the string "0" or "1" the MSI writes. Both registry locations are read once, at start: a GPO refresh takes effect at the next service start.

The PKI licence is not one of them. The Server supplies it in the handshake; see Certificates:Validation:License.

There is no secret an install gives a machine to join with. A machine mints its own Workstation Key, announces itself and waits to be admitted by an Administrator. Nothing on this page is pushed by the Server. What the Server does send a machine is its PKI licence, its Trusted CA set and, when an Administrator offers one, a Workstation Release; none of those changes a key here.

Value shapes are the Server's: : in a file and __ in the environment, durations as [d.]hh:mm:ss with the twenty-four-days trap, sizes as plain integers.

Reaching the Server

{
  "Server": {
    "Url": "https://trustbridge.example.com",
    "InstallerKey": "MIGHAgEAMBMGByqGSM49…",
    "InitialReconnectDelay": "00:00:01",
    "MaxReconnectDelay": "00:01:00"
  }
}

Server:Url

Default unset · Fleet install the MSI writes SERVER_URL to HKLM\Software\TrustBridge\ServerUrl; Group Policy overrides it at HKLM\Software\Policies\TrustBridge\ServerUrl · Bad value refuses the start

Where this machine's Server is. Required, and it must be an absolute URI. The MSI refuses an empty or scheme-less value first, at its launch condition; the service's start-time check is the backstop. The Tray App shows this URL and can never set it: whoever writes it decides where the machine asks to be admitted, so the write stays behind an elevation boundary. What the Tray App can do (since Workstation 1.6.0) is open that boundary's door: its Change Server… button starts the installed package's maintenance screen, where the repair that re-points the machine happens (Repairing and re-pointing). It offers that only where the URL came from the preference, and reads (set by Group Policy) beside one that came from the policy.

Server:InstallerKey

Default the product's own key · Fleet install the MSI writes INSTALLER_KEY to HKLM\Software\TrustBridge\InstallerKey, only on a deployment that minted one · Bad value refuses the start

The Installer Key this machine signs its admission request with, besides its own: base64 DER PKCS#8, ECDSA P-256. It shows the request came from the genuine product and is not authentication of anything; every copy of TrustBridge holds the product's private half. A deployment that wants a key of its own configures the public half on the Server under Admission:InstallerKeys and delivers the private half here. Set it on the machines before the Server stops trusting the old key. Not a secret. Deliberately not on the ADMX template.

Server:InitialReconnectDelay and Server:MaxReconnectDelay

Default 1 s and 1 min · Fleet install never touched · Bad value non-positive, or a ceiling below the floor, refuses the start

Where the reconnect backoff starts after the channel drops, and the ceiling it climbs to. A machine that cannot reach its Server retries at this cadence indefinitely. Two failures are logged at Error so they can be told from a blip: the Server answered 401 on the channel (admission withdrawn or revoked, or the machine removed from the fleet, after which it asks for admission again as a new machine), and the Server refused the admission request (revoked, untrusted Installer Key, too many requests from the address, or a full queue; the log names all four). A revoked machine stays refused for as long as the Server keeps its row: it rejoins only as a new machine, with a new Workstation Key or after an Administrator removes it. Waiting to be admitted is not a failure and is logged once at Information.

Keep-alive

Not a setting, but it decides how soon a machine that vanished reads offline. The service pings its Server every 5 s when it has sent nothing else, and gives the Server up after three of the pings the Server says it sends (15 s). The Server, for its part, hangs up on a machine it has heard nothing from for Workstations:ClientTimeout (30 s by default). Every release from 1.2.0 on pings every 5 s, so once the whole fleet is on 1.2.0 or newer that Server setting can be lowered to 15 s; see Server configuration.

Updates from the Server

{
  "ServerUpdates": {
    "Enabled": true
  }
}

ServerUpdates:Enabled

Default true · Fleet install Group Policy only, at HKLM\Software\Policies\TrustBridge\ServerUpdates: a REG_DWORD, 0 for off and 1 for on, which the shipped Take updates from the TrustBridge Server policy writes when it is disabled or enabled · Bad value at the policy, anything but a REG_DWORD of 0 or 1 reads as off and is logged at Error; in a settings file, refuses the start

Whether this machine takes the Workstation Releases its Server offers it. On unless a policy turns it off, including on a fleet whose first install came by Group Policy. There is no MSI property and no preference value for it: a fleet that wants the channel off has Group Policy.

Off, the machine downloads and installs nothing, whatever its Server offers: it never waits out the random delay, never asks for a package, and never starts msiexec (Server-delivered updates is what on means). The start-up log says so once. The machine tells its Server in every handshake that it is off, the Server offers it nothing, and the Workstations screen reads it as Updates disabled by policy rather than as behind. It still reports how its last Server-delivered update ended.

A policy value it cannot read turns it off rather than refusing the start. A REG_SZ of "0", say, which a Group Policy Preferences registry item writes more readily than the ADMX's REG_DWORD, leaves the machine signing and taking no release, with an Error line naming the location. Refusing the start would take signing down across a fleet over a switch that governs only updates.

Read once, at start, like every registry value.

The Workstation Report

{
  "WorkstationReport": {
    "Enabled": true
  }
}

WorkstationReport:Enabled

Default true · Fleet install the MSI writes WORKSTATION_REPORT to HKLM\Software\TrustBridge\WorkstationReport (0 off, 1 on; unset writes nothing on a first install, which is on, and keeps the machine's own value on an upgrade or repair); Group Policy overrides it at HKLM\Software\Policies\TrustBridge\WorkstationReport, a REG_DWORD the shipped Report this machine's condition to the TrustBridge Server policy writes · Bad value in the registry, anything but 0 or 1 reads as off and is logged at Error; in a settings file, refuses the start

Whether this machine sends its Server the Workstation Report (Workstation 1.8.0): its condition, which the Server's fleet screen, Dashboard and Workstation Reports screen show to support. It carries the PKI licence the machine holds and its .NET runtime, its switches, the token middleware it looked through (each with its path, file version and whether it loaded), its tokens (vendor, model, serial, and how close each PIN is to locking), the smart-card readers Windows left failed, and the Error and Critical lines the service and the Tray App logged, grouped by source, logger category and message template with a count.

From Workstation 1.10.0 it also carries the console: the Windows account signed in at the console session, the Console Account (its SID, and its DOMAIN\user where that resolves), or nobody; whether that session is locked; whether a Tray App is attached there, and its version; and how many other sessions have a Tray App attached, without their accounts. The service reads the account and the lock itself, so they are reported while no Tray runs. The Workstations screen shows it in its Console Account column from Server 1.23.0; an earlier Server ignores it.

On, the machine reports after every handshake and again a few seconds after anything in it changes, a sign-in, a sign-out, a lock or an unlock, a switch of user at the console, and a Tray App attaching or detaching among them. A report never costs the machine its connection, its detection, its signing or its PIN Cache; its own failures are logged at Warning.

Deliver it with Server 1.20.0 or later. A Server from before the report existed answers that it has none and is not asked again, but only from 1.20.0 does the Server take workstation messages up to 1 MB; an earlier one closes the connection of a report past 32 KB, which a machine on Workstation 1.8.0 with many tokens, middleware or errors can send. From Workstation 1.8.1 a machine keeps its reports under 32 KB until its Server has taken one. See Which Server a release needs.

Off, nothing of the machine's condition leaves it, the Console Account and the rest of the console included. It still reports after every handshake, so that its silence is never read as a healthy machine, but the report says only that reporting is off. The Server then forgets everything the machine reported before, and the fleet screen shows it as Not reported. Signing, certificate detection and the PIN Cache are unaffected either way. From the Workstation 1.10.0 templates, the explanation of the Report this machine's condition to the TrustBridge Server policy names the account signed in at the console among what the report carries, in both languages.

Unreadable reads as off, and the start goes on, as an unreadable ServerUpdates policy does: off is the reading that sends nothing. The start-up log says which source supplied the value. Read once, at start: a Service that starts with it back on sends its full report straight after its handshake.

Certificate detection

{
  "Certificates": {
    "SweepInterval": "00:01:00",
    "ValidationInterval": "01:00:00",
    "ChangeDebounce": "00:00:02",
    "RestartFailedReaders": true
  }
}

Key	Default	Meaning
Certificates:SweepInterval	1 min	The always-on reconciliation sweep: an enumerate-and-diff of every store, covering a missed change trigger or a token that never shows up as a smart card. Non-positive refuses the start.
Certificates:ValidationInterval	1 h	How often every certificate present is fully validated again, so a revocation, an expiry or a lapsed grace window surfaces within one interval. Non-positive refuses the start.
Certificates:ChangeDebounce	2 s	How long the pipeline waits after a change signal before enumerating, so a card arrival coalesces and the middleware has time to make the certificates readable. Outside zero to 5 minutes refuses the start. Undershooting costs a whole sweep; overshooting costs a second of latency.

Certificates:RestartFailedReaders

Default true · Fleet install the MSI writes RESTART_FAILED_READERS to HKLM\Software\TrustBridge\RestartFailedReaders (0 off, 1 on; unset writes nothing on a first install, which is on, and keeps the machine's own value on an upgrade or repair); Group Policy overrides it at HKLM\Software\Policies\TrustBridge\RestartFailedReaders, a REG_DWORD the shipped Restart a smart-card reader Windows could not start policy writes · Bad value in the registry, anything but 0 or 1 reads as off and is logged at Error; in a settings file, refuses the start

Whether the service restarts a failed reader (Workstation 1.8.0): a smart-card reader Windows could not start, so no token in it can be seen. Some USB tokens are their own reader, and Windows' inbox driver sometimes leaves that reader in problem code 10 when the token is plugged in. On, the service restarts such a reader by itself, up to three times per plugging-in, and only a USB reader in problem code 10. Only unplugging the reader earns it a fresh set of tries. Every restart and its outcome is one line in the service's log. It never elevates and never restarts the machine: a restart Windows says needs a reboot counts as a failure.

While it tries, the Tray App's Tokens tab says Windows could not start a smart-card reader. TrustBridge is restarting it (attempt 1 of 3). A reader still failed after the tries, or any failed reader while the restart is off, gets A smart-card reader is plugged in, but Windows could not start it. Unplug it and plug it back in.

Off, nothing is restarted: the Tokens tab asks for the replug at once, which is what every machine did before the restart existed, and the log line that names the failed reader says the restart is turned off. A deployment whose policy forbids software changing device state turns it off without a release.

Only a machine that looks for A3 tokens reads it. With Certificates:Pkcs11:Modules set empty, or with none of the shipped middlewares installed, the service lists no reader device and restarts nothing, whatever this says.

Unreadable reads as off, and the start goes on, as an unreadable ServerUpdates policy does: off is the replug a holder did before, and uncertainty must never be what changes a device. The start-up log says which source supplied the value. Read once, at start.

The certificate stores

{
  "Certificates": {
    "WindowsStore": { "Enabled": true },
    "Pkcs11": { "Modules": "C:\\Windows\\System32\\eTPKCS11.dll;C:\\Vendors\\uncommon-p11.dll" }
  }
}

What the readers announce. A certificate is a signing identity when it has a private key and a readable ICP-Brasil holder: an e-CPF, or an e-CNPJ with its holder's CPF and its Company (alphanumeric CNPJs included). Everything else is skipped. An e-CNPJ is announced, with its Company, only to a Server whose handshake says it takes them (Server 1.13.0 and later), and never as its holder's e-CPF. Against an older Server the Tray App lists the e-CNPJ as not announced, with the reason. The Tray App's certificate list and detail name the Company, and the PIN prompt for a Company's session names the Company being signed for.

Certificates:WindowsStore:Enabled

Default true · Fleet install an administrator's choice · Bad value refuses the start

Whether the machine-wide Windows certificate store (LocalMachine\My) is read for A1 certificates. On, an A1 installed there enumerates, validates and announces like any other certificate on the machine. The store's change notification is held open so an import announces within ChangeDebounce. Off, nothing on the machine opens that store. Read once at start.

An A1 Certificate signs once an A1 PIN is set for it on that machine. Somebody at the machine's console sets one at the Tray App (Set A1 PIN…, then Change A1 PIN…, which asks for the current one); a newly detected A1 with none prompts the holder once to set one. From then on a client application's PIN is checked against that A1 PIN the way a token's PIN is checked against the PIN Cache, and the service signs with the certificate's key with nobody at the machine. Until one is set, the certificate announces and is listed, and sessions over it end PIN_NOT_AVAILABLE.

The service never keeps the A1 PIN itself, only a PBKDF2 verifier, under C:\ProgramData\TrustBridge\ with the PIN Cache's permissions. A wrong current A1 PIN counts toward Tray:MaxConsecutivePinFailures. An A1 PIN is deleted when its certificate has been gone from the store for two passes in a row, and at once if a token turns up holding the same certificate. An upgrade keeps it; a true uninstall deletes it. Nothing about this is configured: the switch controls whether the store is read at all, and the A1 PIN is per certificate, per machine, set by whoever is at the console first.

Certificates:Pkcs11:Modules

Default unset, meaning the shipped vendor list · Fleet install never touched on a machine with common middleware · Bad value a module that will not load is that store failing in the log, not a refused start

The PKCS#11 vendor modules A3 tokens are read through, as one semicolon-separated string of absolute paths. Three states:

• Unset is the shipped default list: SafeNet Authentication Client, SafeSign IC, Watchdata PROTON, Feitian ePass2003, Idemia AWP and Thales IDPrime, at the paths those vendors install to, probed by file existence. Common fleets get token detection with zero configuration.
• Set is exactly what is listed, wholesale; nothing is probed and no default is kept. A listed module that is missing, of the wrong architecture or not a PKCS#11 module counts as that store failing, with the reason in the log. This is how an uncommon middleware is added, at the price of also listing the common ones the machine needs.
• Set empty turns A3 detection off. From an environment variable, off is Certificates__Pkcs11__Modules=";", because a variable that does not exist reads as unset.

Each module is its own store and they fail alone: one failing middleware costs only that vendor's certificates, which degrade to STALE over the grace window. Enumeration never involves a PIN and spends nothing on a token's retry counter. Read once at start.

The Tray App's Tokens tab is where to check the result. It shows one card per token the last detection pass saw (label, serial, model, the middleware that read it, whether a PIN is stored, the certificates on it), the middleware the service looked through and any that failed, and a line naming any reader holding a card no installed middleware reads, or a card that does not respond. From Workstation 1.8.0 it also says when Windows could not start a smart-card reader (Certificates:RestartFailedReaders).

Certificate validation and the PKI SDK licence

The same section name and the same policy the Server reads. Four things are different on a workstation, each called out below.

{
  "Certificates": {
    "Validation": {
      "UseIcpBrasil": true,
      "UseMachineRootStore": false,
      "UseLacunaTestPki": false,
      "UseServerTrustedCas": true,
      "TrustedRootPaths": ["C:\\ProgramData\\TrustBridge\\anchors\\your-root.pem"],
      "RevocationGraceWindow": "1.00:00:00",
      "RevocationTimeout": "00:00:05",
      "CheckTimeout": "00:00:30"
    }
  }
}

Certificates:Validation:License

Default unset · Fleet install never set on the machine: the Server shares its own licence with every Admitted machine on each handshake · Bad value a stale or garbled licence is a Critical line, never a refused start

Required on every machine, which is the first difference from the Server, and the Server supplies it. Here the SDK is what reads a certificate at all, so without a licence every certificate on the machine reports UNTRUSTED and the machine signs nothing. An Admitted machine is handed its Server's own Certificates:Validation:License in the answer to every handshake and applies it before it announces a single certificate. It is held in memory only, never written to the machine's disk, and replaces any value set here.

Nothing a fleet install writes supplies one, and that is the design. No MSI property and no Group Policy value carries a licence. Renewing it is an edit and a restart on the Server, which every connected machine picks up as it reconnects, and an offline machine at its next handshake. A machine revoked or sent back to Pending keeps the licence it was given until its service restarts.

What the machine says. With nothing set here, the start-up line is Information, awaiting the Server, which is the ordinary start of an installed machine. A licence the Server sent that the SDK refuses is Critical once per distinct value, and so is a Server that accepts the handshake but sends none. The Tray App shows a line above its certificate list saying why the machine is unlicensed: awaiting the Server (Pending, never admitted, or offline since start), the Server's licence was refused, the Server sent none, or a licence this machine could not apply.

A value set here, in a settings file or as Certificates__Validation__License, is for a developer's console run only: the base64 licence on one line, which the Server's replaces as soon as it answers.

The anchor sources

Key	Default	Meaning
Certificates:Validation:UseIcpBrasil	true	The ICP-Brasil roots the SDK carries. Turning it off is a trust decision.
Certificates:Validation:UseMachineRootStore	false	The second difference: here it does something. Trusts every public CA in the Windows root program, a far broader set than ICP-Brasil.
Certificates:Validation:UseLacunaTestPki	false	Also trust the Lacuna Test PKI. Development only: Lacuna publishes the matching private keys. The service says so at Critical every start.

Certificates:Validation:UseServerTrustedCas

Default true · Fleet install the settings file the MSI installs (this key has no registry row, so no GPO reaches it) · Bad value refuses the start

The third difference: this key does something only on a machine. Whether the machine composes the Server's Trusted CAs into its own anchor set. On, the machine asks the Server for the set after every handshake and re-asks when the Server says it changed, so a CA an Administrator adds on the Trusted CAs screen reaches this machine's verdicts in seconds. The last set received is cached locally and stays in force while the Server is unreachable: a Server that does not answer has not said anything, and only a Server answering, including answering no Trusted CAs, replaces what the machine holds.

While this machine holds a non-empty set from the Server, TrustedRootPaths is disregarded entirely, and the service says so at Critical, naming the dropped paths. A control that only ever added trust could never withdraw it.

Off, the machine never asks and validates against its own configuration only, TrustedRootPaths included: the posture for a fleet with its own change-controlled anchor pipeline. Turning it off is a settings-file change on each machine, best made before the machine first connects to its Server. Either way the machine reports which posture it is in on every connect, and the fleet screen shows it per machine.

Certificates:Validation:TrustedRootPaths

Default empty · Fleet install an administrator's choice, deployed with the anchor files · Bad value an unreadable file is a Critical line, not a refused start

How a private CA is added from a file on this machine. No longer the last word: the supported way to trust a private CA fleet-wide is a Trusted CA added once on the Server. This key still decides the whole answer on a machine whose UseServerTrustedCas is off, one that has never heard from a Server, or one whose Server has no Trusted CAs.

The fourth difference: these must be absolute paths. Anyone who can add a file here can make a certificate of their own validate as ACTIVE, so the files belong under C:\ProgramData\TrustBridge\anchors\, whose ACL the installer owns. With no anchors at all, the service still starts and every certificate reads UNTRUSTED, with a Critical line naming the settings (not the licence); anchor files carrying only intermediates get a second, different line.

The revocation bounds

Key	Default	Meaning
Certificates:Validation:RevocationGraceWindow	24 h (1.00:00:00)	How long the last successful revocation check keeps a certificate ACTIVE while its CA cannot be reached; past it the certificate goes STALE. Widening this is how long a revoked certificate keeps signing while its CA is unreachable. Negative refuses the start.
Certificates:Validation:RevocationTimeout	5 s	How long one CRL download or issuer fetch may take before the CA counts as unreachable. Non-positive refuses the start.
Certificates:Validation:CheckTimeout	30 s	The outer bound on one certificate's whole check. Validation passes serialize on the machine, so an unbounded check stalls every certificate behind it. Zero waits indefinitely.

While the Server and this machine are on different versions

The handshake is where this machine gets its PKI licence and its Trusted CA set, so a version mismatch decides whether the machine can read a certificate at all. Workstation 1.6.0 introduced protocol 6, which adds the Signing Authorization: for a Client Application with Per-Transaction PIN on, the Server asks this machine's Tray for the PIN on every signing call. Protocol 5 before it is the one on which the Server stopped sending any machine the client application's PIN: it challenges the machine with a nonce, and the machine answers with a PIN Proof over the PIN it has cached, or over an A1 PIN's verifier, for the Server to check. A Server accepts its own protocol and the one before it.

• This machine ahead of its Server: it does not connect at all. A Server before 1.15.0 refuses the handshake (Protocol version 6 is newer than this server's supported window (4–5); update the Server first). This service logs that verdict, disconnects and retries with backoff. With no Server to hand it a licence, every certificate on this machine reads UNTRUSTED, and it cannot sign until the Server is upgraded.
• A Server ahead of a machine: it connects, and serves every session but a per-transaction one. A Server 1.15.0 or later lets a machine on Workstation 1.5.0 (protocol 5) handshake and serve every session as before, but never chooses it for a session whose Client Application has Per-Transaction PIN on. A machine on 1.4.x or older is refused with update required.

Workstation 1.7.0 to 1.10.0 keep protocol 6, so the above holds for them unchanged, with one more condition from 1.8.0 on: deliver it with Server 1.20.0 or later, the first Server that takes its Workstation Report; an earlier one closes the connection of a 1.8.0 report past 32 KB. What 1.9.0 and 1.10.0 add rides protocol 6 as optional fields an earlier Server ignores, and 1.10.0's console shows on the Workstations screen from Server 1.23.0.

So the rule is the Server first, then the fleet: see Which Server a release needs. Cached PINs, A1 PINs and the machine's admission carry over the upgrade as they stand. Workstation 1.7.0 added Tray:InsertionPrompt, and 1.8.0 added WorkstationReport:Enabled and Certificates:RestartFailedReaders, all on by default; 1.8.1 to 1.10.0 added no key, and no key was renamed or removed.

The Service–Tray channel

The named-pipe channel between the service and the Tray App. Its ACL admits interactive users and that is the whole of its access control. A fleet install touches none of this but Tray:InsertionPrompt, which an MSI property or a Group Policy turns off.

{
  "Tray": {
    "PipeName": "TrustBridge.WorkstationService",
    "PromptTimeout": "00:01:30",
    "InsertionPrompt": true,
    "MaxConsecutivePinFailures": 3,
    "PinFailureCooldown": "00:05:00",
    "LogBufferSize": 500
  }
}

Key	Default	Meaning
Tray:PipeName	TrustBridge.WorkstationService	The pipe the service listens on. Configurable only so a developer can run a second instance; the Tray App dials the well-known name and has no setting of its own. Blank refuses the start.
Tray:PromptTimeout	90 s	The machine's own bound on a session's PIN prompt. The Server's Sessions:PinPromptTimeout (60 s) is what normally ends a prompt: when it runs out the Server takes the prompt down on the machine. This looser window is what ends a prompt the Server can no longer reach, such as one on a machine that lost its connection, and it also bounds how long an entry waits for the Server's verdict on its proof. Keep it longer than the Server's. A per-transaction prompt is bounded by the window the Server sends with it instead (Signing:AuthorizationTimeout). Non-positive refuses the start.
Tray:MaxConsecutivePinFailures	3	How many PINs may be rejected in a row for one certificate before entries for it are refused without being checked: a token rejecting them, or for an A1 Certificate, wrong A1 PINs (including a wrong current A1 PIN when changing one). Bounds a process asking thousands of times, not a person: a user can still lock their own token by mistyping. Zero refuses the start.
Tray:PinFailureCooldown	5 min	How long entries for a certificate are refused once that limit is reached. Not a token state; no PUK is involved, and it clears on its own, for a token and an A1 alike.
Tray:LogBufferSize	500	How many recent log entries the service keeps for the Tray's Log tab. Memory only.

Tray:InsertionPrompt

Default true · Fleet install the MSI writes INSERTION_PROMPT to HKLM\Software\TrustBridge\InsertionPrompt (0 off, 1 on; unset writes nothing on a first install, which is on, and keeps the machine's own value on an upgrade or repair); Group Policy overrides it at HKLM\Software\Policies\TrustBridge\InsertionPrompt, a REG_DWORD the shipped Ask for a token's PIN when it is inserted policy writes · Bad value in the registry, anything but 0 or 1 reads as off and is logged at Error; in a settings file, refuses the start

Whether a token going in opens an Insertion Prompt (Workstation 1.7.0): the PIN window, opened by itself at an unlocked console for a token whose PIN is not cached, so the signatures that follow need no prompt. What the token accepts is kept in the PIN Cache for every certificate on it. The window, headed Enter the PIN of the token you inserted, names the token, its reader and, for each certificate on it, the holder, or for an e-CNPJ the Company and the CPF of the person who holds it. The holder types the PIN, chooses Not now, or lets the window close at the end of the 90-second countdown every prompt has; a wrong PIN is typed again in the same window, under the same limit on rejected PINs as every PIN entry.

It is offered once per insertion, and only for a token that lists at least one ACTIVE certificate, is not PIN-locked and whose PIN is not cached; never for an A1 Certificate, for the cards already in when the Tray App attaches, or for a token that lists nothing without a login. It never opens behind the lock screen: a token inserted while the console is locked is offered at the unlock, if it is still in and its PIN still not cached. A session's PIN prompt or a per-transaction prompt arriving over it takes the screen, and the Insertion Prompt comes back once the screen is idle. It closes on its own if the token is pulled out or its PIN gets cached another way. It never reaches the Server, and it never authorizes a per-transaction signing call, which still asks at the Tray App every time.

Deliver Workstation 1.8.1 or later where it is on. On 1.7.0 and 1.8.0, a PIN prompt closing (an Insertion Prompt answered, declined or timed out among them) could end a Tray App whose window had not been opened since sign-in, leaving the session with no Tray until sign-out, so a per-transaction call there was refused NO_TRAY. From 1.8.1 the Tray App ends only when asked to: its menu's Exit, or its window closed while it has no icon to come back through.

Off, the token balloon is exactly what it was before the prompt existed: the service offers no Insertion Prompt and tells the Tray App so when it attaches, and the Tray App goes on inviting the holder to enter the PIN from a notification. A desktop where the window is unwelcome turns it off without a release. On, the balloon is gone for every token that goes in, not only for the ones the window opens for: a token the service then offers no prompt for (its PIN locked, a login it demands before it lists anything, no certificate on it that can sign yet) is announced by neither. Its certificates still reach the Tray App's list, and Enter PIN… there still caches its PIN.

Unreadable reads as off, and the start goes on, as an unreadable ServerUpdates policy does: off is the balloon every machine had before. The start-up log says which source supplied the value, and names an unreadable one at Error, or at Warning, naming the source that outranks it, where a readable policy supplies the key instead. Read once, at start.

The per-transaction prompt

For a Client Application with Per-Transaction PIN on, every signing call under a session bound to this machine opens a prompt on the Tray App in the console session, headed A signing transaction needs your PIN. It names the Client Application asking and what it will sign: the number of hashes, or the number of documents and the first five by name (each cut to one line of at most 80 characters, then and N more), and, for an e-CNPJ, on whose behalf. The holder types the token's PIN or the A1 PIN and chooses Authorize or Decline; a PIN the token refuses is typed again in the same window.

Nothing on this page configures it. A transaction prompt is never shown beside another prompt: whichever arrives second waits its turn within its own window. Past sixteen waiting or showing at once, a new one is refused unshown. The accepted PIN is held in memory for that call only, and the prompt is answered NO_TRAY where no Tray App at the console can show it, which the client sees as PIN_NOT_AVAILABLE (no Tray at the console).

From Workstation 1.9.0 the machine says why, beside its NO_TRAY: a Tray in a session that is not the console's (Remote Desktop, or a switched console), no Tray App attached anywhere, a console Tray too old to show a transaction, an install starting, a console Tray not reading, the Tray detaching while the prompt was up, or the service stopping. From 1.10.0 a session's PIN prompt the machine could not show says why too, with one reason of its own: every certificate it could offer is an A1 Certificate with no A1 PIN set. The client's refusal does not change; the Audit Log records the reason from Server 1.22.0, and the admin console's Workstations screen says it in words from Server 1.23.0.

The PIN Cache

Local and administrator-owned. The Server pushes nothing here, no Tray or API call can change it. One line at every start says which posture the machine is in.

The PIN never comes from the Server. A PIN reaches the cache only from the holder at this machine's Tray App, after the token has accepted it. At session creation the Server sends a nonce, and the machine answers with a proof keyed by the cached PIN; the Server decides whether it matched the client application's PIN and tells the machine when a session bound through it.

{
  "PinCache": {
    "SurviveRestart": false,
    "Ttl": "08:00:00",
    "SweepInterval": "00:05:00",
    "StorePath": "C:\\ProgramData\\TrustBridge\\pin-cache.dat",
    "KeyRingPath": "C:\\ProgramData\\TrustBridge\\keys"
  }
}

PinCache:SurviveRestart

Default false · Fleet install an administrator's choice, and a documented deviation

Whether cached PINs survive a service restart or a reboot, including the restart a Server-delivered update causes. Off, the entries are encrypted under a key ring that exists only in the running process, so stopping the service destroys the means to read them. On, the key ring is persisted under KeyRingPath protected with DPAPI machine scope, and the ciphertext goes to StorePath in a file whose ACL admits SYSTEM and Administrators only. Either way the TTL is sealed inside the ciphertext, so a restart cannot reset it and editing the file cannot extend it.

Turning it on is a documented deviation from the ICP-Brasil middleware requirement's termination trigger (REQUISITO-MW II.27), which TrustBridge treats as a guideline because it sits above the vendor's middleware. A machine running with it on says so at Warning on every start.

A1 PINs are not part of the PIN Cache and are not affected by this switch: they are kept on disk until the certificate leaves the machine or the package is uninstalled.

The rest of the PIN Cache

Key	Default	Meaning
PinCache:Ttl	8 h	How long an entry lives without being used. Sliding: each session that binds through it refreshes the expiry, so a daily-active user is never re-prompted. A PIN typed for a per-transaction call never enters the cache and slides no entry. Non-positive refuses the start.
PinCache:SweepInterval	5 min	How often idle entries are swept out of memory. Nothing can obtain an expired PIN regardless.
PinCache:StorePath	%ProgramData%\TrustBridge\pin-cache.dat	Where the ciphertext is written. Never written while survival is off.
PinCache:KeyRingPath	%ProgramData%\TrustBridge\keys	Where the persisted key ring lives. Unused while survival is off.

Logging

The framework's own configuration, in the same shape as the Server's. The shipped file sets Default to Information and quietens two SignalR client categories to Warning. Two lines an administrator should recognise at the default level: which PIN Cache posture the machine is in (every start), and that the fake-token development harness is active (every start, on any machine with a FakeTokens section). A FakeTokens section does not belong on a machine anybody signs from: it makes fabricated certificates validate as ACTIVE.

The Tray App reads no configuration file

There is no appsettings.json for the Tray App. Its options are constructed in code: the pipe name and protocol version it dials, its reconnect delay and its prompt-expiry grace are compiled in, and the language it shows comes from the signed-in user's own Windows UI culture rather than from a setting. What shapes the channel between the two is the Tray section above, which the service reads. Its one command-line switch, --background (Workstation 1.9.0), is the autostart entry's: started with it, the Tray shows only its icon and exits silently beside a Tray in the session that answers; started without it, from the Start menu's TrustBridge shortcut or the executable, it opens its window (see Workstation installation).

It writes no log file either, deliberately: a prompt's log line names a CPF, and a file in every user's profile is somewhere an uninstall cannot reach. What the Tray App logs is held in memory and shown on its Log tab beside the service's lines, and leaves the machine only through that tab's Export. Its lines end when the Tray App does, so export before anybody restarts it.