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:

  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.

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.