---
title: "Segurança"
description: "Segurança do TrustBridge: o que protege o quê, onde fica cada segredo, o que o operador precisa guardar e o Cofre de Certificados como exceção às chaves locais."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge/security"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-12"
---

# Segurança

O que protege o quê na plataforma, onde fica cada segredo e o que o operador precisa guardar.

## A premissa fundamental e sua única exceção

**A chave privada de um Certificado de Estação de Trabalho nunca sai da estação de trabalho.** O
Workstation Service é o único caminho até os certificados de uma máquina, a chave só vê um hash, e a
assinatura com um certificado A3 acontece no hardware que o guarda. Nada no Servidor consegue assinar
com um Certificado de Estação de Trabalho, e nada no produto exporta um.

O **Cofre de Certificados** é a exceção deliberada, desligada por padrão. Com `Vault:Enabled=true`,
um Administrador pode importar um certificado A1, com chave e tudo, e o Servidor assina com ele. Isso
troca custódia por conveniência: uma chave armazenada no próprio repositório da plataforma, em vez de
em um cartão que não consegue entregá-la. Qual custódia um certificado usa é assunto do operador e do
auditor; a aplicação cliente nunca é informada.

## Tratamento do PIN

O PIN é o que autentica o titular perante o token dele, para que uma assinatura possa ser feita.
Quatro regras o regem:

- **O PIN é digitado localmente.** O titular o digita no Tray App da máquina em que o token está
  conectado, somente na sessão de console. O Workstation Service o guarda, criptografado, no Cache de
  PIN, indexado por certificado, com um TTL de inatividade deslizante (8 h por padrão).
- **O PIN que um cliente envia é comparado, não apresentado.** Quando `POST /v1/sessions` repassa um
  PIN a uma estação de trabalho, o serviço o compara com o PIN já em uso ali. Um valor errado vindo da
  rede não consegue consumir o contador de tentativas do token. Só PINs digitados pelo titular chegam
  ao hardware.
- **Dois bloqueios limitam tentativas de adivinhação.** O Servidor bloqueia a criação de sessões para
  um CPF após `Sessions:MaxPinFailures` (5) falhas dentro de `Sessions:PinFailureWindow` (15 min),
  contadas em todas as chaves de API e respondidas com `429 TOO_MANY_PIN_ATTEMPTS`. A estação de
  trabalho recusa entradas para um certificado após `Tray:MaxConsecutivePinFailures` (3) rejeições
  seguidas do token, durante `Tray:PinFailureCooldown` (5 min). Nenhum dos dois torna impossível o
  bloqueio do hardware: o titular ainda pode bloquear o próprio token digitando errado.
- **PINs nunca aparecem na Trilha de Auditoria, no log do Servidor nem na rede além do repasse.** O
  Cache de PIN do Workstation Service fica só em memória por padrão; `PinCache:SurviveRestart` o
  persiste com DPAPI no escopo da máquina, em um arquivo acessível apenas a SYSTEM e aos
  Administradores, um desvio documentado que o administrador escolhe ativar.

Para um Certificado do Cofre, o `pin` que o cliente envia é a senha que abre o arquivo do
certificado. O Servidor a usa para abrir a chave na criação da sessão, a mantém em memória somente
para aquela sessão e nunca a grava. Desativar a sessão, ou reiniciar o Servidor, a descarta.

## O Protetor do Chaveiro

Os dois chaveiros (key rings) do Servidor são linhas no banco de dados dele:

| Chaveiro | Protege | Se não puder ser lido |
|---|---|---|
| `web-sessions` | Cookies do console administrativo, tokens antifalsificação (antiforgery), circuitos do Blazor | Todos os administradores entram de novo, e nada mais |
| `certificate-vault` | A chave privada de cada Certificado do Cofre | **O host para.** Gerar uma chave nova deixaria órfão, silenciosamente, todo certificado já armazenado |

Os dois são selados sob um único certificado X.509 com uma chave RSA que a plataforma **não** guarda:
o **Protetor do Chaveiro** (Key Ring Protector), fornecido como `KeyRingProtector:Certificate`
(PKCS#12 em base64). Todo Servidor precisa de um, com ou sem cofre, porque o chaveiro das sessões web
também precisa dele. Quem consegue ler o protetor e o banco de dados consegue ler todos os
Certificados do Cofre; portanto, o protetor é um segredo por si só, e o `.env` ou o app setting que o
contém merece o mesmo cuidado que uma chave privada.

**Faça backup do PKCS#12 permanentemente, em algum lugar que a plataforma não consiga acessar.**
Perdê-lo torna todos os Certificados do Cofre impossíveis de abrir por qualquer pessoa, inclusive por
esta plataforma. Não há custódia de recuperação (escrow), de propósito. Uma referência ao Key Vault no
Azure é um lugar conveniente para o Servidor em execução, e não um backup.

**A rotação é aditiva.** Um protetor novo sela chaves novas; ele nunca recriptografa o que já está
armazenado. O protetor que sai passa para `KeyRingProtector:RetiredCertificates:{n}:Certificate`, e o
PKCS#12 dele é guardado **para sempre**. Exclua um protetor aposentado e você terá destruído tudo o que
foi selado sob ele, com todos os sintomas apontando para o banco de dados. O Servidor informa essa
situação a cada inicialização: a impressão digital (thumbprint) atual e a quantidade de protetores
aposentados.

## O Cofre de Certificados

Ligar esse recurso traz três coisas que uma implantação sem cofre nunca encontra:

- **A licença do Lacuna PKI SDK passa a ser crítica.** O Servidor valida o que guarda por meio do SDK,
  que não lê nada sem licença. Sem uma licença válida, todo Certificado do Cofre aparece como
  `UNTRUSTED` e toda importação é recusada. A imagem não traz licença; ela chega como
  `Certificates:Validation:License` e expira sem que nada falhe de forma visível, além de uma linha
  `Critical` na inicialização.
- **Um PKCS#12 precisa estar no formato PFX legado.** A biblioteca com que a plataforma assina não lê
  uma chave protegida com `pkcs5PBES2`, que é o que `openssl pkcs12 -export` grava se não receber
  `-legacy`, e o que caminhos de exportação recentes do Windows também gravam. Um arquivo assim é
  recusado na importação, com a indicação de exportá-lo de novo:
  ```bash
  openssl pkcs12 -export -legacy -in holder.pem -inkey holder.key -out holder.pfx
  ```
- **O cofre pode ficar travado fechado** quando o Servidor inicia antes de o banco de dados responder.
  Veja [Operações](https://docs.lacunasoftware.com/articles/trustbridge/operations#a-trava-do-cofre).

A senha de importação é usada para provar que o arquivo abre e **nunca é armazenada**: nada consegue
abrir um arquivo armazenado sem alguém presente, e é também por isso que nenhum processo automático
consegue verificar se arquivos antigos estão no formato legado. Não há caminho de exportação nem de
download. Um certificado sai do cofre ao ser **destruído**, o que não pode ser desfeito, e a
confirmação pede que o CPF seja digitado. **Fora de uso** impede que um certificado abra sessões e
assine, mas o mantém.

Uma Sessão de Assinatura vinculada ao cofre não sobrevive a um reinício do Servidor, porque o segredo
que abre o certificado fica só na memória. Isso é uma propriedade da custódia, não um defeito.

## Chaves de API

Uma **chave de API** autentica uma Aplicação Cliente em toda a superfície do contrato. Ela é emitida
na tela **Aplicações Cliente** com um nome e uma validade opcional, **exibida uma única vez** e
armazenada apenas como o SHA-256 dela. Todas as chaves aceitas de uma aplicação são equivalentes; a
chave não restringe nada.

- **Revogue** uma chave e a próxima requisição que a apresentar será recusada, permanentemente.
- **Desative** uma aplicação e todas as chaves dela passam a ser recusadas imediatamente; ativá-la de
  novo as restaura.
- **Faça uma chave expirar** no fim de um dia em UTC, ou apague a data para que ela volte a não ter
  validade.
- Para fazer a rotação, emita uma chave nova ao lado da antiga, implante-a e então revogue a antiga.

Chaves ausentes, desconhecidas, revogadas, expiradas e de aplicações desativadas são todas recusadas
da mesma forma, com `401 UNAUTHORIZED`, então quem chama não descobre qual era o caso. Cada chave tem
o próprio rastro na Trilha de Auditoria, inclusive as chamadas recusadas.

Um `sessionId` e um `signatureId` são tokens de portador daquilo que identificam: qualquer chave aceita
pode usar uma sessão ou buscar um documento cujo id ela tenha. Não entregue nenhum dos dois a quem não
deveria tê-los.

## Contas administrativas e o segundo fator

As Contas Administrativas são locais. Toda conta tem um **Segundo Fator** (TOTP de um aplicativo
autenticador) nos dois papéis, cadastrado pelo próprio dono e conhecido por mais ninguém. Os **Códigos
de Recuperação** são substitutos de uso único, emitidos em conjunto no cadastro e exibidos uma única
vez. Um Administrador pode limpar o segundo fator de outra pessoa, o que invalida os Códigos de
Recuperação dela e força um novo cadastro, mas nunca pode lê-lo nem defini-lo.

`Admin:SecondFactor:Required` (padrão `true`) é configuração da implantação e fica de fora, de
propósito, da tela **Configurações e usuários**: um interruptor que desativa o segundo fator,
acessível de dentro do próprio console que ele protege, é um interruptor que um invasor aciona no
caminho. Uma linha salva no banco de dados com essa chave é ignorada. A mesma proteção vale para
`Vault:Enabled`.

As senhas têm pelo menos doze caracteres. Não há e-mail de redefinição; um Administrador define uma
senha nova na tela **Configurações e usuários** e a entrega pessoalmente, e as sessões existentes da
conta terminam em até cinco minutos. Desativar uma conta a mantém, porque a Trilha de Auditoria
atribui a ela as ações passadas.

### Acesso de emergência (break-glass): autenticador perdido

Um Administrador que perdeu o dispositivo pode ficar sem acesso mesmo enquanto a plataforma acredita
que outro Administrador consegue entrar. O caminho de volta é pela implantação, não pelas telas:

1. Defina `Admin:SecondFactor:Required=false` e reinicie o Servidor.
2. Deixe que ele entre com a senha e cadastre um autenticador novo.
3. Volte a configuração para `true` e reinicie.

O Servidor anuncia a postura enfraquecida em **toda** inicialização enquanto ela estiver desligada,
não só na primeira, porque um acesso de emergência que ninguém fechou de novo é justamente a falha
sobre a qual vale avisar.

## Admissão de estações de trabalho

Uma máquina **não tem segredo compartilhado** com que entrar na plataforma, e procurar um é procurar
algo que o produto deliberadamente não tem. Ela gera uma **Chave da Estação de Trabalho** no TPM,
quando há um utilizável (senão, em software), se anuncia e aguarda que um Administrador a admita.
Depois de admitida, ela se prova a cada conexão com uma **Workstation Assertion** assinada e de curta
duração, em vez de uma credencial: nada é emitido, nada é armazenado, e uma asserção capturada já foi
consumida.

A **Installer Key**, que também assina a requisição de admissão, serve contra abusos, não para
autenticação: toda cópia do TrustBridge tem a metade privada do produto. Uma implantação que queira
uma chave que ninguém mais tenha gera uma, informa a metade pública dela em `Admission:InstallerKeys`
(o que substitui a chave do produto) e entrega a metade privada pelo próprio instalador.

O valor da admissão é limitado, e a tela diz isso: sem um canal externo (out-of-band) com que conferir
uma impressão digital, uma máquina é notada, e não verificada. Os controles em volta dela:
`Admission:MaxPending` limita a fila, `Admission:RequestsPerAddress` limita um endereço de origem,
`Admission:PendingExpiry` faz expirar requisições abandonadas e `Admission:RequireHardwareBackedKeys`
recusa máquinas com chave em software. A postura da chave é declarada pela própria máquina; atestação
de TPM está fora do escopo.

A **revogação** na tela **Estações de Trabalho** recusa uma máquina permanentemente e não depende da
cooperação dela. Uma máquina cujo disco foi clonado com uma chave em software é uma identidade
clonada, e é isso que a postura de exigir hardware existe para recusar.

## Âncoras de confiança

A plataforma confia nas **raízes da ICP-Brasil** que o PKI SDK traz por padrão. Uma autoridade
certificadora privada é adicionada como **Autoridade Certificadora Confiável** (Trusted CA) no console
administrativo, passa a valer no Servidor em execução e é enviada a todas as máquinas admitidas. Quem
pode adicionar uma Autoridade Certificadora Confiável pode fazer certificados próprios serem validados
como `ACTIVE`; por isso a ação é de um Administrador e é auditada, e por isso uma autoridade descoberta
pela web, a partir de uma URL indicada pelo próprio certificado não confiável, é sinalizada para
conferência da impressão digital antes de ser confirmada.

Em uma estação de trabalho, os arquivos de âncora em `C:\ProgramData\TrustBridge\anchors\` são o
equivalente, protegidos por uma ACL que pertence ao instalador, e são desconsiderados enquanto a
máquina tiver um conjunto não vazio recebido do Servidor.

Dois interruptores ampliam a confiança e merecem atenção: `UseMachineRootStore` (todas as ACs públicas
do programa de raízes do Windows, em uma estação de trabalho) e `UseLacunaTestPki` (**somente para
desenvolvimento**: a Lacuna publica as chaves privadas desses certificados de exemplo, e um Servidor
com ele ligado exibe um banner de aviso em todas as páginas administrativas).

`Certificates:Validation:RevocationGraceWindow` (24 h) é a outra decisão de confiança: exatamente por
quanto tempo um certificado continua assinando depois que a AC dele parou de responder, revogado ou
não. Zero é a postura mais rígida.

## Postura de rede

- **As estações de trabalho só fazem conexões de saída**, por HTTPS até o Servidor. Nenhuma porta de
  entrada é aberta na máquina, e o canal entre o Service e o Tray é um named pipe local cuja ACL é
  todo o controle de acesso dele.
- **O Servidor termina o próprio TLS** no Docker e precisa apresentar uma cadeia em que todas as
  estações de trabalho confiem; no App Service, a plataforma o termina, e
  `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` é o que mantém o endereço de quem chama na Trilha de
  Auditoria. Atrás de qualquer proxy, vale a mesma configuração.
- **Sete áreas compartilham uma porta**, distinguidas pelo caminho: o contrato em `/v1`, o canal das
  estações de trabalho, a admissão de estações de trabalho, a documentação publicada, a Landing Page,
  o health probe e as páginas administrativas. Um caminho fora de todas elas recebe um `401` de chave
  de API antes que um navegador o veja. `/healthz`, `/` e a documentação respondem sem credencial e,
  de propósito, não revelam nada sobre o estado da plataforma.
- **O throttle global** (`Throttle:ConcurrencyLimit`, 200) é um disjuntor (circuit breaker) sobre a
  superfície do contrato contra um cliente descontrolado e não pode ser desligado.
- **Nunca execute uma implantação com `ASPNETCORE_ENVIRONMENT=Development`**: a imagem traz um arquivo
  de configuração de desenvolvimento com uma licença de exemplo e as credenciais de um Signer de testes
  compartilhado, inofensivos apenas porque uma implantação é Production.

## O que é gravado onde

| Registro | Contém | Nunca contém |
|---|---|---|
| **Trilha de Auditoria** (banco de dados) | Ator, ids dos objetos, resultado e timestamps de cada chamada à API, evento de sessão e de assinatura, evento de estação de trabalho e de PIN e ação administrativa | PINs, conteúdo de documentos, bytes de assinatura |
| **Log do Servidor** (console, arquivo rotativo, Application Insights) | O que o Servidor estava fazendo, com um id de correlação; linhas de auditoria que o banco de dados recusou, em `Critical` | PINs, material de chave |
| **Log do Workstation Service** (log de eventos Aplicativo, painel de diagnóstico do Tray) | De onde veio cada valor definido na instalação, estado da conexão, recusas, vereditos | PINs |
| **Banco de dados** | Sessões, operações, Registro de Certificados, texto cifrado do cofre, os dois chaveiros, contas administrativas, valores alterados nas configurações | O Protetor do Chaveiro, qualquer documento do Signer |

Nada em nenhum dos componentes grava documentos em disco. Os documentos ficam só em trânsito, em
memória, limitados a `Signing:MaxDocumentBytes` vezes `Signing:MaxBatchItems`.