Instalação da estação de trabalho

Um MSI, uma linha de msiexec, e uma máquina limpa passa a aguardar na fila de admissão. O pacote TrustBridge-Workstation-<version>-x64.msi traz os dois componentes da estação de trabalho, o Workstation Service e o Tray App, publicados como autocontidos (self-contained), então uma máquina sem runtime do .NET não precisa de nada instalado antes. Junto com ele, a Lacuna Software fornece TrustBridge-Workstation-GroupPolicy-<version>.zip, com os modelos de Diretiva de Grupo.

Esta página é o que o operador digita. A página Configuração da estação de trabalho é o que cada valor pode dizer: cada configuração que o serviço aceita, o padrão dela e o que um valor inválido provoca.

Antes de começar

• Uma máquina Windows de 64 bits e direitos administrativos nela. O pacote é por máquina, somente x64, e exige o Windows Installer 5.0 (Windows 7 e posteriores). ARM64 não é suportado.
• Nada mais instalado. Os dois componentes são autocontidos, e é por isso que o pacote tem cerca de 100 MB.
• A URL do Servidor, acessível a partir da máquina. O único valor sem o qual a instalação se recusa a prosseguir.
• A licença do PKI SDK, o conteúdo inteiro de um LacunaPkiLicense.config codificado em base64 em uma linha. O instalador não a exige, e uma máquina sem ela não valida nada e não assina nada.
• Um Administrador que vá admitir a máquina. Instalar não faz a máquina entrar na frota; uma pessoa faz isso, no Servidor.
• Uma cadeia TLS em que a máquina confie. O Workstation Service recusa um certificado de Servidor não confiável, e o sintoma é uma máquina que nunca aparece na fila.

A linha única

msiexec /i TrustBridge-Workstation-1.0.1-x64.msi /qn SERVER_URL=https://trustbridge.example.com PKI_LICENSE=<base64>

Essa é uma instalação completa para a frota. Em ordem, ela:

1. Verifica SERVER_URL e faz a transação inteira falhar se o valor estiver vazio ou não começar com um esquema.
2. Coloca os dois componentes em C:\Program Files\TrustBridge\, cria a árvore de estado da máquina em C:\ProgramData\TrustBridge\, com uma DACL que só admite Administradores e LocalSystem, e registra a entrada de inicialização automática do Tray App.
3. Grava a configuração da instalação em HKLM\Software\TrustBridge.
4. Registra o TrustBridge Workstation Service no SCM (LocalSystem, inicialização automática, reinício em caso de falha) e o inicia, aguardando a inicialização ser bem-sucedida.
5. O serviço gera a Chave da Estação de Trabalho no TPM da máquina (recorrendo ao provider de software, se necessário), se anuncia ao Servidor e fica Pendente na fila de admissão.

O último ato da instalação é o serviço subir. Um serviço que se recusa a iniciar (uma licença que o SDK não lê, uma INSTALLER_KEY que não é uma chave) faz a instalação falhar e ser revertida, em vez de deixar uma máquina que parece instalada e nunca se conecta.

O msiexec não espera. Ele retorna imediatamente, e a linha seguinte de um script de implantação é executada enquanto a instalação ainda está em andamento. Para ler o resultado, aguarde o processo:

$install = Start-Process msiexec -Wait -PassThru -ArgumentList @(
    '/i', 'TrustBridge-Workstation-1.0.1-x64.msi',
    '/qn',
    '/l*v', 'C:\Windows\Temp\trustbridge-install.log',
    'SERVER_URL=https://trustbridge.example.com',
    'PKI_LICENSE=PD94bWwgdmVyc2lvbj0…'
)
$install.ExitCode

Os códigos de saída são os do próprio Windows Installer: 0 sucesso, 1602 cancelado, 3010 sucesso com algo pedindo reinicialização, 1603 erro fatal, que é como as duas recusas próprias deste pacote aparecem. O motivo é uma linha do log /l*v; procure nele por SERVER_URL ou newer version.

As três propriedades

As três são gravadas em HKLM\Software\TrustBridge como valores de Registro, e não em um arquivo de configuração, e é isso que as faz sobreviver a uma atualização sem nenhum mecanismo para lembrar propriedades.

Propriedade	Valor no Registro	Chave de configuração
SERVER_URL	ServerUrl	Server:Url	Obrigatória, a menos que o build traga um padrão embutido. Controlada pela condição de inicialização.
PKI_LICENSE	PkiLicense	Certificates:Validation:License	Opcional para o instalador; uma máquina sem ela não assina nada.
INSTALLER_KEY	InstallerKey	Server:InstallerKey	Opcional. A maioria das implantações nunca a passa.

PKI_LICENSE só é opcional no sentido de que o MSI não a verifica. Sem licença, todo certificado da máquina aparece como UNTRUSTED, e o serviço avisa isso uma vez na inicialização. Passe-a, ou publique-a por Diretiva de Grupo antes que se espere que a máquina funcione.

INSTALLER_KEY é para uma implantação que gerou uma Installer Key própria e configurou a metade pública dela no Servidor, em Admission:InstallerKeys. Se não for definida, nenhum valor é gravado e vale a chave do próprio produto. Ela não é um segredo e não admite nada sozinha.

Nenhuma das três deve precisar de aspas. Uma URL não tem espaços, e a licença e a chave são base64 em uma linha.

A condição de inicialização

SERVER_URL precisa estar presente e começar com http:// ou https://, ou a transação falha antes que qualquer coisa seja gravada. Vale para instalações silenciosas e interativas; para instalação, atualização e reparo, embora uma atualização e um reparo a satisfaçam com o valor que a própria máquina já tem, sem que você precise passar nada. A única transação que ela não controla é a remoção. Um serviço que se recusasse a iniciar seria uma máquina em loop de falhas, descoberta quando alguém não conseguisse assinar; uma instalação recusada é uma falha única e visível enquanto alguém está acompanhando.

Um build pode trazer uma URL de Servidor padrão embutida; assim, a linha para a frota passa a ser msiexec /i <msi> /qn e o campo interativo já vem preenchido. Um valor na linha de comando continua prevalecendo, assim como o valor que a máquina já tem.

O que uma instalação coloca na máquina

C:\Program Files\TrustBridge\Workstation Service\	O serviço e o runtime autocontido dele
C:\Program Files\TrustBridge\Tray App\	O Tray App e o runtime próprio dele
C:\ProgramData\TrustBridge\	O estado da máquina: o Cache de PIN, o chaveiro dele, o conjunto de Autoridades Certificadoras Confiáveis em cache. Somente Administradores e LocalSystem
C:\ProgramData\TrustBridge\anchors\	Onde ficam os arquivos de âncora de confiança, com a mesma DACL
HKLM\Software\TrustBridge	Os três valores definidos na instalação
HKLM\…\CurrentVersion\Run → TrustBridge Tray App	Inicialização automática para toda a máquina, para que o Tray seja executado para todo usuário interativo
Serviço TrustBridge Workstation Service	LocalSystem, automático, reinicia três vezes em caso de falha, em intervalos de um minuto
Origem de eventos de Aplicativo TrustBridge Workstation Service	Onde são gravados uma recusa ocorrida antes de o log existir e o relatório de limpeza de uma desinstalação

O diretório de instalação é fixo. A Chave da Estação de Trabalho não está nesta tabela porque o serviço a gera em um container CNG na primeira vez que inicia, e nada além do próprio verbo de limpeza do serviço consegue removê-la.

O Tray App só aparece no próximo login. Em uma máquina em que alguém já está conectado, o ícone aparece depois que a pessoa sai e entra de novo, ou quando Tray App\TrustBridge.TrayApp.exe é iniciado manualmente. Enquanto ele não estiver em execução, não há ninguém para responder a uma solicitação de PIN.

Instalando interativamente

Clicar duas vezes no MSI mostra uma tela própria deste pacote entre as telas padrão de progresso e de conclusão: em uma máquina limpa, um único campo Server URL, associado à mesma propriedade SERVER_URL; em uma máquina que já tem o pacote, uma tela para reparar, reapontar ou remover, com o campo já preenchido. Não há EULA, seletor de diretório nem árvore de recursos. As caixas de diálogo são somente em inglês, de propósito: são ferramentas de implantação para o operador. O Tray App que o usuário vê fala o idioma do usuário.

A licença e a Installer Key não têm campo. Forneça-as a uma máquina interativa isolada por uma linha de reparo silencioso ou por Diretiva de Grupo.

Admitindo a máquina

Instalar não faz a máquina entrar na frota. A máquina se anuncia e aguarda, Pendente, até que um Administrador a torne Admitida na fila de admissão, em /admin/admission. Até lá, o serviço está em execução, acessando o Servidor e sem se conectar a nada; o log dele diz o motivo a cada reconexão, e o Tray App mostra Ainda não admitida.

O que admitir significa é limitado, e a tela diz isso: sem um canal externo (out-of-band) com que conferir uma impressão digital, admitir é uma barreira humana, com limite de requisições, sobre uma fila. Uma máquina é notada, e não verificada. O que torna isso aceitável é que a etapa não é opcional; nada que a máquina tenha a admite sozinha. Leia o nome do host, o sistema operacional, as versões e a postura da chave (em hardware ou em software) da máquina antes de admiti-la.

Depois de admitida, a máquina se conecta na próxima tentativa de reconexão e aparece na tela Estações de Trabalho, em /admin/fleet. Uma máquina devolvida a Pendente mantém a chave e o histórico; uma máquina Revogada é recusada permanentemente e não tem como voltar, exceto como uma máquina nova, com uma chave nova.

Uma requisição Pendente abandonada expira depois de Admission:PendingExpiry (7 dias por padrão, contados a partir da última requisição da máquina), e a linha dela é excluída. Isso não é uma recusa; a máquina simplesmente pede de novo, como uma que a plataforma nunca viu.

Se a máquina nunca aparece na fila

Leia primeiro o que o próprio serviço registra: o log Aplicativo do Windows, origem TrustBridge Workstation Service, e o log do serviço. Quatro coisas fazem uma requisição de admissão ser recusada, e o Servidor deliberadamente não diz qual, então o log da máquina cita as quatro: a máquina foi revogada; a Installer Key dela não é uma em que este Servidor confia; vieram requisições demais do endereço dela; ou a fila está cheia. As duas últimas se resolvem sozinhas.

O serviço informa de onde veio cada um dos três valores definidos na instalação, a cada inicialização, uma linha por valor, no formato Server:Url is https://…, supplied by …. Leia isso antes de mexer no Registro.

sc.exe query "TrustBridge Workstation Service"
Get-ItemProperty 'HKLM:\Software\TrustBridge'
Get-ItemProperty 'HKLM:\Software\Policies\TrustBridge' -ErrorAction SilentlyContinue

Execute esses comandos em um PowerShell de 64 bits. A preferência fica na visão de 64 bits do Registro; um host de 32 bits é redirecionado para WOW6432Node, onde uma máquina perfeitamente configurada parece vazia.

São dois locais, porque o segundo prevalece: um valor de Diretiva de Grupo em HKLM\Software\Policies\TrustBridge vence o que o instalador gravou, e uma máquina apontando para o Servidor errado normalmente é uma máquina no escopo de uma GPO de que alguém se esqueceu. Os dois são lidos uma vez, na inicialização.

Diretiva de Grupo: implantando os modelos

O modelo ADMX permite que um domínio defina dois valores em toda a frota: Server:Url e Certificates:Validation:License. Ele nunca é instalado pelo MSI: nada que o pacote grava pode ficar em \Policies, porque o processamento de diretivas exclui os valores que deixa de gerenciar. Descompactado, o arquivo de modelos da versão tem três arquivos:

admx\TrustBridge.admx
admx\en-US\TrustBridge.adml
admx\pt-BR\TrustBridge.adml

Copie-os para o repositório central do domínio, incluindo as pastas de idioma:

$store = "\\$env:USERDNSDOMAIN\SYSVOL\$env:USERDNSDOMAIN\Policies\PolicyDefinitions"
New-Item -ItemType Directory -Force -Path $store, "$store\en-US", "$store\pt-BR" | Out-Null
Copy-Item admx\TrustBridge.admx $store
Copy-Item admx\en-US\TrustBridge.adml "$store\en-US"
Copy-Item admx\pt-BR\TrustBridge.adml "$store\pt-BR"

A linha New-Item não é mera formalidade: Copy-Item para uma pasta que não existe cria um arquivo com esse nome, e um repositório nesse estado fica quebrado de um jeito de que nada reclama. Uma máquina sem repositório central recebe os mesmos três arquivos em %SystemRoot%\PolicyDefinitions. De qualquer forma, as configurações aparecem em Configuração do Computador → Modelos Administrativos → TrustBridge Workstation.

Copie os dois idiomas, mesmo que os seus administradores leiam inglês. O gpedit recorre ao idioma alternativo por arquivo, e não por string, então um repositório sem pt-BR\TrustBridge.adml faz um console em português perder o modelo inteiro.

Uma alteração de diretiva exige reiniciar o serviço, não atualizar a Diretiva de Grupo. O serviço lê os dois locais do Registro uma vez, na inicialização. O gpupdate /force entrega o valor, e a máquina o adota na próxima inicialização do serviço:

Restart-Service "TrustBridge Workstation Service"

Renovar a licença é a razão de ser da segunda diretiva. Sem uma licença válida, todo certificado de toda máquina aparece como UNTRUSTED, então um vencimento seria, de outra forma, uma indisponibilidade em toda a frota, resolvida executando o MSI de novo em todas as máquinas. Publicada como diretiva, é uma atualização e uma onda de reinícios.

Não há, de propósito, diretiva para a Installer Key: uma troca de chave é uma implantação em etapas (informe a chave nova ao lado da antiga no Servidor, atualize as máquinas, remova a entrada antiga), e não uma atualização de GPO.

Reparando e reapontando

Um reparo reinstala o pacote e regrava os três valores de Registro a partir das propriedades, e é assim que você altera a configuração de instalação de uma máquina sem desinstalá-la:

# Repair: put back what a machine lost, keeping its current configuration.
msiexec /i TrustBridge-Workstation-1.0.1-x64.msi /qn REINSTALL=ALL REINSTALLMODE=ecmus

# Re-point: the same transaction, with a new value.
msiexec /i TrustBridge-Workstation-1.0.1-x64.msi /qn REINSTALL=ALL REINSTALLMODE=ecmus `
    SERVER_URL=https://trustbridge-2.example.com

Uma propriedade que você não passa é lida de novo da máquina e regravada sem alteração. O serviço é parado e iniciado pela transação, então um reapontamento entra em vigor quando o reparo termina. A máquina mantém a Chave da Estação de Trabalho, então é a mesma estação de trabalho para o Servidor dela. Um reapontamento para um Servidor diferente chega à fila desse Servidor como uma nova máquina Pendente.

Atualizando

Um MSI mais novo se instala sobre um mais antigo. Esse é o procedimento inteiro.

msiexec /i TrustBridge-Workstation-1.1.0-x64.msi /qn

Nenhuma propriedade é necessária; o pacote novo lê os valores existentes da máquina antes de o produto antigo ser removido e os grava de volta. Uma máquina atualizada é a mesma estação de trabalho:

Sobrevive a uma atualização	Por quê
A Chave da Estação de Trabalho	Ela fica em um container CNG que nenhuma tabela do instalador cita
O Cache de PIN, o chaveiro dele, o conjunto de Autoridades Certificadoras Confiáveis em cache	Arquivos em C:\ProgramData\TrustBridge\ que nenhum componente inclui
ServerUrl, PkiLicense, InstallerKey	Regravados a partir dos valores da própria máquina
A interface em pt-BR	Os assemblies satélites são substituídos, e não deixados para trás

O Tray App é fechado pelo instalador durante o processo, então uma atualização não termina em reinicialização. Um downgrade é recusado: voltar atrás é uma desinstalação de verdade, com tudo o que a próxima seção descreve.

Atualize primeiro o Servidor, depois as estações de trabalho, dentro de um mesmo ciclo de versão. Uma estação de trabalho cuja versão de protocolo é mais nova que a janela suportada pelo Servidor não consegue se conectar até que o Servidor seja atualizado. Veja Operações.

Removendo uma máquina

Uma desinstalação é a saída da máquina da plataforma, e não é o inverso de uma atualização.

msiexec /x TrustBridge-Workstation-1.0.1-x64.msi /qn

Ou, sem o MSI à mão, pelo código do produto:

$product = Get-ChildItem HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall |
    Where-Object { $_.GetValue('DisplayName') -eq 'TrustBridge Workstation' }
Start-Process msiexec -Wait -ArgumentList "/x $($product.PSChildName) /qn"

O que a remoção destrói, e nada mais destrói:

A Chave da Estação de Trabalho	Excluída tanto do TPM quanto do repositório de software pelo verbo purge-machine-identity do próprio serviço, que a desinstalação agenda
C:\ProgramData\TrustBridge\	Toda a árvore de estado da máquina: Cache de PIN, chaveiro, conjunto de Autoridades Certificadoras Confiáveis em cache, âncoras
HKLM\Software\TrustBridge	Os três valores
O serviço, o Tray App, a entrada de inicialização automática	Remoção comum
HKLM\Software\Policies\TrustBridge	Intocado. Pertence ao mecanismo de diretivas

A limpeza é executada em uma desinstalação de verdade e nunca na etapa de desinstalação de uma atualização. Uma desinstalação é concluída mesmo quando a limpeza não é; nesse caso, o verbo grava uma entrada bem visível no log Aplicativo, citando o que deixou para trás.

A revogação no Servidor é o controle que não depende da cooperação da máquina. Revogue uma máquina removida no painel dela, na tela Estações de Trabalho, em /admin/fleet. Reinstalar depois produz uma máquina realmente nova: ela volta à fila com uma nova impressão digital, e os titulares dela digitam os PINs de novo.

Quando uma instalação falha

O que você vê	O que é	O que fazer
Código de saída 1603, log cita SERVER_URL	A condição de inicialização	Passe SERVER_URL=https://…. O esquema não é opcional.
Código de saída 1603, log diz que uma versão mais nova está instalada	Um downgrade	Remova antes o pacote mais novo, depois de ler Removendo uma máquina.
Reverte em Starting services	O serviço se recusou a iniciar: uma licença que o SDK não lê, uma INSTALLER_KEY que não pode ser interpretada ou um valor de Registro do tipo errado	O log de eventos Aplicativo cita o valor recusado.
Uma tela de arquivos em uso listando o Tray App	Uma atualização ou remoção interativa	Continue. O Tray é encerrado antes que qualquer arquivo seja tocado; não há reinicialização.
Concluída, mas a máquina não está na fila	Quase sempre a URL; às vezes um valor de diretiva sobrepondo o que você passou	Veja Se a máquina nunca aparece na fila, acima.
Concluída, mas todo certificado aparece como UNTRUSTED	Não há licença da PKI, ou ela expirou	Passe PKI_LICENSE, ou publique-a por Diretiva de Grupo, e então reinicie o serviço.