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). Esta página descreve o Workstation 1.10.0.

Todo valor aqui tem um padrão, e a maioria das máquinas da frota não altera nenhum deles. Seis valores chegam pelo Registro, cinco deles pelo MSI (que a Política de Grupo pode sobrepor) e um só pela Política 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. O MSI não instala esse arquivo.
3	HKLM\Software\TrustBridge, a preferência	O MSI, a partir de SERVER_URL, INSTALLER_KEY, INSERTION_PROMPT, RESTART_FAILED_READERS e WORKSTATION_REPORT. 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 política	A Política de Grupo, por meio do modelo ADMX fornecido. Somente o mecanismo de políticas pode gravar ali.

Seis valores chegam pelo Registro. Em qualquer um dos locais, ServerUrl vira Server:Url e InstallerKey vira Server:InstallerKey. ServerUpdates vira ServerUpdates:Enabled e é lido somente no local da política: nenhuma propriedade do MSI o grava, e um ServerUpdates colocado manualmente em HKLM\Software\TrustBridge não é lido. Três opções são lidas em qualquer um dos locais, com a política vencendo a preferência que o MSI gravou: InsertionPrompt vira Tray:InsertionPrompt, RestartFailedReaders vira Certificates:RestartFailedReaders e WorkstationReport vira WorkstationReport:Enabled. Um valor de string publicado com o tipo de Registro errado (um REG_DWORD onde se esperava uma string) impede a inicialização, citando o local. As quatro opções também não são adivinhadas, mas uma máquina que não consegue ler uma delas ainda consegue assinar, então um ServerUpdates que não seja um REG_DWORD com 0 ou 1 é lido como desligado e registrado em Error (veja a entrada dele); as outras três são lidas da mesma forma, com mais uma forma aceita, a string "0" ou "1" que o MSI grava. 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.

A licença da PKI não é um deles. O Servidor a fornece no handshake; veja Certificates:Validation:License.

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. O que o Servidor envia a uma máquina é a licença da PKI, o conjunto de Autoridades Certificadoras Confiáveis dele e, quando um Administrador oferece uma, uma Versão da Estação de Trabalho; nada disso altera uma chave daqui.

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 Política 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. O que o Tray App pode fazer (desde o Workstation 1.6.0) é abrir a porta dessa barreira: o botão Trocar de Servidor… dele inicia a tela de manutenção do pacote instalado, onde acontece o reparo que reaponta a máquina (Reparando e reapontando). Ele só oferece isso quando a URL veio da preferência, e mostra (definido por Política de Grupo) ao lado de uma que veio da política.

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, ou a máquina removida da frota, depois do que ela pede admissão de novo como uma máquina nova), 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). Uma máquina revogada continua recusada enquanto o Servidor mantiver a linha dela: ela só volta como uma máquina nova, com uma nova Chave da Estação de Trabalho ou depois que um Administrador a remove. Aguardar a admissão não é uma falha e é registrado uma vez em Information.

Keep-alive

Não é uma configuração, mas decide em quanto tempo uma máquina que sumiu aparece como offline. O serviço envia um ping ao Servidor a cada 5 s quando não enviou mais nada, e desiste do Servidor depois de três dos pings que o Servidor diz enviar (15 s). O Servidor, por sua vez, desconecta uma máquina de que não ouve nada por Workstations:ClientTimeout (30 s por padrão). Toda versão a partir da 1.2.0 envia ping a cada 5 s, então, quando a frota inteira estiver na 1.2.0 ou posterior, essa configuração do Servidor pode ser reduzida para 15 s; veja Configuração do Servidor.

Atualizações pelo Servidor

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

ServerUpdates:Enabled

Padrão true · Instalação na frota somente a Política de Grupo, em HKLM\Software\Policies\TrustBridge\ServerUpdates: um REG_DWORD, 0 para desligado e 1 para ligado, que a política Receber atualizações do Servidor TrustBridge fornecida grava quando é desabilitada ou habilitada · Valor inválido na política, qualquer coisa que não seja um REG_DWORD com 0 ou 1 é lida como desligada e registrada em Error; em um arquivo de configuração, impede a inicialização

Se esta máquina recebe as Versões da Estação de Trabalho que o Servidor dela lhe oferece. Ligado, a menos que uma política o desligue, inclusive em uma frota cuja primeira instalação veio pela Política de Grupo. Não há propriedade do MSI nem valor de preferência para ele: uma frota que queira o canal desligado tem a Política de Grupo.

Desligado, a máquina não baixa nem instala nada, seja o que for que o Servidor lhe ofereça: ela nunca aguarda o atraso aleatório, nunca pede um pacote e nunca inicia o msiexec (Atualizações entregues pelo Servidor é o que ligado significa). O log de inicialização avisa isso uma vez. A máquina avisa o Servidor a cada handshake que está desligado, o Servidor não lhe oferece nada, e a tela Estações de Trabalho a mostra como Atualizações desativadas por política, e não como atrasada. Ela continua informando como terminou a última atualização entregue pelo Servidor.

Um valor de política que ela não consegue ler a desliga, em vez de impedir a inicialização. Um REG_SZ com "0", por exemplo, que um item de Registro das Preferências de Política de Grupo grava com mais facilidade que o REG_DWORD do ADMX, deixa a máquina assinando e sem receber versão nenhuma, com uma linha Error citando o local. Impedir a inicialização derrubaria a assinatura em toda a frota por causa de uma chave que só controla atualizações.

Lido uma vez, na inicialização, como todo valor do Registro.

O Relatório da Estação de Trabalho

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

WorkstationReport:Enabled

Padrão true · Instalação na frota o MSI grava WORKSTATION_REPORT em HKLM\Software\TrustBridge\WorkstationReport (0 desligado, 1 ligado; sem valor, não grava nada em uma primeira instalação, o que é ligado, e mantém o valor da própria máquina em uma atualização ou um reparo); a Política de Grupo o sobrepõe em HKLM\Software\Policies\TrustBridge\WorkstationReport, um REG_DWORD que a política Informar a situação desta máquina ao TrustBridge Server fornecida grava · Valor inválido no Registro, qualquer coisa que não seja 0 ou 1 é lida como desligada e registrada em Error; em um arquivo de configuração, impede a inicialização

Se esta máquina envia ao Servidor dela o Relatório da Estação de Trabalho (Workstation 1.8.0): a situação dela, que a tela Estações de Trabalho, o Painel e a tela Relatórios das Estações de Trabalho do Servidor mostram ao suporte. Ele traz a licença da PKI que a máquina tem e o runtime do .NET dela, as opções, os middlewares de token que ela consultou (cada um com o caminho, a versão do arquivo e se carregou), os tokens (fabricante, modelo, número de série e o quanto cada PIN está perto de bloquear), as leitoras de cartão que o Windows deixou com falha, e as linhas Error e Critical que o serviço e o Tray App registraram, agrupadas por origem, categoria de log e modelo de mensagem, com uma contagem.

A partir do Workstation 1.10.0, ele também traz o console: a conta do Windows conectada à sessão do console, a Conta no console (o SID dela e, quando é possível resolvê-lo, o DOMAIN\user), ou ninguém; se essa sessão está bloqueada; se há um Tray App conectado ali, e a versão dele; e quantas outras sessões têm um Tray App conectado, sem as contas delas. O próprio serviço lê a conta e o bloqueio, então eles são informados mesmo sem nenhum Tray em execução. A tela Estações de Trabalho o mostra na coluna Conta no console a partir do Servidor 1.23.0; um Servidor anterior o ignora.

Ligado, a máquina informa depois de cada handshake e de novo alguns segundos depois que algo nela muda, entre outras coisas um login, um logoff, um bloqueio ou desbloqueio, uma troca de usuário no console e um Tray App que se conecta ou se desconecta. Um relatório nunca custa à máquina a conexão, a detecção, a assinatura nem o Cache de PIN; as falhas do próprio relatório são registradas em Warning.

Entregue-o com o Servidor 1.20.0 ou posterior. Um Servidor anterior ao relatório responde que não o tem e não é chamado de novo, mas só a partir da 1.20.0 o Servidor aceita mensagens de estação de trabalho de até 1 MB; um anterior fecha a conexão de um relatório acima de 32 KB, que uma máquina no Workstation 1.8.0 com muitos tokens, middlewares ou erros pode enviar. A partir do Workstation 1.8.1, a máquina mantém os relatórios abaixo de 32 KB até que o Servidor tenha recebido um. Veja Qual Servidor uma versão exige.

Desligado, nada da situação da máquina sai dela, incluindo a Conta no console e o resto do console. Ela continua informando depois de cada handshake, para que o silêncio dela nunca seja lido como uma máquina saudável, mas o relatório diz apenas que está desligado. O Servidor então esquece tudo o que a máquina informou antes, e a tela Estações de Trabalho a mostra como Sem relatório. A assinatura, a detecção de certificados e o Cache de PIN não são afetados em nenhum dos casos. A partir dos modelos do Workstation 1.10.0, a explicação da política Informar a situação desta máquina ao TrustBridge Server cita a conta do Windows conectada ao console entre o que o relatório traz, nos dois idiomas.

Um valor ilegível é lido como desligado, e a inicialização continua, como acontece com uma política ServerUpdates ilegível: desligado é a leitura que não envia nada. O log de inicialização diz qual fonte forneceu o valor. Lido uma vez, na inicialização: um Service que inicia com ele ligado de novo envia o relatório completo logo depois do handshake.

Detecção de certificados

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

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. Um valor não positivo impede a inicialização.
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.

Certificates:RestartFailedReaders

Padrão true · Instalação na frota o MSI grava RESTART_FAILED_READERS em HKLM\Software\TrustBridge\RestartFailedReaders (0 desligado, 1 ligado; sem valor, não grava nada em uma primeira instalação, o que é ligado, e mantém o valor da própria máquina em uma atualização ou um reparo); a Política de Grupo o sobrepõe em HKLM\Software\Policies\TrustBridge\RestartFailedReaders, um REG_DWORD que a política Reiniciar uma leitora de cartão que o Windows não conseguiu iniciar fornecida grava · Valor inválido no Registro, qualquer coisa que não seja 0 ou 1 é lida como desligada e registrada em Error; em um arquivo de configuração, impede a inicialização

Se o serviço reinicia uma leitora com falha (Workstation 1.8.0): uma leitora de cartão que o Windows não conseguiu iniciar, de modo que nenhum token nela pode ser visto. Alguns tokens USB são a própria leitora, e o driver nativo do Windows às vezes deixa essa leitora com o código de problema 10 quando o token é conectado. Ligada, o serviço reinicia essa leitora sozinho, até três vezes a cada vez que ela é conectada, e somente uma leitora USB com o código de problema 10. Só desconectar a leitora lhe dá uma nova série de tentativas. Cada reinicialização e o resultado dela são uma linha no log do serviço. Ele nunca pede elevação e nunca reinicia a máquina: uma reinicialização que o Windows diz exigir reiniciar a máquina conta como falha.

Enquanto ele tenta, a aba Tokens do Tray App diz O Windows não conseguiu iniciar uma leitora de cartão. O TrustBridge está reiniciando-a (tentativa 1 de 3). Uma leitora que continua com falha depois das tentativas, ou qualquer leitora com falha enquanto a reinicialização está desligada, recebe Uma leitora de cartão está conectada, mas o Windows não conseguiu iniciá-la. Desconecte-a e conecte-a novamente.

Desligada, nada é reiniciado: a aba Tokens pede de imediato que a leitora seja desconectada e conectada de novo, que é o que toda máquina fazia antes de a reinicialização existir, e a linha de log que cita a leitora com falha diz que a reinicialização está desligada. Uma implantação cuja política proíbe que software altere o estado de dispositivos a desliga sem precisar de uma nova versão.

Só uma máquina que procura tokens A3 a lê. Com Certificates:Pkcs11:Modules definido como vazio, ou sem nenhum dos middlewares da lista fornecida instalado, o serviço não lista nenhum dispositivo de leitora e não reinicia nada, seja o que for que esta chave diga.

Um valor ilegível é lido como desligado, e a inicialização continua, como acontece com uma política ServerUpdates ilegível: desligado é a reconexão manual que o titular já fazia, e a incerteza nunca deve ser o que altera um dispositivo. O log de inicialização diz qual fonte forneceu o valor. Lido uma vez, na inicialização.

Os repositórios de certificados

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

O que os leitores anunciam. Um certificado é uma identidade de assinatura quando tem chave privada e um titular ICP-Brasil legível: um e-CPF, ou um e-CNPJ com o CPF do responsável e a Empresa (CNPJs alfanuméricos incluídos). Todo o resto é ignorado. Um e-CNPJ é anunciado, com a Empresa, somente a um Servidor cujo handshake diga que os aceita (Servidor 1.13.0 e posteriores), e nunca como o e-CPF do responsável. Com um Servidor mais antigo, o Tray App lista o e-CNPJ como não anunciado, com o motivo. A lista e o detalhe de certificados do Tray App mostram a Empresa, e a solicitação de PIN de uma sessão de uma Empresa mostra em nome de qual Empresa se está assinando.

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 da máquina. 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 assina depois que um PIN do Certificado A1 é definido para ele naquela máquina. Alguém no console da máquina o define no Tray App (Definir PIN do Certificado A1… e, depois, Alterar PIN do Certificado A1…, que pede o atual); um A1 recém-detectado sem PIN pede uma vez ao titular que defina um. A partir daí, o PIN de uma aplicação cliente é conferido com esse PIN do Certificado A1 da mesma forma que o PIN de um token é conferido com o Cache de PIN, e o serviço assina com a chave do certificado sem ninguém junto à máquina. Até que um seja definido, o certificado é anunciado e listado, e as sessões sobre ele terminam em PIN_NOT_AVAILABLE.

O serviço nunca guarda o PIN do Certificado A1 em si, só um verificador PBKDF2, em C:\ProgramData\TrustBridge\, com as permissões do Cache de PIN. Um PIN do Certificado A1 atual errado conta para Tray:MaxConsecutivePinFailures. Um PIN do Certificado A1 é excluído quando o certificado some do repositório por duas varreduras seguidas, e na hora se um token aparecer com o mesmo certificado. Uma atualização o mantém; uma desinstalação de verdade o exclui. Nada disso é configurado: a chave controla se o repositório é lido, e o PIN do Certificado A1 é por certificado, por máquina, definido por quem estiver no console primeiro.

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. Um módulo listado que não existe, é da arquitetura errada ou não é um módulo PKCS#11 conta como falha desse repositório, com o motivo no log. É 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.

A aba Tokens do Tray App é onde se confere o resultado. Ela mostra um cartão por token que a última varredura de detecção viu (rótulo, número de série, modelo, o middleware que o leu, se há PIN armazenado, os certificados nele), os middlewares consultados pelo serviço e os que falharam, e uma linha citando qualquer leitora com um cartão que nenhum middleware instalado lê, ou um cartão que não responde. A partir do Workstation 1.8.0, ela também avisa quando o Windows não conseguiu iniciar uma leitora de cartão (Certificates:RestartFailedReaders).

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": {
      "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 nunca definida na máquina: o Servidor compartilha a própria licença com toda máquina Admitida a cada handshake · Valor inválido uma licença vencida ou corrompida gera uma linha Critical, nunca uma inicialização recusada

Obrigatória em todas as máquinas, essa é a primeira diferença em relação ao Servidor, e é o Servidor que a fornece. 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. Uma máquina Admitida recebe a própria Certificates:Validation:License do Servidor na resposta a cada handshake e a aplica antes de anunciar qualquer certificado. Ela fica só em memória, nunca é gravada no disco da máquina e substitui qualquer valor definido aqui.

Nada que uma instalação na frota grava fornece uma, e isso é proposital. Nenhuma propriedade do MSI e nenhum valor de Política de Grupo traz uma licença. Renová-la é uma alteração e um reinício no Servidor, que toda máquina conectada adota ao se reconectar, e uma máquina offline no próximo handshake. Uma máquina revogada ou devolvida a Pendente mantém a licença que recebeu até o serviço dela reiniciar.

O que a máquina informa. Sem nada definido aqui, a linha de inicialização é Information, aguardando o Servidor, que é a inicialização normal de uma máquina instalada. Uma licença enviada pelo Servidor que o SDK recusa gera Critical uma vez por valor distinto, assim como um Servidor que aceita o handshake mas não envia nenhuma. O Tray App mostra uma linha acima da lista de certificados dizendo por que a máquina está sem licença: aguardando o Servidor (Pendente, nunca admitida ou offline desde a inicialização), a licença do Servidor foi recusada, o Servidor não enviou nenhuma, ou uma licença que esta máquina não conseguiu aplicar.

Um valor definido aqui, em um arquivo de configuração ou como Certificates__Validation__License, é só para a execução de um desenvolvedor no console: a licença em base64 em uma linha, que a do Servidor substitui assim que ele responde.

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 é uma alteração no arquivo de configuração de cada máquina, que convém fazer antes de a máquina se conectar ao Servidor pela primeira vez. 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 ou em uma cujo Servidor não tem Autoridades Certificadoras Confiáveis.

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 (e não a licença); 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

O handshake é onde esta máquina recebe a licença da PKI e o conjunto de Autoridades Certificadoras Confiáveis, então uma diferença de versão decide se a máquina consegue ler um certificado. O Workstation 1.6.0 introduziu o protocolo 6, que acrescenta a Autorização de assinatura: para uma Aplicação Cliente com o PIN por transação ligado, o Servidor pede o PIN ao Tray desta máquina a cada chamada de assinatura. O protocolo 5, anterior a ele, é aquele em que o Servidor deixou de enviar a qualquer máquina o PIN da aplicação cliente: ele desafia a máquina com um nonce, e a máquina responde com uma Prova de PIN (PIN Proof) calculada sobre o PIN que tem em cache, ou sobre o verificador de um PIN do Certificado A1, para o Servidor conferir. Um Servidor aceita o próprio protocolo e o anterior.

• Esta máquina à frente do Servidor: ela não se conecta. Um Servidor anterior à 1.15.0 recusa o handshake (Protocol version 6 is newer than this server's supported window (4–5); update the Server first). Este serviço registra esse veredito no log, desconecta e tenta de novo com backoff. Sem um Servidor que lhe entregue a licença, todo certificado desta máquina aparece como UNTRUSTED, e ela não consegue assinar até que o Servidor seja atualizado.
• Um Servidor à frente de uma máquina: ela se conecta e atende toda sessão, exceto as com PIN por transação. Um Servidor 1.15.0 ou posterior deixa uma máquina no Workstation 1.5.0 (protocolo 5) fazer o handshake e atender toda sessão como antes, mas nunca a escolhe para uma sessão cuja Aplicação Cliente tem o PIN por transação ligado. Uma máquina na 1.4.x ou anterior é recusada com update required.

Do Workstation 1.7.0 ao 1.10.0, todos mantêm o protocolo 6, então o que está acima vale para eles sem mudança, com mais uma condição a partir do 1.8.0: entregue-o com o Servidor 1.20.0 ou posterior, o primeiro Servidor que recebe o Relatório da Estação de Trabalho dele; um anterior fecha a conexão de um relatório do 1.8.0 acima de 32 KB. O que o 1.9.0 e o 1.10.0 acrescentam vai no protocolo 6 como campos opcionais que um Servidor anterior ignora, e o console do 1.10.0 aparece na tela Estações de Trabalho a partir do Servidor 1.23.0.

Por isso, a regra é primeiro o Servidor, depois a frota: veja Qual Servidor uma versão exige. Os PINs em cache, os PINs de Certificado A1 e a admissão da máquina passam pela atualização como estão. O Workstation 1.7.0 acrescentou Tray:InsertionPrompt, e o 1.8.0 acrescentou WorkstationReport:Enabled e Certificates:RestartFailedReaders, todas ligadas por padrão; do 1.8.1 ao 1.10.0 nenhuma chave foi acrescentada, e nenhuma foi renomeada nem removida.

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, exceto em Tray:InsertionPrompt, que uma propriedade do MSI ou uma Política de Grupo desliga.

{
  "Tray": {
    "PipeName": "TrustBridge.WorkstationService",
    "PromptTimeout": "00:01:30",
    "InsertionPrompt": true,
    "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	O limite da própria máquina para a solicitação de PIN de uma sessão. O Sessions:PinPromptTimeout do Servidor (60 s) é o que normalmente encerra uma solicitação: quando ele se esgota, o Servidor retira a solicitação da máquina. Esta janela, mais folgada, é o que encerra uma solicitação que o Servidor não consegue mais acessar, como uma em uma máquina que perdeu a conexão, e também limita quanto tempo uma digitação aguarda o veredito do Servidor sobre a prova dela. Mantenha-a mais longa que a do Servidor. Um pedido de PIN por transação é limitado, em vez disso, pela janela que o Servidor envia com ele (Signing:AuthorizationTimeout). Um valor não positivo impede a inicialização.
Tray:MaxConsecutivePinFailures	3	Quantos PINs podem ser rejeitados seguidamente para um certificado antes que as entradas para ele sejam recusadas sem ser verificadas: um token que os rejeita ou, para um Certificado A1, PINs do Certificado A1 errados (inclusive um PIN atual errado ao alterá-lo). 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, e a espera se encerra sozinha, para um token e para um A1.
Tray:LogBufferSize	500	Quantas entradas recentes de log o serviço guarda para a aba Log do Tray. Somente em memória.

Tray:InsertionPrompt

Padrão true · Instalação na frota o MSI grava INSERTION_PROMPT em HKLM\Software\TrustBridge\InsertionPrompt (0 desligado, 1 ligado; sem valor, não grava nada em uma primeira instalação, o que é ligado, e mantém o valor da própria máquina em uma atualização ou um reparo); a Política de Grupo o sobrepõe em HKLM\Software\Policies\TrustBridge\InsertionPrompt, um REG_DWORD que a política Pedir o PIN do token na inserção fornecida grava · Valor inválido no Registro, qualquer coisa que não seja 0 ou 1 é lida como desligada e registrada em Error; em um arquivo de configuração, impede a inicialização

Se a inserção de um token abre um Pedido de PIN na inserção (Workstation 1.7.0): a janela de PIN, aberta sozinha em um console desbloqueado para um token cujo PIN não está em cache, para que as assinaturas seguintes não precisem de pedido. O que o token aceita fica no Cache de PIN para todo certificado nele. A janela, com o título Digite o PIN do token que você inseriu, mostra o token, a leitora dele e, para cada certificado nele, o titular ou, em um e-CNPJ, a Empresa e o CPF do responsável. O titular digita o PIN, escolhe Agora não ou deixa a janela fechar no fim da contagem regressiva de 90 segundos que todo pedido tem; um PIN errado é digitado de novo na mesma janela, sob o mesmo limite de PINs rejeitados de toda digitação de PIN.

Ele é oferecido uma vez por inserção, e só para um token que lista pelo menos um certificado ACTIVE, não está com o PIN bloqueado e cujo PIN não está em cache; nunca para um Certificado A1, para os cartões que já estavam inseridos quando o Tray App se conecta, nem para um token que não lista nada sem login. Ele nunca abre atrás da tela de bloqueio: um token inserido com o console bloqueado é oferecido no desbloqueio, se ainda estiver inserido e com o PIN ainda fora do cache. Um pedido de PIN de sessão ou um pedido de PIN por transação que chegue por cima dele toma a tela, e o Pedido de PIN na inserção volta quando a tela fica livre. Ele se fecha sozinho se o token for retirado ou se o PIN dele entrar no cache por outro caminho. Ele nunca chega ao Servidor e nunca autoriza uma chamada de assinatura por transação, que continua pedindo o PIN no Tray App a cada vez.

Entregue o Workstation 1.8.1 ou posterior onde ele estiver ligado. No 1.7.0 e no 1.8.0, um pedido de PIN que se fechava (entre eles, um Pedido de PIN na inserção respondido, recusado ou expirado) podia encerrar um Tray App cuja janela não tinha sido aberta desde o login, deixando a sessão sem Tray até o logoff, e uma chamada por transação ali era recusada com NO_TRAY. A partir do 1.8.1, o Tray App só termina quando alguém pede: pelo Sair do menu dele, ou com a janela fechada quando ele não tem um ícone pelo qual voltar.

Desligado, o balão do token é exatamente o que era antes de o pedido existir: o serviço não oferece nenhum Pedido de PIN na inserção e avisa o Tray App disso quando ele se conecta, e o Tray App continua convidando o titular a digitar o PIN por uma notificação. Uma área de trabalho em que a janela não é bem-vinda o desliga sem precisar de uma nova versão. Ligado, o balão deixa de aparecer para todo token inserido, não só para aqueles para os quais a janela abre: um token para o qual o serviço não oferece pedido (com o PIN bloqueado, que exige login antes de listar qualquer coisa, sem nenhum certificado que já possa assinar) não é anunciado por nenhum dos dois. Os certificados dele continuam chegando à lista do Tray App, e Digitar PIN… ali continua pondo o PIN dele em cache.

Um valor ilegível é lido como desligado, e a inicialização continua, como acontece com uma política ServerUpdates ilegível: desligado é o balão que toda máquina tinha antes. O log de inicialização diz qual fonte forneceu o valor e cita um valor ilegível em Error, ou em Warning, citando a fonte que o sobrepõe, quando uma política legível fornece a chave. Lido uma vez, na inicialização.

O pedido de PIN por transação

Para uma Aplicação Cliente com o PIN por transação ligado, toda chamada de assinatura sob uma sessão vinculada a esta máquina abre um pedido de PIN no Tray App da sessão do console, com o título Uma transação de assinatura precisa do seu PIN. Ele mostra a Aplicação Cliente que pede e o que ela vai assinar: o número de hashes, ou o número de documentos e os cinco primeiros pelo nome (cada um cortado em uma linha de no máximo 80 caracteres, seguido de e mais N) e, para um e-CNPJ, em nome de quem. O titular digita o PIN do token ou o PIN do Certificado A1 e escolhe Autorizar ou Recusar; um PIN que o token recusa é digitado de novo na mesma janela.

Nada nesta página o configura. Um pedido de PIN por transação nunca aparece ao lado de outro pedido: o que chega por segundo espera a vez dentro da própria janela. Acima de dezesseis esperando ou sendo exibidos ao mesmo tempo, um novo é recusado sem ser exibido. O PIN aceito fica em memória só para aquela chamada, e o pedido é respondido com NO_TRAY quando não há um Tray App no console que possa exibi-lo, o que o cliente vê como PIN_NOT_AVAILABLE (no Tray at the console).

A partir do Workstation 1.9.0, a máquina diz o motivo, ao lado do NO_TRAY: um Tray em uma sessão que não é a do console (Área de Trabalho Remota, ou um console trocado), nenhum Tray App conectado em lugar nenhum, um Tray no console antigo demais para mostrar uma transação, uma instalação começando, um Tray no console que não está lendo, o Tray se desconectando enquanto o pedido estava aberto, ou o serviço parando. A partir do 1.10.0, um pedido de PIN de sessão que a máquina não conseguiu mostrar também diz o motivo, com um que só ele tem: todo certificado que ela poderia oferecer é um Certificado A1 sem PIN do Certificado A1 definido. A recusa que o cliente recebe não muda; a Trilha de Auditoria registra o motivo a partir do Servidor 1.22.0, e a tela Estações de Trabalho do console administrativo o descreve em palavras a partir do Servidor 1.23.0.

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á.

O PIN nunca vem do Servidor. Um PIN só chega ao cache pelo titular, no Tray App desta máquina, depois que o token o aceitou. Na criação de uma sessão, o Servidor envia um nonce, e a máquina responde com uma prova calculada com o PIN em cache; o Servidor decide se ela confere com o PIN da aplicação cliente e avisa a máquina quando uma sessão foi vinculada por meio dela.

{
  "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, inclusive ao reinício causado por uma atualização entregue pelo Servidor. 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.

Os PINs de Certificado A1 não fazem parte do Cache de PIN e não são afetados por esta chave: eles ficam no disco até o certificado sair da máquina ou o pacote ser desinstalado.

O restante do Cache de PIN

Chave	Padrão	Significado
PinCache:Ttl	8 h	Quanto tempo uma entrada permanece válida sem ser usada. Deslizante: cada sessão vinculada por meio dela renova a expiração, então um usuário ativo todo dia nunca é solicitado de novo. Um PIN digitado para uma chamada por transação nunca entra no cache e não renova nenhuma entrada. 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. A única opção de linha de comando dele, --background (Workstation 1.9.0), é a da entrada de inicialização automática: iniciado com ela, o Tray mostra só o ícone e sai sem aviso ao lado de um Tray da sessão que responde; iniciado sem ela, pelo atalho TrustBridge do menu Iniciar ou pelo executável, ele abre a janela (veja Instalação da estação de trabalho).

Ele também não grava arquivo de log, de propósito: a linha de log de uma solicitação cita um CPF, e um arquivo no perfil de cada usuário fica onde uma desinstalação não alcança. O que o Tray App registra fica em memória e aparece na aba Log, ao lado das linhas do serviço, e só sai da máquina pelo Exportar… dessa aba. As linhas dele terminam quando o Tray App termina, então exporte antes que alguém o reinicie.