Configuração da estação de trabalho

Todas as configurações que o Workstation Service aceita e como uma instalação na frota as fornece. As configurações do Servidor estão em Configuração do Servidor; os dois hosts não compartilham nenhuma configuração. O Tray App não tem nenhum arquivo de configuração (veja a última seção).

Todo valor aqui tem um padrão, e a maioria das máquinas da frota não altera nenhum deles. Três valores chegam pelo MSI e pela Diretiva de Grupo; os demais ficam no arquivo de configuração que o MSI instala ao lado dos binários.

Como um valor chega a uma máquina

A última fonte a definir uma chave prevalece:

	Fonte	O que a fornece
1	appsettings.json ao lado dos binários	Instalado pelo MSI em Program Files. Nada no serviço o regrava.
2	appsettings.Development.json, user secrets	Somente a execução de um desenvolvedor no console.
3	HKLM\Software\TrustBridge, a preferência	O MSI, a partir de SERVER_URL, PKI_LICENSE e INSTALLER_KEY. Um reparo ou uma gravação manual com elevação grava os mesmos valores no mesmo lugar.
4	Variáveis de ambiente, __ no lugar de :	Uma execução no console ou um wrapper de serviço. Não é assim que uma instalação na frota funciona.
5	Argumentos de linha de comando	Somente uma execução no console.
6	HKLM\Software\Policies\TrustBridge, a diretiva	A Diretiva de Grupo, por meio do modelo ADMX fornecido. Somente o mecanismo de diretivas pode gravar ali.

Três valores chegam pelo Registro: ServerUrl vira Server:Url, PkiLicense vira Certificates:Validation:License e InstallerKey vira Server:InstallerKey. Um valor publicado com o tipo de Registro errado (um REG_DWORD onde se esperava uma string) impede a inicialização, citando o local. Os dois locais do Registro são lidos uma vez, na inicialização: uma atualização de GPO entra em vigor na próxima inicialização do serviço.

Não há segredo que uma instalação entregue a uma máquina para que ela entre na plataforma. Uma máquina gera a própria Chave da Estação de Trabalho, se anuncia e aguarda ser admitida por um Administrador. Nada nesta página é enviado pelo Servidor; a única coisa que o Servidor envia a uma máquina é o conjunto de Autoridades Certificadoras Confiáveis dele, que é política de confiança, e não configuração.

Os formatos de valor são os do Servidor: : em um arquivo e __ no ambiente, durações como [d.]hh:mm:ss, com a armadilha dos vinte e quatro dias, e tamanhos como inteiros simples.

Acessando o Servidor

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

Server:Url

Padrão não definido · Instalação na frota o MSI grava SERVER_URL em HKLM\Software\TrustBridge\ServerUrl; a Diretiva de Grupo o sobrepõe em HKLM\Software\Policies\TrustBridge\ServerUrl · Valor inválido impede a inicialização

Onde fica o Servidor desta máquina. Obrigatório, e precisa ser um URI absoluto. O MSI recusa primeiro um valor vazio ou sem esquema, na condição de inicialização dele; a verificação do serviço na inicialização é a segunda barreira. O Tray App mostra essa URL e nunca pode defini-la: quem a grava decide onde a máquina pede para ser admitida, então a gravação fica atrás de uma barreira de elevação.

Server:InstallerKey

Padrão a chave do próprio produto · Instalação na frota o MSI grava INSTALLER_KEY em HKLM\Software\TrustBridge\InstallerKey, somente em uma implantação que gerou uma chave própria · Valor inválido impede a inicialização

A Installer Key com que esta máquina assina a requisição de admissão, além da própria chave: PKCS#8 DER em base64, ECDSA P-256. Ela mostra que a requisição veio do produto genuíno e não autentica nada; toda cópia do TrustBridge tem a metade privada do produto. Uma implantação que queira uma chave própria configura a metade pública no Servidor, em Admission:InstallerKeys, e entrega a metade privada aqui. Defina-a nas máquinas antes que o Servidor deixe de confiar na chave antiga. Não é um segredo. Fica de fora do modelo ADMX, de propósito.

Server:InitialReconnectDelay e Server:MaxReconnectDelay

Padrão 1 s e 1 min · Instalação na frota nunca alterados · Valor inválido um valor não positivo, ou um teto abaixo do piso, impede a inicialização

Onde começa o backoff de reconexão depois que o canal cai, e o teto até onde ele sobe. Uma máquina que não consegue acessar o Servidor tenta de novo nesse ritmo indefinidamente. Duas falhas são registradas no log em Error, para que possam ser distinguidas de uma instabilidade passageira: o Servidor respondeu 401 no canal (admissão retirada ou revogada), e o Servidor recusou a requisição de admissão (revogada, Installer Key não confiável, requisições demais do endereço ou fila cheia; o log cita as quatro). Aguardar a admissão não é uma falha e é registrado uma vez em Information.

Detecção de certificados

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

Chave	Padrão	Significado
Certificates:SweepInterval	1 min	A varredura de reconciliação, sempre ativa: uma enumeração com comparação de todos os repositórios, que cobre um gatilho de mudança perdido ou um token que nunca aparece como smart card. Um valor não positivo impede a inicialização.
Certificates:ValidationInterval	1 h	A frequência com que todo certificado presente é validado de novo por completo, para que uma revogação, uma expiração ou o fim de uma janela de tolerância apareça dentro de um intervalo.
Certificates:ChangeDebounce	2 s	Quanto tempo o pipeline aguarda depois de um sinal de mudança antes de enumerar, para que a chegada de um cartão seja agrupada e o middleware tenha tempo de tornar os certificados legíveis. Fora do intervalo de zero a 5 minutos, impede a inicialização. Um valor baixo demais custa uma varredura inteira; um alto demais custa um segundo de latência.

Os repositórios de certificados

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

Certificates:WindowsStore:Enabled

Padrão true · Instalação na frota decisão do administrador · Valor inválido impede a inicialização

Se o repositório de certificados do Windows da máquina (LocalMachine\My) é lido em busca de certificados A1. Ligado, um A1 instalado ali é enumerado, validado e anunciado como qualquer outro certificado, com o leitor ignorando tudo o que não seja uma identidade de assinatura (sem chave privada, ou sem CPF de e-CPF). A notificação de mudanças do repositório fica aberta, para que uma importação seja anunciada dentro de ChangeDebounce. Desligado, nada na máquina abre esse repositório. Lido uma vez, na inicialização.

Um certificado A1 é anunciado e fica visível no Tray App, mas uma Sessão de Assinatura sobre ele ainda espera um PIN que nenhum A1 tem; por isso, sessões e assinaturas com um Certificado de Estação de Trabalho A1 são recusadas até que o fluxo sem PIN seja lançado. Um A1 importado no Cofre de Certificados é, hoje, a forma suportada de assinar com um deles.

Certificates:Pkcs11:Modules

Padrão não definido, o que significa a lista de fabricantes fornecida · Instalação na frota nunca alterado em uma máquina com middleware comum · Valor inválido um módulo que não carrega é uma falha desse repositório no log, e não uma inicialização recusada

Os módulos PKCS#11 dos fabricantes, por meio dos quais os tokens A3 são lidos, como uma única string de caminhos absolutos separados por ponto e vírgula. Três estados:

• Não definido é a lista padrão fornecida: SafeNet Authentication Client, SafeSign IC, Watchdata PROTON, Feitian ePass2003, Idemia AWP e Thales IDPrime, nos caminhos em que esses fabricantes os instalam, verificados pela existência do arquivo. Frotas comuns têm detecção de tokens sem nenhuma configuração.
• Definido é exatamente o que está na lista, por inteiro; nada é verificado e nenhum padrão é mantido. É assim que se adiciona um middleware incomum, ao custo de também listar os comuns de que a máquina precisa.
• Definido como vazio desliga a detecção de A3. Por variável de ambiente, desligado é Certificates__Pkcs11__Modules=";", porque uma variável que não existe é lida como não definida.

Cada módulo é um repositório próprio e eles falham isoladamente: um middleware com falha custa apenas os certificados daquele fabricante, que passam a STALE ao longo da janela de tolerância. A enumeração nunca envolve um PIN e não consome nada do contador de tentativas de um token. Lido uma vez, na inicialização.

Validação de certificados e a licença do PKI SDK

O mesmo nome de seção e a mesma política que o Servidor lê. Quatro coisas são diferentes em uma estação de trabalho, e cada uma é destacada abaixo.

{
  "Certificates": {
    "Validation": {
      "License": "PD94bWwgdmVyc2lvbj0…",
      "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

Padrão não definido · Instalação na frota o MSI grava PKI_LICENSE em HKLM\Software\TrustBridge\PkiLicense; a Diretiva de Grupo o sobrepõe em HKLM\Software\Policies\TrustBridge\PkiLicense · Valor inválido uma licença vencida ou corrompida gera uma linha Critical na inicialização; um valor de Registro do tipo errado impede a inicialização

Obrigatória em todas as máquinas, e essa é a primeira diferença em relação ao Servidor. Aqui, o SDK é o que lê qualquer certificado; sem licença, todo certificado da máquina aparece como UNTRUSTED e a máquina não assina nada. O valor é a própria licença, codificada em base64 em uma linha, e não um caminho. O local da diretiva está no modelo ADMX de propósito: um vencimento da licença seria, de outra forma, uma indisponibilidade da frota, e uma atualização de GPO é como uma renovação chega à frota, com cada máquina adotando-a na próxima inicialização do serviço.

As fontes de âncoras

Chave	Padrão	Significado
Certificates:Validation:UseIcpBrasil	true	As raízes da ICP-Brasil que o SDK traz. Desligá-la é uma decisão de confiança.
Certificates:Validation:UseMachineRootStore	false	A segunda diferença: aqui ela tem efeito. Confia em todas as ACs públicas do programa de raízes do Windows, um conjunto muito mais amplo que a ICP-Brasil.
Certificates:Validation:UseLacunaTestPki	false	Confia também na PKI de testes da Lacuna. Somente para desenvolvimento: a Lacuna publica as chaves privadas correspondentes. O serviço avisa isso em Critical a cada inicialização.

Certificates:Validation:UseServerTrustedCas

Padrão true · Instalação na frota o arquivo de configuração que o MSI instala (esta chave não tem valor no Registro, então nenhuma GPO a alcança) · Valor inválido impede a inicialização

A terceira diferença: esta chave só tem efeito em uma máquina. Define se a máquina incorpora as Autoridades Certificadoras Confiáveis do Servidor ao próprio conjunto de âncoras. Ligada, a máquina pede o conjunto ao Servidor depois de cada handshake e pede de novo quando o Servidor avisa que ele mudou; assim, uma AC que um Administrador adiciona na tela Autoridades Certificadoras Confiáveis chega aos vereditos desta máquina em segundos. O último conjunto recebido fica em cache localmente e continua valendo enquanto o Servidor estiver inacessível: um Servidor que não responde não disse nada, e só um Servidor respondendo, inclusive respondendo nenhuma Autoridade Certificadora Confiável, substitui o que a máquina tem.

Enquanto esta máquina tiver um conjunto não vazio recebido do Servidor, TrustedRootPaths é totalmente desconsiderado, e o serviço avisa isso em Critical, citando os caminhos descartados. Um controle que só acrescentasse confiança nunca conseguiria retirá-la.

Desligada, a máquina nunca pede e valida apenas contra a própria configuração, TrustedRootPaths incluído: é a postura para uma frota com um pipeline próprio de âncoras, sob controle de mudanças. Desligá-la em toda a frota é uma alteração no arquivo de configuração de cada máquina, e vale a pena planejá-la antes de atualizar o Servidor para o protocolo 2, e não depois. De qualquer forma, a máquina informa em qual postura está a cada conexão, e a tela Estações de Trabalho a mostra por máquina.

Certificates:Validation:TrustedRootPaths

Padrão vazio · Instalação na frota decisão do administrador, implantada junto com os arquivos de âncora · Valor inválido um arquivo ilegível gera uma linha Critical, e não uma inicialização recusada

Como uma AC privada é adicionada a partir de um arquivo nesta máquina. Não é mais a palavra final: a forma suportada de confiar em uma AC privada em toda a frota é uma Autoridade Certificadora Confiável adicionada uma vez no Servidor. Esta chave ainda decide a resposta inteira em uma máquina em que UseServerTrustedCas está desligado, em uma que nunca teve contato com um Servidor, em uma cujo Servidor não tem Autoridades Certificadoras Confiáveis ou em uma que ainda está no protocolo 1.

A quarta diferença: estes precisam ser caminhos absolutos. Quem consegue adicionar um arquivo aqui consegue fazer um certificado próprio ser validado como ACTIVE, então os arquivos devem ficar em C:\ProgramData\TrustBridge\anchors\, cuja ACL pertence ao instalador. Sem nenhuma âncora, o serviço ainda inicia e todo certificado aparece como UNTRUSTED, com uma linha Critical citando as configurações; arquivos de âncora que contêm só intermediárias geram uma segunda linha, diferente.

Os limites de revogação

Chave	Padrão	Significado
Certificates:Validation:RevocationGraceWindow	24 h (1.00:00:00)	Por quanto tempo a última verificação de revogação bem-sucedida mantém um certificado ACTIVE enquanto a AC dele está inacessível; depois disso, o certificado passa a STALE. Ampliar este valor é ampliar o tempo durante o qual um certificado revogado continua assinando enquanto a AC dele está inacessível. Um valor negativo impede a inicialização.
Certificates:Validation:RevocationTimeout	5 s	Quanto tempo o download de uma LCR ou a busca de um emissor pode levar antes de a AC ser considerada inacessível. Um valor não positivo impede a inicialização.
Certificates:Validation:CheckTimeout	30 s	O limite externo da verificação inteira de um certificado. As validações são feitas em série na máquina, então uma verificação sem limite trava todos os certificados atrás dela. Zero espera indefinidamente.

Enquanto o Servidor e esta máquina estão em versões diferentes

UseServerTrustedCas só tem efeito em um canal no protocolo 2, e um Servidor e uma frota nunca são atualizados no mesmo minuto. A ordem de atualização é primeiro o Servidor, depois as estações de trabalho, dentro de um mesmo ciclo de versão, e ela tem consequências:

• Um Servidor à frente desta máquina se conecta e simplesmente nunca pede. Uma máquina no protocolo 1 faz o handshake, assina e informa vereditos como sempre fez, e continua validando contra o próprio TrustedRootPaths. Uma Autoridade Certificadora Confiável adicionada no Servidor não chega a ela, e a tela Estações de Trabalho mostra Requer atualização na linha dela.
• Esta máquina à frente do Servidor não se conecta. O Servidor mais antigo recusa o handshake (Protocol version 2 is newer than this server's supported window (0–1); update the Server first), e esta máquina não consegue assinar até que o Servidor seja atualizado.

O canal entre o Service e o Tray

O canal por named pipe entre o serviço e o Tray App. A ACL dele admite usuários interativos, e esse é todo o controle de acesso dele. Uma instalação na frota não mexe em nada disto.

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

Chave	Padrão	Significado
Tray:PipeName	TrustBridge.WorkstationService	O pipe em que o serviço escuta. Configurável só para que um desenvolvedor possa executar uma segunda instância; o Tray App se conecta ao nome conhecido e não tem configuração própria. Um valor em branco impede a inicialização.
Tray:PromptTimeout	90 s	Quanto tempo uma solicitação de PIN fica na tela do usuário antes de o serviço desistir dela. Deliberadamente mais folgado que o Sessions:PinPromptTimeout do Servidor (60 s), e precisa continuar assim: um Servidor que desistiu não consegue mandar esta máquina fechar a solicitação, então é esta janela que encerra toda solicitação não respondida.
Tray:MaxConsecutivePinFailures	3	Quantos PINs um token pode rejeitar seguidamente antes que as entradas para aquele certificado sejam recusadas sem ser repassadas. Limita um processo que tenta milhares de vezes, não uma pessoa: o usuário ainda pode bloquear o próprio token digitando errado. Zero impede a inicialização.
Tray:PinFailureCooldown	5 min	Por quanto tempo as entradas para um certificado são recusadas depois que esse limite é atingido. Não é um estado do token; nenhum PUK está envolvido.
Tray:LogBufferSize	500	Quantas entradas recentes de log o serviço guarda para o painel de diagnóstico do Tray. Somente em memória.

O Cache de PIN

Local e controlado pelo administrador. O Servidor não envia nada para cá, e nenhuma chamada do Tray ou da API pode alterá-lo. Uma linha a cada inicialização informa em qual postura a máquina está.

{
  "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

Padrão false · Instalação na frota decisão do administrador, e um desvio documentado

Se os PINs em cache sobrevivem a um reinício do serviço ou da máquina. Desligado, as entradas são criptografadas com um chaveiro que só existe no processo em execução, então parar o serviço destrói o meio de lê-las. Ligado, o chaveiro é persistido em KeyRingPath, protegido com DPAPI no escopo da máquina, e o texto cifrado vai para StorePath, em um arquivo cuja ACL admite apenas SYSTEM e Administradores. Em qualquer caso, o TTL fica selado dentro do texto cifrado, então um reinício não consegue zerá-lo e editar o arquivo não consegue estendê-lo.

Ligá-lo é um desvio documentado do gatilho de encerramento do requisito de middleware da ICP-Brasil (REQUISITO-MW II.27), que o TrustBridge trata como uma diretriz porque fica acima do middleware do fabricante. Uma máquina com ele ligado avisa isso em Warning a cada inicialização.

O restante do Cache de PIN

Chave	Padrão	Significado
PinCache:Ttl	8 h	Quanto tempo uma entrada vive sem ser usada. Deslizante: cada uso renova a expiração, então um usuário ativo todo dia nunca é solicitado de novo. Um valor não positivo impede a inicialização.
PinCache:SweepInterval	5 min	A frequência com que entradas inativas são removidas da memória. De qualquer forma, nada consegue obter um PIN expirado.
PinCache:StorePath	%ProgramData%\TrustBridge\pin-cache.dat	Onde o texto cifrado é gravado. Nunca é gravado enquanto a sobrevivência estiver desligada.
PinCache:KeyRingPath	%ProgramData%\TrustBridge\keys	Onde fica o chaveiro persistido. Não é usado enquanto a sobrevivência estiver desligada.

Logs

A configuração do próprio framework, no mesmo formato da do Servidor. O arquivo fornecido define Default como Information e reduz duas categorias do cliente SignalR a Warning. Duas linhas que um administrador deve reconhecer no nível padrão: em qual postura do Cache de PIN a máquina está (a cada inicialização) e que o mecanismo de tokens falsos para desenvolvimento está ativo (a cada inicialização, em qualquer máquina com uma seção FakeTokens). Uma seção FakeTokens não deve existir em uma máquina em que alguém assine: ela faz certificados fabricados serem validados como ACTIVE.

O Tray App não lê nenhum arquivo de configuração

Não há appsettings.json para o Tray App. As opções dele são construídas no código: o nome do pipe e a versão de protocolo a que ele se conecta, o intervalo de reconexão e a tolerância de expiração da solicitação são compilados, e o idioma que ele exibe vem da cultura de interface do Windows do usuário conectado, e não de uma configuração. O que molda o canal entre os dois é a seção Tray acima, que é lida pelo serviço.