---
title: "Conceitos"
description: "O vocabulário do TrustBridge, definido uma única vez: a plataforma, sessões e Provas de PIN, custódia, empresas, acesso dos administradores, confiança, licenciamento e atualizações, como o console, a API e os logs os usam."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge/concepts"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-13"
---

# Conceitos

O TrustBridge usa um vocabulário pequeno e preciso, e o console administrativo, a API e os logs o
usam da mesma forma. Esta página define cada termo uma única vez. Nos títulos que trazem um termo em
inglês entre parênteses, o termo em português é o que o console administrativo e o Tray App mostram
quando lidos em português do Brasil, e o termo em inglês é o que mostram quando lidos em inglês.

## A plataforma

### TrustBridge

A plataforma como um todo: o Servidor, o Workstation Service e o Tray App. A especificação do
SignSession usa "Trust Bridge" especificamente para o serviço do Windows que monitora os
certificados; nesta documentação, o nome sem qualificação significa a plataforma, e o serviço é
sempre o **Workstation Service**.

### Servidor (*Server*)

A aplicação web central: a API REST do SignSession Contract, o console administrativo, a página
inicial (Landing Page), o canal das estações de trabalho, os downloads das Versões da Estação de
Trabalho e o probe de saúde, todos na mesma porta e diferenciados pelo caminho. Ele guarda o único
banco de dados da plataforma: sessões, operações, o Registro de Certificados, o Cofre de Certificados,
a Trilha de Auditoria, as contas administrativas, os dois chaveiros, as Versões da Estação de Trabalho
e as configurações salvas por um Administrador. Ele também guarda a **licença da PKI** da implantação,
como configuração, e a entrega à frota.

### Workstation Service

O serviço do Windows instalado na máquina do usuário. É o único caminho de acesso aos certificados
dessa máquina e às chaves privadas deles, por meio do middleware PKCS#11 do fabricante e do Lacuna PKI
SDK. Ele se conecta **de saída** ao Servidor por SignalR/WebSockets, de modo que nenhuma porta de
entrada é aberta na máquina. A chave privada de um Certificado de Estação de Trabalho nunca sai da
estação de trabalho. A partir do Workstation 1.4.0, ele também consegue instalar uma **Versão da
Estação de Trabalho** que o Servidor lhe oferece.

### Tray App

O aplicativo de bandeja do Windows que roda na sessão do usuário conectado, na mesma máquina. Ele
mostra o status dos certificados e a lista de certificados, uma aba de tokens com cada token que o
serviço enxerga e os certificados dele, coleta o PIN quando uma Sessão de Assinatura precisa de um,
define e troca um **PIN do Certificado A1**, mostra se a máquina está aguardando admissão ou por que
está sem licença da PKI e tem um painel de diagnóstico com as linhas recentes de log. Ele fala com o
Workstation Service por um named pipe local e nunca com o Servidor.

### Página inicial

A porta de entrada do Servidor em `/` (a *Landing Page*), sem autenticação. Ela diz o que é este Servidor e traz links
para o console administrativo, para a documentação publicada e para a Lacuna Software. Não mostra
nenhum estado da plataforma, porque qualquer pessoa que acesse o Servidor pode lê-la.

### Signer

O Lacuna Signer, o serviço externo de assinatura responsável pelo fluxo dos documentos: ele calcula o
hash a assinar, monta o PDF assinado e o disponibiliza para download. O TrustBridge assina hashes;
nunca monta nem armazena documentos.

## Sessões e assinaturas

### Sessão de Assinatura (*Signing Session*)

A autorização vinculada a um CPF que permite assinar com o certificado de um usuário, opcionalmente em
nome de uma **Empresa**: uma sessão criada com um CPF e um CNPJ só assina com o e-CNPJ dessa Empresa
do qual essa pessoa é a responsável, e uma criada só com o CPF só assina com o e-CPF da pessoa. Há no
máximo uma ativa por CPF, ou por par de CPF e CNPJ; criar uma nova substitui a anterior, então a
sessão do próprio titular e uma sessão para a Empresa dele podem estar ativas ao mesmo tempo. Ela é
identificada por um `sessionId` opaco, que a criação devolve. O CPF vincula a sessão, mas não a
identifica, e nenhuma chamada recupera o id a partir de um CPF.

A sessão é criada quando o PIN informado pela aplicação cliente comprova que quem chama é o titular de
um certificado correspondente:

- para um **Certificado de Estação de Trabalho**, por uma **Prova de PIN** de uma única estação de
  trabalho que confere, feita sobre o PIN em cache ou digitado no Tray App dessa máquina, ou sobre um
  PIN do Certificado A1;
- para um **Certificado do Cofre**, quando o PIN abre a própria chave do certificado.

PINs errados bloqueiam a criação de sessões para o CPF do titular por um tempo, qualquer que seja o
CNPJ pedido.

A partir da criação, ela fica vinculada a esse único certificado e ao seu titular, e toda assinatura
feita com ela é encaminhada somente para lá. Ela expira após uma **janela de ociosidade** que só a
atividade de assinatura prolonga; consultar o status dela nunca a prolonga. Onde a implantação
concedeu uma **Franquia de Assinaturas**, ela também termina depois desse número de chamadas de
assinatura.

Uma sessão vinculada a uma estação de trabalho sobrevive à desconexão da estação (fica inerte enquanto
a máquina está offline) e sobrevive a reinícios do Servidor. Uma sessão vinculada ao cofre **não**
sobrevive a um reinício do Servidor, porque o segredo que abre o certificado só existe em memória;
essas sessões terminam como `Stranded`, e o cliente cria uma nova.

"Sessão", sozinha, sempre significa Sessão de Assinatura. Uma sessão de token PKCS#11, uma sessão de
logon do Windows e a sessão web de login de um administrador são coisas diferentes e sempre aparecem
qualificadas.

### Operação de Assinatura (*Signing Operation*)

O registro, no Servidor, de uma execução de assinatura de um documento dentro de uma Sessão de
Assinatura, criado no envio e conduzido até concluído ou com falha. Uma sessão pode abranger muitas
Operações de Assinatura. O id que o cliente recebe, e com o qual obtém o documento assinado, é o id
do próprio documento no Signer.

### Franquia de Assinaturas (*Signature Allowance*)

Um segundo limite opcional para uma Sessão de Assinatura: quantas **chamadas** de assinatura podem ser
feitas com ela. É concedida na criação, a partir de `Sessions:SignatureAllowance`, fixa durante toda a
vida da sessão e ausente por padrão. Cada chamada gasta uma unidade, qualquer que seja o número de
documentos: um lote de cinquenta gasta uma, e uma chamada cujos documentos falharam todos antes de a
chave ser usada não gasta nenhuma. Uma sessão que esgota a franquia fica **Esgotada** (*Exhausted*).
Uma franquia de 1 torna toda sessão de uso único.

É um limite de política, não uma fronteira de segurança: chamadas simultâneas são autorizadas cada
uma antes que qualquer delas tenha gastado uma unidade. As linhas por assinatura da Trilha de
Auditoria são o registro exato.

### Sessão de console (*Console Session*)

A sessão de logon do Windows ligada ao console físico da máquina. Uma estação de trabalho pode ter
várias sessões de logon ao mesmo tempo (área de trabalho remota, troca rápida de usuário); o pedido de
PIN aparece somente nesta, o PIN só pode ser digitado a partir dela, e o log do Workstation Service só
pode ser lido a partir dela.

### Cache de PIN (*PIN Cache*)

O armazenamento seguro de PINs de token do Workstation Service, indexado por certificado e preenchido
somente pela digitação do PIN no Tray App. Digitar um PIN uma vez cobre todos os certificados do mesmo
token. As entradas expiram após um TTL de ociosidade deslizante e são apagadas quando o titular manda
esquecer, quando a sessão que autorizaram é desativada ou quando o token recusa o PIN, mas não quando
o token é removido. Por padrão o cache fica só em memória e, opcionalmente, pode sobreviver a
reinicializações. Um PIN em cache é aquilo com que a máquina prova quando o Servidor a desafia na
criação de uma sessão, e o que desbloqueia o token quando ela assina; o tempo ocioso de uma entrada é
renovado quando o Servidor avisa a máquina de que uma sessão foi vinculada a ela. Um tempo de vida não
governa o outro. O Cache de PIN trata só de tokens: o PIN de um Certificado A1 é um **PIN do
Certificado A1**, guardado como verificador.

### Prova de PIN

A resposta de uma estação de trabalho ao desafio do Servidor para um certificado na criação de uma
sessão (a *PIN Proof*). O Servidor envia à máquina um nonce novo, e nunca o PIN; a máquina responde com
um HMAC sobre esse nonce, cuja chave é o PIN que ela tem em cache para o certificado, o PIN que o
titular acabou de digitar no Tray App ou o verificador de um PIN do Certificado A1, ou diz que não tem
com o que provar. O Servidor calcula a prova esperada a partir do PIN enviado pela aplicação cliente e
decide se confere; a máquina só fica sabendo o veredito. Assim, o PIN do cliente não passa do Servidor,
e a máquina não descobre nada sobre ele. As provas ficam fora de todo log e da Trilha de Auditoria,
assim como o PIN. Exige o protocolo 5 das estações de trabalho: uma máquina no protocolo 4 nunca é
desafiada.

### Limite de provas com falha

Quantas Provas de PIN que não conferem uma estação de trabalho pode dar para o CPF de um titular (o
*Failed-Proof Budget*), dentro da mesma janela e até o mesmo número do bloqueio por PIN errado do CPF
(`Sessions:MaxPinFailures` e `Sessions:PinFailureWindow`). Toda prova que falha conta, mesmo quando
outra máquina conferiu. Uma máquina que esgotou o limite para um CPF não é desafiada nem recebe pedido
de PIN para esse CPF, e conta como inacessível para esse titular, até que as falhas expirem. Isso é
registrado no log em `Warning` e na auditoria como `pin.proof-budget-spent`. O limite é cobrado só
dessa máquina e não é o bloqueio, mas um PIN errado custa à máquina do próprio titular uma prova com
falha para cada certificado dele que ela tem, então ela pode deixar de ser consultada antes de o
bloqueio entrar em vigor. O Cofre de Certificados tem o mesmo limite para senhas que não abrem nada,
por CPF e com os mesmos números.

## Certificados e custódia

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

Um certificado guardado numa máquina, acessível somente pelo Workstation Service dessa máquina e
registrado no Registro de Certificados. A chave privada dele nunca sai da estação de trabalho, e a
assinatura com ele acontece lá. Um **Certificado A3** (smart card ou token USB) é sempre um
Certificado de Estação de Trabalho. Um **Certificado A1** instalado no repositório do Windows da
máquina também é, e ele pode assinar depois que o titular define um **PIN do Certificado A1** para ele
nessa máquina.

### Certificado do Cofre (*Vault Certificate*)

Um certificado que o próprio Servidor guarda, com chave privada e tudo, importado por um Administrador
como PKCS#12 e mantido no Cofre de Certificados. Ele não pertence a nenhuma máquina e não depende de
nada online para abrir uma sessão ou assinar. A senha que o desbloqueia é fornecida pela aplicação
cliente como o `pin` em cada criação de sessão e nunca é gravada: a plataforma persiste aquilo sem o
qual não consegue assinar, e nada que lhe permita assinar sem ser solicitada.

Esta é, de propósito, a mais conveniente e a mais fraca das duas custódias. Qual custódia um
certificado usa é assunto do operador e do auditor, e não é informado à aplicação cliente. Um
Administrador pode tirar um Certificado do Cofre **de uso** (*Fora de uso*), o que impede que ele abra
sessões e assine, mas mantém o certificado e o histórico dele, ou destruir o material da chave, o que
não pode ser desfeito. Não existe caminho de exportação ou download em nenhum lugar da plataforma.

### Registro de Certificados (*Certificate Registry*)

O mapeamento persistido, no Servidor, de certificado para estação de trabalho: quais certificados
(thumbprint, CPF do titular, o CNPJ da Empresa no caso de um e-CNPJ, e status) estão presentes em
quais Workstation Services conectados. Cada
serviço anuncia seus certificados ao se conectar e a cada inserção ou remoção. O status de um
certificado é o último veredito de validação que a estação de trabalho dele informou, e só `ACTIVE`
pode abrir sessões ou assinar. As entradas refletem o último estado conhecido: os certificados de uma
estação de trabalho desconectada continuam visíveis, marcados como offline e com o horário em que
foram vistos por último. O mesmo certificado pode, legitimamente, estar registrado em várias estações
de trabalho.

### Cofre de Certificados (*Certificate Vault*)

O armazenamento, no Servidor, dos Certificados do Cofre: o que a plataforma guarda, para quem (o CPF
do titular e, no caso de um e-CNPJ, o CNPJ da Empresa), o último veredito de cada um e se está fora de
uso. É a contraparte do Registro de Certificados. Um
certificado pode estar num, no outro ou nos dois.

### Diretório de Certificados e Alvo de Assinatura

A leitura que o Servidor faz dos dois armazenamentos como um só (o *Certificate Directory*): o que pode
assinar por um CPF, ou por um CPF em nome de uma Empresa (com os dois conferindo exatamente), e em que
ordem a plataforma tenta cada opção. Os Certificados do Cofre são
tentados primeiro, depois as estações de trabalho. Um **Alvo de Assinatura** (*Signing Target*) é uma
coisa capaz de assinar, resolvida uma vez por chamada: um certificado, o último veredito que ele
recebeu e a custódia que o guarda. A partir desse ponto, para o restante do Servidor, as duas
custódias são uma coisa só.

### Vereditos dos certificados

Todo certificado tem um de cinco vereditos, e eles ficam em inglês em todas as telas porque também
trafegam no protocolo:

| Veredito | Significado |
|----------|-------------|
| `ACTIVE` | A cadeia chega a uma âncora de confiança, o certificado está dentro do prazo de validade, e a revogação foi verificada e não consta. O único veredito que pode abrir uma sessão ou assinar. |
| `EXPIRED` | Fora do prazo de validade. |
| `REVOKED` | Revogado pela autoridade certificadora. |
| `UNTRUSTED` | A cadeia não chega a nenhuma âncora em que este componente confia. É também o que todo certificado informa enquanto o componente não tem uma **licença da PKI** utilizável: uma licença vencida, ou uma estação de trabalho que o Servidor ainda não licenciou. |
| `STALE` | Nenhuma verificação de revogação bem-sucedida dentro da janela de tolerância; a AC está inacessível há tempo demais. |

### Certificado A3 e Certificado A1

Classes de certificado da ICP-Brasil. A chave privada de um **A3** fica num hardware removível que
executa as assinaturas ele mesmo e nunca entrega a chave; para usá-la é preciso o PIN do titular, e o
hardware conta as tentativas erradas. Um **A1** é um arquivo de software cuja chave privada é um dado,
que circula protegido por senha; depois de instalado, não pede PIN. O mesmo A1 pode estar em várias
máquinas ao mesmo tempo, cada cópia um Certificado de Estação de Trabalho, ou ser importado para o
Cofre de Certificados.

### PIN do Certificado A1 (*A1 PIN*)

Um PIN que o titular define no Tray App para um Certificado A1 numa estação de trabalho, para que o
certificado possa vincular Sessões de Assinatura como um certificado de token: a máquina responde ao
desafio do Servidor com uma Prova de PIN feita sobre ele. O Workstation Service guarda um verificador,
nunca o PIN, por certificado e por máquina, então o mesmo A1 em três máquinas tem três PINs do
Certificado A1. Ele só pode ser definido ou trocado a partir da Sessão de console, e a troca pede o
PIN atual. Ele é apagado quando o certificado sai da máquina e também quando aparece um token com o
mesmo certificado. Enquanto nenhum estiver definido, as sessões sobre esse A1 terminam em
`PIN_NOT_AVAILABLE`. Ele não protege a chave, que continua no repositório do Windows tão utilizável
quanto antes; ele decide quem pode assinar pelo TrustBridge.

### Token e middleware

Um **token** é o hardware removível que guarda chaves A3 e assina com elas: um smart card numa leitora
ou um token USB. O **middleware** é o software do fabricante do token, instalado na máquina; o
TrustBridge nunca fala diretamente com um token, só pelo módulo PKCS#11 de um middleware, e só pelos
módulos que sabe onde encontrar ou que um operador lista. A aba de tokens do Tray App mostra cada token
que o serviço viu, o middleware que o leu e os certificados dele, e indica a leitora que tem um cartão
que nenhum middleware leu.

### e-CPF e e-CNPJ

Os dois tipos de certificado ICP-Brasil que uma pessoa pode ter, cada um na forma A1 ou A3. Um
**e-CPF** é emitido para uma pessoa física e identifica o titular pelo CPF. Um **e-CNPJ** é emitido
para uma **Empresa** e identifica duas partes: a Empresa, pelo CNPJ, e a pessoa física responsável
por ela, pelo CPF. Para o TrustBridge, essa pessoa é quem detém o e-CNPJ, exatamente como num e-CPF: o
cartão, o PIN e a assinatura são dela. Quem tem os dois tem dois certificados que não se substituem,
mesmo quando os dois estão num só token, atrás de um só PIN: uma sessão só para o CPF nunca assina com
o e-CNPJ, e uma sessão para a Empresa nunca assina com o e-CPF.

### Empresa (*Company*) e Responsável

A pessoa jurídica para a qual um e-CNPJ é emitido, identificada pelo **CNPJ**. A Empresa nunca é quem
detém o certificado: ela não tem PIN, e nada é assinado por ela a não ser pela pessoa que o e-CNPJ
identifica. Uma Empresa pode ter vários e-CNPJs, de pessoas diferentes. O console administrativo e o
Tray App chamam essa pessoa de **Responsável**, nunca de *Titular*, porque na ICP-Brasil o titular de
um e-CNPJ é a Empresa.

### CPF

O número de inscrição de pessoa física na Receita Federal, com onze dígitos, dois deles verificadores.
É a chave que vincula uma Sessão de Assinatura a um certificado: sozinho, numa sessão para essa pessoa,
ou com um **CNPJ**, numa sessão em nome de uma Empresa, em que continua sendo o CPF da pessoa. O
TrustBridge confere os dígitos verificadores do CPF que o cliente envia e recusa os onze valores de
dígitos repetidos; nunca consulta a Receita Federal para saber se o CPF foi emitido.

### CNPJ

O número de inscrição de pessoa jurídica na Receita Federal, que identifica a **Empresa** para a qual
um e-CNPJ é emitido. São catorze caracteres, enviados sem pontuação: doze que identificam a Empresa e
dois dígitos verificadores. Os doze podem ter letras maiúsculas além de dígitos (o CNPJ
alfanumérico), e as duas formas são aceitas. O TrustBridge confere os dígitos verificadores do CNPJ
que o cliente envia e recusa o anúncio de uma estação de trabalho cujo CNPJ não confere com o do
certificado anunciado.

## Atores e credenciais

### Aplicação Cliente (*Client Application*)

Um sistema externo que se integra pelo SignSession Contract, cadastrado no console administrativo.
Ela tem uma ou mais **chaves de API**, apresentadas no header `X-API-Key`, e qualquer uma delas a
autentica para toda a superfície do contrato. As Sessões de Assinatura não ficam vinculadas à
Aplicação Cliente que as criou: qualquer chave pode consultar, usar ou encerrar uma sessão cujo id
tenha em mãos.

### Conta Administrativa (*Admin Account*)

O login local de uma pessoa no console administrativo. Não há provedor de identidade externo. A conta
tem um de dois perfis: **Administrador** pode mudar o estado da plataforma; **Auditor** só pode ler.
Toda conta também tem um **Segundo Fator**. Ela é aberta com a senha e o Segundo Fator ou, quando a
implantação permite, só com o **Acesso com Certificado**; uma implantação pode desligar a entrada com
senha, e aí o certificado é a única forma de entrar. Um administrador nunca assina documentos aqui: o
certificado usado para entrar só comprova quem a pessoa é.

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

O código TOTP que uma Conta Administrativa apresenta além da senha, cadastrado pelo próprio titular no
próprio dispositivo. Nenhum administrador consegue ler, definir ou repassar o de outra pessoa; a única
coisa que outro Administrador pode fazer é limpá-lo, o que obriga a uma nova inscrição. Os **Códigos
de Recuperação** são substitutos de uso único, emitidos como um conjunto na inscrição e mostrados uma
única vez; um conjunto novo substitui todo o antigo, e limpar o Segundo Fator os invalida. Eles são
guardados como hash, então o banco de dados não tem uma cópia utilizável. Uma implantação pode
declarar que não exige segundo fator, e isso é uma postura de toda a implantação, definida na
configuração, nunca uma exceção por conta. O Acesso com Certificado não apresenta segundo fator e é
completo sem ele, mas toda conta continua tendo um, porque a entrada com senha é o caminho de volta.

### Acesso com Certificado (*Certificate Sign-In*)

A entrada de uma Conta Administrativa no console administrativo comprovando que tem a chave de um
**e-CPF** ICP-Brasil que declara o **CPF vinculado** da conta, lido pelo Lacuna Web PKI no navegador
da própria pessoa. É completo por si só: não se apresenta nem senha nem Segundo Fator. Fica desligado
até que a implantação o ative e é oferecido ao lado da entrada com senha, a menos que a implantação
desligue as senhas. Qualquer certificado em que o Servidor confie para esse CPF serve, A1 ou A3,
inclusive uma renovação, então um certificado vencido significa uma ida à autoridade certificadora, e
não um bloqueio. Um e-CNPJ nunca dá acesso a ninguém, embora traga o CPF do responsável. O
certificado assina um desafio de uso único para comprovar quem a pessoa é e nunca assina um
documento.

### CPF vinculado (*Bound CPF*)

O CPF que um Administrador registrou como sendo o da pessoa a quem uma Conta Administrativa pertence:
aquilo que o Acesso com Certificado precisa conferir. Ele é digitado na tela de contas, nunca
comprovado pela apresentação de um certificado, então é exatamente tão confiável quanto o
Administrador que o digitou; o dono da conta vê na própria página qual é o CPF, quem o definiu e
quando. É um CPF e nunca um certificado, então qualquer certificado confiável que o declare dá acesso
à conta. Ele é único entre as contas. Só um Administrador define, substitui ou limpa um CPF vinculado,
e nunca na própria conta; por isso, uma implantação que desliga as senhas precisa de pelo menos dois
Administradores. Substituí-lo ou limpá-lo encerra os acessos abertos do dono em até cinco minutos. Não tem
relação com o CPF ao qual uma Sessão de Assinatura é vinculada, mesmo quando a mesma pessoa é as duas
coisas.

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

A chave que uma máquina gera para si mesma, no TPM quando há um utilizável e, caso contrário, em
software, e que ela não consegue entregar. Ela **é** a identidade da máquina: nada é emitido em troca
dela, então não existe segredo da estação de trabalho para copiar de um disco. Uma máquina que mantém
a chave numa reinstalação continua sendo a mesma estação de trabalho; uma máquina que perdeu a chave é
uma nova pedindo para entrar. Se a chave está em hardware ou em software é a **postura de chave** da
máquina, que um Administrador lê antes de admiti-la.

### Asserção da Estação de Trabalho

O que uma máquina admitida envia, no lugar de um segredo, ao se conectar (a *Workstation Assertion*):
uma declaração de curta duração com a impressão digital da chave, quando foi gerada, quando expira e
um nonce, assinada pela Chave da Estação de Trabalho. Uma asserção abre uma conexão; apresentada de
novo, é recusada. É uma prova, não uma credencial, então uma cópia capturada não serve para nada.
Cada download de uma Versão da Estação de Trabalho também leva uma asserção nova.

### Admissão (*Admission*)

O ciclo de vida em que uma estação de trabalho se encontra. A máquina se anuncia (a chave, o nome da
máquina, o sistema operacional, as versões e a postura de chave) e aguarda uma pessoa. Ela está em
exatamente um de três estados:

| Estado | Em inglês | Significado |
|--------|-----------|-------------|
| **Pendente** | *Pending* | Pediu e ainda não recebeu resposta. |
| **Admitida** | *Admitted* | Pode se conectar. |
| **Revogada** | *Revoked* | Recusada permanentemente. Uma máquina revogada que pede de novo é recusada e nunca volta para Pendente. |

Uma máquina pode ser devolvida de Admitida para Pendente sem perder a chave nem o histórico. Um pedido
Pendente abandonado, de uma máquina que ninguém nunca admitiu, **expira** depois de um período
configurável e é excluído; a máquina simplesmente pede de novo, como uma máquina que a plataforma
nunca viu.

O horário em que a máquina foi **vista pela primeira vez** é quando a linha dela foi gravada, ou seja,
o primeiro pedido. Uma linha Pendente que expirou e é gravada de novo recebe um horário novo. No banco
de dados é a coluna `FirstSeenAt` de `Workstations`, que se chamava `EnrolledAt` antes do Servidor
1.11.0; uma consulta ou relatório que use o nome antigo precisa ser alterado.

Admitir é uma etapa humana sobre uma fila, com limite de requisições: sem um canal independente
(out-of-band) contra o qual conferir uma impressão digital, a máquina é *notada*, e não *verificada*.
Isso é aceitável porque a admissão não é opcional e nada que a máquina tenha a admite por conta
própria.

### Installer Key

Uma chave com a qual o Workstation Service assina o pedido de admissão, além da sua própria, para
mostrar que o pedido veio do produto genuíno. Todas as cópias do TrustBridge têm a
mesma metade privada, então ela serve contra abuso e não autentica nada. Uma implantação pode receber
uma chave própria em vez dessa.

## Segredos e confiança

### Chaveiro (*Key Ring*)

O conjunto de chaves com que uma parte da plataforma cifra um segredo. Há três, e não há dois iguais:
o do Workstation Service, que protege as entradas do Cache de PIN; e os dois do Servidor, um que
protege o Cofre de Certificados (`certificate-vault`) e outro que protege as próprias sessões web dele
(`web-sessions`). Perder o do cofre torna todos os Certificados do Cofre impossíveis de abrir para
qualquer um, inclusive para esta plataforma; perder o das sessões web custa uma rodada de novos logins.

### Protetor do Chaveiro (*Key Ring Protector*)

O certificado X.509 com chave privada RSA que torna legíveis os dois chaveiros do Servidor, fornecido
como configuração e nunca guardado pela plataforma. Exigido de **todo** Servidor, inclusive de um sem
Certificados do Cofre, porque o chaveiro das sessões web também precisa dele. Perdê-lo é a forma mais
cara de operar mal a plataforma. Ele pode passar por rotação, mas um protetor aposentado nunca é
descartado: o Servidor continua precisando, permanentemente, de todo protetor sob o qual alguma chave
armazenada já foi selada.

### Autoridade Certificadora Confiável e Conjunto de Âncoras de Confiança

Uma **Autoridade Certificadora Confiável** (*Trusted CA*) é uma autoridade certificadora em que um
Administrador mandou este Servidor confiar, adicionada e removida no console administrativo e em vigor
sem reinício no Servidor e em toda máquina admitida que tenha recebido notícias dele desde então. Não
é sinônimo de "autoridade certificadora": toda AC da ICP-Brasil é confiável e nenhuma delas é uma
Autoridade Certificadora Confiável. Remover uma pode tornar certificados `UNTRUSTED`, por isso a
plataforma informa antes quantos dependem dela.

**Quando a implantação ativa o Acesso com Certificado, uma Autoridade Certificadora Confiável também
decide quem pode entrar no console administrativo.** O acesso confere um CPF, e não um certificado,
então uma autoridade que alguém adicione pode emitir um certificado para o CPF vinculado de qualquer
administrador e entrar como ele, sem senha e sem Segundo Fator. Adicionar uma é confiar a quem tem a
chave dela todos os CPFs vinculados da plataforma; a Trilha de Auditoria continua mostrando quem a
adicionou. Da mesma forma, remover uma pode recusar o acesso dos administradores cujos certificados
ela emitiu, e a tela de Autoridades Certificadoras Confiáveis mostra uma contagem aproximada deles.

O **Conjunto de Âncoras de Confiança** (*Trust Anchor Set*) de um componente é aquilo até onde uma
cadeia precisa chegar para que esse componente considere um certificado confiável. Ele é composto de
várias fontes, e qualquer uma delas basta: as raízes da ICP-Brasil que o PKI SDK traz,
opcionalmente o repositório de raízes da própria máquina, arquivos de âncora configurados numa
estação de trabalho e as Autoridades Certificadoras Confiáveis vindas do Servidor. Uma estação de
trabalho que recebeu do Servidor um conjunto não vazio de Autoridades Certificadoras Confiáveis usa
esse conjunto **no lugar** dos próprios arquivos de âncora. Só um certificado autoassinado pode
encerrar uma cadeia, então um conjunto que só tem intermediárias não ancora nada.

## Licenciamento e atualizações

### Licença da PKI (*PKI Licence*)

A permissão de que o Lacuna PKI SDK precisa para ler qualquer certificado. Há **uma por implantação, e
quem a guarda é o Servidor**, como configuração (`Certificates:Validation:License`): um Servidor sem
ela não inicia. O Servidor valida os próprios Certificados do Cofre com ela e a entrega a toda máquina
**Admitida** sempre que essa máquina se conecta, então renovar a licença é uma edição e um reinício no
Servidor, sem visitar nenhuma máquina. Nenhuma máquina a guarda entre reinícios, e nada que a
instalação de uma estação de trabalho grave a fornece. Uma máquina Pendente, ou que iniciou enquanto o
Servidor estava inacessível, fica sem licença até que o Servidor a licencie e, enquanto isso, mostra
todo certificado como `UNTRUSTED`; o Tray App diz em qual estado sem licença ela está. Uma licença
vencida não para o Servidor, mas nada na frota nem no cofre consegue assinar até que ela seja renovada,
e toda página administrativa avisa isso. Ela não é uma credencial: não autentica ninguém e não diz
nada sobre quais certificados são confiáveis.

### Versão do protocolo das estações de trabalho

A versão do canal entre o Workstation Service e o Servidor, que cada lado declara no handshake. Um
Servidor aceita uma janela de duas versões: a dele e a anterior. Uma máquina abaixo da janela é
recusada com *update required*; uma máquina acima dela é recusada com *update the Server first*, não
recebe licença da PKI e mostra todo certificado como `UNTRUSTED` até que o Servidor seja atualizado.
É por isso que, em geral, o Servidor é atualizado primeiro e a frota no máximo uma release atrás dele.

| Protocolo | Primeiro Servidor | Releases das estações de trabalho | O que acrescentou |
|-----------|-------------------|-----------------------------------|-------------------|
| 3 | 1.7.0 | 1.1.0 a 1.3.0 | O Servidor licencia a máquina no handshake. |
| 4 | 1.9.0 | 1.4.0 a 1.4.2 | Ofertas: a máquina pode receber atualizações do Servidor. |
| 5 | 1.13.0 (janela 4–5) | 1.5.0 | Provas de PIN no lugar do envio do PIN à máquina. |

**O protocolo 5 exige que os dois sejam atualizados juntos.** Uma máquina no protocolo 4 ainda se
conecta a um Servidor 1.13.0, recebe a licença, assina pelas sessões já vinculadas a ela e pode
receber oferta de uma versão, mas nunca recebe desafio nem pedido de PIN, então, para sessões novas,
ela conta como offline. O MSI de uma Versão da Estação de Trabalho declara o protocolo que fala, e o
Servidor se recusa a guardar uma versão fora da janela dele.

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

Um pacote assinado dos componentes da estação de trabalho, o Workstation Service e o Tray App, que um
Administrador enviou na tela **Versões da Estação de Trabalho** para que o Servidor possa oferecê-lo à
frota. O Servidor guarda um por versão, no banco de dados, e lê do próprio arquivo a versão, o
protocolo que ele fala e o signatário, então ninguém precisa digitá-los. Ele recusa, sem guardar nada,
um arquivo sem assinatura, um signatário que o **Publisher Pin** dele não lista, um protocolo fora da
janela dele ou uma versão que ele já tem. Guardar uma versão não muda nenhuma máquina: só uma
**oferta** muda. Não confunda com uma release do Servidor, que é uma linha separada, com versões
próprias.

### Oferta (*Release Offer*)

Uma Versão da Estação de Trabalho oferecida por um Administrador a uma máquina Admitida. Uma máquina
tem no máximo uma: oferecer outra substitui a anterior, e retirar a oferta a deixa sem nenhuma. A
máquina só age sobre uma oferta acima da versão que executa e só se a Diretiva de Grupo deixar as
atualizações ligadas. Ela baixa a versão, a confere (o hash anunciado, a assinatura Authenticode e o
carimbo de tempo, um signatário no Publisher Pin dela, a revogação, o produto e a versão), espera um
momento ocioso, sem assinatura nem pedido de PIN em andamento, instala sem perguntar nada ao titular e
informa se a instalação foi concluída, falhou ou foi recusada. Uma versão que falhou ou foi recusada
não é tentada de novo até que um Administrador a ofereça outra vez. Oferecer a todas as máquinas
abaixo de uma versão é uma seleção feita uma única vez, então uma máquina admitida depois não recebe
oferta até que alguém ofereça de novo. Uma máquina com o Workstation 1.3.0 ou anterior não consegue
receber oferta; a tela de estações de trabalho indica que ela precisa de atualização manual.

### Publisher Pin

A lista de certificados com que uma Versão da Estação de Trabalho pode ser assinada, compilada no
produto, tanto no Servidor quanto em cada Workstation Service, de modo que nenhum Servidor,
Administrador, diretiva ou configuração consegue alterá-la. Uma máquina não instala nada cujo
signatário não esteja no pin que ela já executa, então o pior que um Servidor ou uma conta
administrativa comprometidos conseguem fazer pelas atualizações é instalar antes da hora uma versão
genuína e mais nova. Cada máquina informa o próprio pin, e o Servidor só oferece uma versão a máquinas
cujo pin lista o signatário dela. Como o pin cita certificados, e não um fornecedor, a renovação do
certificado de assinatura de código da Lacuna Software sai primeiro numa release de transição,
assinada com o certificado antigo e listando os dois; uma máquina que não a recebe é atualizada à mão
ou pela Diretiva de Grupo.

## Registros

### Trilha de Auditoria (*Audit Log*)

O registro somente de acréscimo (append-only), no Servidor, dos eventos da plataforma: acesso à API,
ciclo de vida das sessões e das assinaturas, eventos de estações de trabalho e de PIN, e ações
administrativas, com uma entrada por evento contendo o autor, os identificadores do objeto e o
resultado. PINs, Provas de PIN, conteúdo de documentos e bytes de assinatura nunca aparecem nela. Uma entrada que o
banco de dados não aceita é gravada no Log do Servidor no nível `Critical`, com a própria linha.

### Log do Servidor (*Server log*)

O relato do próprio Servidor sobre o que estava fazendo, uma linha por evento com um nível, uma
categoria e um id de correlação que também aparece em toda resposta HTTP e liga a linha às linhas
correspondentes da Trilha de Auditoria. A saída do console é o registro; um arquivo rotativo no diretório
temporário alimenta a tela **Log do Servidor** do console administrativo, e o Application Insights é a
cópia retida, quando configurado. Linhas de log, linhas da Trilha de Auditoria, vereditos de
certificado e o `error.message` da API ficam permanentemente em inglês, qualquer que seja o idioma em
que a tela é lida.