Conceitos

O TrustBridge usa um vocabulário pequeno e preciso, e o console administrativo, a API e os logs o usam da mesma forma. Esta página define cada termo uma única vez. Nos títulos que trazem um termo em inglês entre parênteses, o termo em português é o que o console administrativo e o Tray App mostram quando lidos em português do Brasil, e o termo em inglês é o que mostram quando lidos em inglês.

A plataforma

TrustBridge

A plataforma como um todo: o Servidor, o Workstation Service e o Tray App. A especificação do SignSession usa "Trust Bridge" especificamente para o serviço do Windows que monitora os certificados; nesta documentação, o nome sem qualificação significa a plataforma, e o serviço é sempre o Workstation Service.

Servidor (Server)

A aplicação web central: a API REST do SignSession Contract, o console administrativo, a página inicial (Landing Page), o canal das estações de trabalho, os downloads das Versões da Estação de Trabalho e o probe de saúde, todos na mesma porta e diferenciados pelo caminho. Ele guarda o único banco de dados da plataforma: sessões, operações, o Registro de Certificados, o Cofre de Certificados, a Trilha de Auditoria, as contas administrativas, os dois chaveiros, as Versões da Estação de Trabalho e as configurações salvas por um Administrador. Ele também guarda a licença da PKI da implantação, como configuração, e a entrega à frota.

Workstation Service

O serviço do Windows instalado na máquina do usuário. É o único caminho de acesso aos certificados dessa máquina e às chaves privadas deles, por meio do middleware PKCS#11 do fabricante e do Lacuna PKI SDK. Ele se conecta de saída ao Servidor por SignalR/WebSockets, de modo que nenhuma porta de entrada é aberta na máquina. A chave privada de um Certificado de Estação de Trabalho nunca sai da estação de trabalho. A partir do Workstation 1.4.0, ele também consegue instalar uma Versão da Estação de Trabalho que o Servidor lhe oferece.

Tray App

O aplicativo de bandeja do Windows que roda na sessão do usuário conectado, na mesma máquina. Ele mostra o status dos certificados e a lista de certificados, uma aba de tokens com cada token que o serviço enxerga e os certificados dele, coleta o PIN quando uma Sessão de Assinatura precisa de um, define e troca um PIN do Certificado A1, mostra se a máquina está aguardando admissão ou por que está sem licença da PKI e tem um painel de diagnóstico com as linhas recentes de log. Ele fala com o Workstation Service por um named pipe local e nunca com o Servidor.

Página inicial

A porta de entrada do Servidor em / (a Landing Page), sem autenticação. Ela diz o que é este Servidor e traz links para o console administrativo, para a documentação publicada e para a Lacuna Software. Não mostra nenhum estado da plataforma, porque qualquer pessoa que acesse o Servidor pode lê-la.

Signer

O Lacuna Signer, o serviço externo de assinatura responsável pelo fluxo dos documentos: ele calcula o hash a assinar, monta o PDF assinado e o disponibiliza para download. O TrustBridge assina hashes; nunca monta nem armazena documentos.

Sessões e assinaturas

Sessão de Assinatura (Signing Session)

A autorização vinculada a um CPF que permite assinar com o certificado de um usuário, opcionalmente em nome de uma Empresa: uma sessão criada com um CPF e um CNPJ só assina com o e-CNPJ dessa Empresa do qual essa pessoa é a responsável, e uma criada só com o CPF só assina com o e-CPF da pessoa. Há no máximo uma ativa por CPF, ou por par de CPF e CNPJ; criar uma nova substitui a anterior, então a sessão do próprio titular e uma sessão para a Empresa dele podem estar ativas ao mesmo tempo. Ela é identificada por um sessionId opaco, que a criação devolve. O CPF vincula a sessão, mas não a identifica, e nenhuma chamada recupera o id a partir de um CPF.

A sessão é criada quando o PIN informado pela aplicação cliente comprova que quem chama é o titular de um certificado correspondente:

• para um Certificado de Estação de Trabalho, por uma Prova de PIN de uma única estação de trabalho que confere, feita sobre o PIN em cache ou digitado no Tray App dessa máquina, ou sobre um PIN do Certificado A1;
• para um Certificado do Cofre, quando o PIN abre a própria chave do certificado.

PINs errados bloqueiam a criação de sessões para o CPF do titular por um tempo, qualquer que seja o CNPJ pedido.

A partir da criação, ela fica vinculada a esse único certificado e ao seu titular, e toda assinatura feita com ela é encaminhada somente para lá. Ela expira após uma janela de ociosidade que só a atividade de assinatura prolonga; consultar o status dela nunca a prolonga. Onde a implantação concedeu uma Franquia de Assinaturas, ela também termina depois desse número de chamadas de assinatura.

Uma sessão vinculada a uma estação de trabalho sobrevive à desconexão da estação (fica inerte enquanto a máquina está offline) e sobrevive a reinícios do Servidor. Uma sessão vinculada ao cofre não sobrevive a um reinício do Servidor, porque o segredo que abre o certificado só existe em memória; essas sessões terminam como Stranded, e o cliente cria uma nova.

"Sessão", sozinha, sempre significa Sessão de Assinatura. Uma sessão de token PKCS#11, uma sessão de logon do Windows e a sessão web de login de um administrador são coisas diferentes e sempre aparecem qualificadas.

Operação de Assinatura (Signing Operation)

O registro, no Servidor, de uma execução de assinatura de um documento dentro de uma Sessão de Assinatura, criado no envio e conduzido até concluído ou com falha. Uma sessão pode abranger muitas Operações de Assinatura. O id que o cliente recebe, e com o qual obtém o documento assinado, é o id do próprio documento no Signer.

Franquia de Assinaturas (Signature Allowance)

Um segundo limite opcional para uma Sessão de Assinatura: quantas chamadas de assinatura podem ser feitas com ela. É concedida na criação, a partir de Sessions:SignatureAllowance, fixa durante toda a vida da sessão e ausente por padrão. Cada chamada gasta uma unidade, qualquer que seja o número de documentos: um lote de cinquenta gasta uma, e uma chamada cujos documentos falharam todos antes de a chave ser usada não gasta nenhuma. Uma sessão que esgota a franquia fica Esgotada (Exhausted). Uma franquia de 1 torna toda sessão de uso único.

É um limite de política, não uma fronteira de segurança: chamadas simultâneas são autorizadas cada uma antes que qualquer delas tenha gastado uma unidade. As linhas por assinatura da Trilha de Auditoria são o registro exato.

Sessão de console (Console Session)

A sessão de logon do Windows ligada ao console físico da máquina. Uma estação de trabalho pode ter várias sessões de logon ao mesmo tempo (área de trabalho remota, troca rápida de usuário); o pedido de PIN aparece somente nesta, o PIN só pode ser digitado a partir dela, e o log do Workstation Service só pode ser lido a partir dela.

Cache de PIN (PIN Cache)

O armazenamento seguro de PINs de token do Workstation Service, indexado por certificado e preenchido somente pela digitação do PIN no Tray App. Digitar um PIN uma vez cobre todos os certificados do mesmo token. As entradas expiram após um TTL de ociosidade deslizante e são apagadas quando o titular manda esquecer, quando a sessão que autorizaram é desativada ou quando o token recusa o PIN, mas não quando o token é removido. Por padrão o cache fica só em memória e, opcionalmente, pode sobreviver a reinicializações. Um PIN em cache é aquilo com que a máquina prova quando o Servidor a desafia na criação de uma sessão, e o que desbloqueia o token quando ela assina; o tempo ocioso de uma entrada é renovado quando o Servidor avisa a máquina de que uma sessão foi vinculada a ela. Um tempo de vida não governa o outro. O Cache de PIN trata só de tokens: o PIN de um Certificado A1 é um PIN do Certificado A1, guardado como verificador.

Prova de PIN

A resposta de uma estação de trabalho ao desafio do Servidor para um certificado na criação de uma sessão (a PIN Proof). O Servidor envia à máquina um nonce novo, e nunca o PIN; a máquina responde com um HMAC sobre esse nonce, cuja chave é o PIN que ela tem em cache para o certificado, o PIN que o titular acabou de digitar no Tray App ou o verificador de um PIN do Certificado A1, ou diz que não tem com o que provar. O Servidor calcula a prova esperada a partir do PIN enviado pela aplicação cliente e decide se confere; a máquina só fica sabendo o veredito. Assim, o PIN do cliente não passa do Servidor, e a máquina não descobre nada sobre ele. As provas ficam fora de todo log e da Trilha de Auditoria, assim como o PIN. Exige o protocolo 5 das estações de trabalho: uma máquina no protocolo 4 nunca é desafiada.

Limite de provas com falha

Quantas Provas de PIN que não conferem uma estação de trabalho pode dar para o CPF de um titular (o Failed-Proof Budget), dentro da mesma janela e até o mesmo número do bloqueio por PIN errado do CPF (Sessions:MaxPinFailures e Sessions:PinFailureWindow). Toda prova que falha conta, mesmo quando outra máquina conferiu. Uma máquina que esgotou o limite para um CPF não é desafiada nem recebe pedido de PIN para esse CPF, e conta como inacessível para esse titular, até que as falhas expirem. Isso é registrado no log em Warning e na auditoria como pin.proof-budget-spent. O limite é cobrado só dessa máquina e não é o bloqueio, mas um PIN errado custa à máquina do próprio titular uma prova com falha para cada certificado dele que ela tem, então ela pode deixar de ser consultada antes de o bloqueio entrar em vigor. O Cofre de Certificados tem o mesmo limite para senhas que não abrem nada, por CPF e com os mesmos números.

Certificados e custódia

Certificado de Estação de Trabalho (Workstation Certificate)

Um certificado guardado numa máquina, acessível somente pelo Workstation Service dessa máquina e registrado no Registro de Certificados. A chave privada dele nunca sai da estação de trabalho, e a assinatura com ele acontece lá. Um Certificado A3 (smart card ou token USB) é sempre um Certificado de Estação de Trabalho. Um Certificado A1 instalado no repositório do Windows da máquina também é, e ele pode assinar depois que o titular define um PIN do Certificado A1 para ele nessa máquina.

Certificado do Cofre (Vault Certificate)

Um certificado que o próprio Servidor guarda, com chave privada e tudo, importado por um Administrador como PKCS#12 e mantido no Cofre de Certificados. Ele não pertence a nenhuma máquina e não depende de nada online para abrir uma sessão ou assinar. A senha que o desbloqueia é fornecida pela aplicação cliente como o pin em cada criação de sessão e nunca é gravada: a plataforma persiste aquilo sem o qual não consegue assinar, e nada que lhe permita assinar sem ser solicitada.

Esta é, de propósito, a mais conveniente e a mais fraca das duas custódias. Qual custódia um certificado usa é assunto do operador e do auditor, e não é informado à aplicação cliente. Um Administrador pode tirar um Certificado do Cofre de uso (Fora de uso), o que impede que ele abra sessões e assine, mas mantém o certificado e o histórico dele, ou destruir o material da chave, o que não pode ser desfeito. Não existe caminho de exportação ou download em nenhum lugar da plataforma.

Registro de Certificados (Certificate Registry)

O mapeamento persistido, no Servidor, de certificado para estação de trabalho: quais certificados (thumbprint, CPF do titular, o CNPJ da Empresa no caso de um e-CNPJ, e status) estão presentes em quais Workstation Services conectados. Cada serviço anuncia seus certificados ao se conectar e a cada inserção ou remoção. O status de um certificado é o último veredito de validação que a estação de trabalho dele informou, e só ACTIVE pode abrir sessões ou assinar. As entradas refletem o último estado conhecido: os certificados de uma estação de trabalho desconectada continuam visíveis, marcados como offline e com o horário em que foram vistos por último. O mesmo certificado pode, legitimamente, estar registrado em várias estações de trabalho.

Cofre de Certificados (Certificate Vault)

O armazenamento, no Servidor, dos Certificados do Cofre: o que a plataforma guarda, para quem (o CPF do titular e, no caso de um e-CNPJ, o CNPJ da Empresa), o último veredito de cada um e se está fora de uso. É a contraparte do Registro de Certificados. Um certificado pode estar num, no outro ou nos dois.

Diretório de Certificados e Alvo de Assinatura

A leitura que o Servidor faz dos dois armazenamentos como um só (o Certificate Directory): o que pode assinar por um CPF, ou por um CPF em nome de uma Empresa (com os dois conferindo exatamente), e em que ordem a plataforma tenta cada opção. Os Certificados do Cofre são tentados primeiro, depois as estações de trabalho. Um Alvo de Assinatura (Signing Target) é uma coisa capaz de assinar, resolvida uma vez por chamada: um certificado, o último veredito que ele recebeu e a custódia que o guarda. A partir desse ponto, para o restante do Servidor, as duas custódias são uma coisa só.

Vereditos dos certificados

Todo certificado tem um de cinco vereditos, e eles ficam em inglês em todas as telas porque também trafegam no protocolo:

Veredito	Significado
ACTIVE	A cadeia chega a uma âncora de confiança, o certificado está dentro do prazo de validade, e a revogação foi verificada e não consta. O único veredito que pode abrir uma sessão ou assinar.
EXPIRED	Fora do prazo de validade.
REVOKED	Revogado pela autoridade certificadora.
UNTRUSTED	A cadeia não chega a nenhuma âncora em que este componente confia. É também o que todo certificado informa enquanto o componente não tem uma licença da PKI utilizável: uma licença vencida, ou uma estação de trabalho que o Servidor ainda não licenciou.
STALE	Nenhuma verificação de revogação bem-sucedida dentro da janela de tolerância; a AC está inacessível há tempo demais.

Certificado A3 e Certificado A1

Classes de certificado da ICP-Brasil. A chave privada de um A3 fica num hardware removível que executa as assinaturas ele mesmo e nunca entrega a chave; para usá-la é preciso o PIN do titular, e o hardware conta as tentativas erradas. Um A1 é um arquivo de software cuja chave privada é um dado, que circula protegido por senha; depois de instalado, não pede PIN. O mesmo A1 pode estar em várias máquinas ao mesmo tempo, cada cópia um Certificado de Estação de Trabalho, ou ser importado para o Cofre de Certificados.

PIN do Certificado A1 (A1 PIN)

Um PIN que o titular define no Tray App para um Certificado A1 numa estação de trabalho, para que o certificado possa vincular Sessões de Assinatura como um certificado de token: a máquina responde ao desafio do Servidor com uma Prova de PIN feita sobre ele. O Workstation Service guarda um verificador, nunca o PIN, por certificado e por máquina, então o mesmo A1 em três máquinas tem três PINs do Certificado A1. Ele só pode ser definido ou trocado a partir da Sessão de console, e a troca pede o PIN atual. Ele é apagado quando o certificado sai da máquina e também quando aparece um token com o mesmo certificado. Enquanto nenhum estiver definido, as sessões sobre esse A1 terminam em PIN_NOT_AVAILABLE. Ele não protege a chave, que continua no repositório do Windows tão utilizável quanto antes; ele decide quem pode assinar pelo TrustBridge.

Token e middleware

Um token é o hardware removível que guarda chaves A3 e assina com elas: um smart card numa leitora ou um token USB. O middleware é o software do fabricante do token, instalado na máquina; o TrustBridge nunca fala diretamente com um token, só pelo módulo PKCS#11 de um middleware, e só pelos módulos que sabe onde encontrar ou que um operador lista. A aba de tokens do Tray App mostra cada token que o serviço viu, o middleware que o leu e os certificados dele, e indica a leitora que tem um cartão que nenhum middleware leu.

e-CPF e e-CNPJ

Os dois tipos de certificado ICP-Brasil que uma pessoa pode ter, cada um na forma A1 ou A3. Um e-CPF é emitido para uma pessoa física e identifica o titular pelo CPF. Um e-CNPJ é emitido para uma Empresa e identifica duas partes: a Empresa, pelo CNPJ, e a pessoa física responsável por ela, pelo CPF. Para o TrustBridge, essa pessoa é quem detém o e-CNPJ, exatamente como num e-CPF: o cartão, o PIN e a assinatura são dela. Quem tem os dois tem dois certificados que não se substituem, mesmo quando os dois estão num só token, atrás de um só PIN: uma sessão só para o CPF nunca assina com o e-CNPJ, e uma sessão para a Empresa nunca assina com o e-CPF.

Empresa (Company) e Responsável

A pessoa jurídica para a qual um e-CNPJ é emitido, identificada pelo CNPJ. A Empresa nunca é quem detém o certificado: ela não tem PIN, e nada é assinado por ela a não ser pela pessoa que o e-CNPJ identifica. Uma Empresa pode ter vários e-CNPJs, de pessoas diferentes. O console administrativo e o Tray App chamam essa pessoa de Responsável, nunca de Titular, porque na ICP-Brasil o titular de um e-CNPJ é a Empresa.

CPF

O número de inscrição de pessoa física na Receita Federal, com onze dígitos, dois deles verificadores. É a chave que vincula uma Sessão de Assinatura a um certificado: sozinho, numa sessão para essa pessoa, ou com um CNPJ, numa sessão em nome de uma Empresa, em que continua sendo o CPF da pessoa. O TrustBridge confere os dígitos verificadores do CPF que o cliente envia e recusa os onze valores de dígitos repetidos; nunca consulta a Receita Federal para saber se o CPF foi emitido.

CNPJ

O número de inscrição de pessoa jurídica na Receita Federal, que identifica a Empresa para a qual um e-CNPJ é emitido. São catorze caracteres, enviados sem pontuação: doze que identificam a Empresa e dois dígitos verificadores. Os doze podem ter letras maiúsculas além de dígitos (o CNPJ alfanumérico), e as duas formas são aceitas. O TrustBridge confere os dígitos verificadores do CNPJ que o cliente envia e recusa o anúncio de uma estação de trabalho cujo CNPJ não confere com o do certificado anunciado.

Atores e credenciais

Aplicação Cliente (Client Application)

Um sistema externo que se integra pelo SignSession Contract, cadastrado no console administrativo. Ela tem uma ou mais chaves de API, apresentadas no header X-API-Key, e qualquer uma delas a autentica para toda a superfície do contrato. As Sessões de Assinatura não ficam vinculadas à Aplicação Cliente que as criou: qualquer chave pode consultar, usar ou encerrar uma sessão cujo id tenha em mãos.

Conta Administrativa (Admin Account)

O login local de uma pessoa no console administrativo. Não há provedor de identidade externo. A conta tem um de dois perfis: Administrador pode mudar o estado da plataforma; Auditor só pode ler. Toda conta também tem um Segundo Fator. Ela é aberta com a senha e o Segundo Fator ou, quando a implantação permite, só com o Acesso com Certificado; uma implantação pode desligar a entrada com senha, e aí o certificado é a única forma de entrar. Um administrador nunca assina documentos aqui: o certificado usado para entrar só comprova quem a pessoa é.

Segundo Fator (Second Factor) e Código de Recuperação (Recovery Code)

O código TOTP que uma Conta Administrativa apresenta além da senha, cadastrado pelo próprio titular no próprio dispositivo. Nenhum administrador consegue ler, definir ou repassar o de outra pessoa; a única coisa que outro Administrador pode fazer é limpá-lo, o que obriga a uma nova inscrição. Os Códigos de Recuperação são substitutos de uso único, emitidos como um conjunto na inscrição e mostrados uma única vez; um conjunto novo substitui todo o antigo, e limpar o Segundo Fator os invalida. Eles são guardados como hash, então o banco de dados não tem uma cópia utilizável. Uma implantação pode declarar que não exige segundo fator, e isso é uma postura de toda a implantação, definida na configuração, nunca uma exceção por conta. O Acesso com Certificado não apresenta segundo fator e é completo sem ele, mas toda conta continua tendo um, porque a entrada com senha é o caminho de volta.

Acesso com Certificado (Certificate Sign-In)

A entrada de uma Conta Administrativa no console administrativo comprovando que tem a chave de um e-CPF ICP-Brasil que declara o CPF vinculado da conta, lido pelo Lacuna Web PKI no navegador da própria pessoa. É completo por si só: não se apresenta nem senha nem Segundo Fator. Fica desligado até que a implantação o ative e é oferecido ao lado da entrada com senha, a menos que a implantação desligue as senhas. Qualquer certificado em que o Servidor confie para esse CPF serve, A1 ou A3, inclusive uma renovação, então um certificado vencido significa uma ida à autoridade certificadora, e não um bloqueio. Um e-CNPJ nunca dá acesso a ninguém, embora traga o CPF do responsável. O certificado assina um desafio de uso único para comprovar quem a pessoa é e nunca assina um documento.

CPF vinculado (Bound CPF)

O CPF que um Administrador registrou como sendo o da pessoa a quem uma Conta Administrativa pertence: aquilo que o Acesso com Certificado precisa conferir. Ele é digitado na tela de contas, nunca comprovado pela apresentação de um certificado, então é exatamente tão confiável quanto o Administrador que o digitou; o dono da conta vê na própria página qual é o CPF, quem o definiu e quando. É um CPF e nunca um certificado, então qualquer certificado confiável que o declare dá acesso à conta. Ele é único entre as contas. Só um Administrador define, substitui ou limpa um CPF vinculado, e nunca na própria conta; por isso, uma implantação que desliga as senhas precisa de pelo menos dois Administradores. Substituí-lo ou limpá-lo encerra os acessos abertos do dono em até cinco minutos. Não tem relação com o CPF ao qual uma Sessão de Assinatura é vinculada, mesmo quando a mesma pessoa é as duas coisas.

Chave da Estação de Trabalho (Workstation Key)

A chave que uma máquina gera para si mesma, no TPM quando há um utilizável e, caso contrário, em software, e que ela não consegue entregar. Ela é a identidade da máquina: nada é emitido em troca dela, então não existe segredo da estação de trabalho para copiar de um disco. Uma máquina que mantém a chave numa reinstalação continua sendo a mesma estação de trabalho; uma máquina que perdeu a chave é uma nova pedindo para entrar. Se a chave está em hardware ou em software é a postura de chave da máquina, que um Administrador lê antes de admiti-la.

Asserção da Estação de Trabalho

O que uma máquina admitida envia, no lugar de um segredo, ao se conectar (a Workstation Assertion): uma declaração de curta duração com a impressão digital da chave, quando foi gerada, quando expira e um nonce, assinada pela Chave da Estação de Trabalho. Uma asserção abre uma conexão; apresentada de novo, é recusada. É uma prova, não uma credencial, então uma cópia capturada não serve para nada. Cada download de uma Versão da Estação de Trabalho também leva uma asserção nova.

Admissão (Admission)

O ciclo de vida em que uma estação de trabalho se encontra. A máquina se anuncia (a chave, o nome da máquina, o sistema operacional, as versões e a postura de chave) e aguarda uma pessoa. Ela está em exatamente um de três estados:

Estado	Em inglês	Significado
Pendente	Pending	Pediu e ainda não recebeu resposta.
Admitida	Admitted	Pode se conectar.
Revogada	Revoked	Recusada permanentemente. Uma máquina revogada que pede de novo é recusada e nunca volta para Pendente.

Uma máquina pode ser devolvida de Admitida para Pendente sem perder a chave nem o histórico. Um pedido Pendente abandonado, de uma máquina que ninguém nunca admitiu, expira depois de um período configurável e é excluído; a máquina simplesmente pede de novo, como uma máquina que a plataforma nunca viu.

O horário em que a máquina foi vista pela primeira vez é quando a linha dela foi gravada, ou seja, o primeiro pedido. Uma linha Pendente que expirou e é gravada de novo recebe um horário novo. No banco de dados é a coluna FirstSeenAt de Workstations, que se chamava EnrolledAt antes do Servidor 1.11.0; uma consulta ou relatório que use o nome antigo precisa ser alterado.

Admitir é uma etapa humana sobre uma fila, com limite de requisições: sem um canal independente (out-of-band) contra o qual conferir uma impressão digital, a máquina é notada, e não verificada. Isso é aceitável porque a admissão não é opcional e nada que a máquina tenha a admite por conta própria.

Installer Key

Uma chave com a qual o Workstation Service assina o pedido de admissão, além da sua própria, para mostrar que o pedido veio do produto genuíno. Todas as cópias do TrustBridge têm a mesma metade privada, então ela serve contra abuso e não autentica nada. Uma implantação pode receber uma chave própria em vez dessa.

Segredos e confiança

Chaveiro (Key Ring)

O conjunto de chaves com que uma parte da plataforma cifra um segredo. Há três, e não há dois iguais: o do Workstation Service, que protege as entradas do Cache de PIN; e os dois do Servidor, um que protege o Cofre de Certificados (certificate-vault) e outro que protege as próprias sessões web dele (web-sessions). Perder o do cofre torna todos os Certificados do Cofre impossíveis de abrir para qualquer um, inclusive para esta plataforma; perder o das sessões web custa uma rodada de novos logins.

Protetor do Chaveiro (Key Ring Protector)

O certificado X.509 com chave privada RSA que torna legíveis os dois chaveiros do Servidor, fornecido como configuração e nunca guardado pela plataforma. Exigido de todo Servidor, inclusive de um sem Certificados do Cofre, porque o chaveiro das sessões web também precisa dele. Perdê-lo é a forma mais cara de operar mal a plataforma. Ele pode passar por rotação, mas um protetor aposentado nunca é descartado: o Servidor continua precisando, permanentemente, de todo protetor sob o qual alguma chave armazenada já foi selada.

Autoridade Certificadora Confiável e Conjunto de Âncoras de Confiança

Uma Autoridade Certificadora Confiável (Trusted CA) é uma autoridade certificadora em que um Administrador mandou este Servidor confiar, adicionada e removida no console administrativo e em vigor sem reinício no Servidor e em toda máquina admitida que tenha recebido notícias dele desde então. Não é sinônimo de "autoridade certificadora": toda AC da ICP-Brasil é confiável e nenhuma delas é uma Autoridade Certificadora Confiável. Remover uma pode tornar certificados UNTRUSTED, por isso a plataforma informa antes quantos dependem dela.

Quando a implantação ativa o Acesso com Certificado, uma Autoridade Certificadora Confiável também decide quem pode entrar no console administrativo. O acesso confere um CPF, e não um certificado, então uma autoridade que alguém adicione pode emitir um certificado para o CPF vinculado de qualquer administrador e entrar como ele, sem senha e sem Segundo Fator. Adicionar uma é confiar a quem tem a chave dela todos os CPFs vinculados da plataforma; a Trilha de Auditoria continua mostrando quem a adicionou. Da mesma forma, remover uma pode recusar o acesso dos administradores cujos certificados ela emitiu, e a tela de Autoridades Certificadoras Confiáveis mostra uma contagem aproximada deles.

O Conjunto de Âncoras de Confiança (Trust Anchor Set) de um componente é aquilo até onde uma cadeia precisa chegar para que esse componente considere um certificado confiável. Ele é composto de várias fontes, e qualquer uma delas basta: as raízes da ICP-Brasil que o PKI SDK traz, opcionalmente o repositório de raízes da própria máquina, arquivos de âncora configurados numa estação de trabalho e as Autoridades Certificadoras Confiáveis vindas do Servidor. Uma estação de trabalho que recebeu do Servidor um conjunto não vazio de Autoridades Certificadoras Confiáveis usa esse conjunto no lugar dos próprios arquivos de âncora. Só um certificado autoassinado pode encerrar uma cadeia, então um conjunto que só tem intermediárias não ancora nada.

Licenciamento e atualizações

Licença da PKI (PKI Licence)

A permissão de que o Lacuna PKI SDK precisa para ler qualquer certificado. Há uma por implantação, e quem a guarda é o Servidor, como configuração (Certificates:Validation:License): um Servidor sem ela não inicia. O Servidor valida os próprios Certificados do Cofre com ela e a entrega a toda máquina Admitida sempre que essa máquina se conecta, então renovar a licença é uma edição e um reinício no Servidor, sem visitar nenhuma máquina. Nenhuma máquina a guarda entre reinícios, e nada que a instalação de uma estação de trabalho grave a fornece. Uma máquina Pendente, ou que iniciou enquanto o Servidor estava inacessível, fica sem licença até que o Servidor a licencie e, enquanto isso, mostra todo certificado como UNTRUSTED; o Tray App diz em qual estado sem licença ela está. Uma licença vencida não para o Servidor, mas nada na frota nem no cofre consegue assinar até que ela seja renovada, e toda página administrativa avisa isso. Ela não é uma credencial: não autentica ninguém e não diz nada sobre quais certificados são confiáveis.

Versão do protocolo das estações de trabalho

A versão do canal entre o Workstation Service e o Servidor, que cada lado declara no handshake. Um Servidor aceita uma janela de duas versões: a dele e a anterior. Uma máquina abaixo da janela é recusada com update required; uma máquina acima dela é recusada com update the Server first, não recebe licença da PKI e mostra todo certificado como UNTRUSTED até que o Servidor seja atualizado. É por isso que, em geral, o Servidor é atualizado primeiro e a frota no máximo uma release atrás dele.

Protocolo	Primeiro Servidor	Releases das estações de trabalho	O que acrescentou
3	1.7.0	1.1.0 a 1.3.0	O Servidor licencia a máquina no handshake.
4	1.9.0	1.4.0 a 1.4.2	Ofertas: a máquina pode receber atualizações do Servidor.
5	1.13.0 (janela 4–5)	1.5.0	Provas de PIN no lugar do envio do PIN à máquina.

O protocolo 5 exige que os dois sejam atualizados juntos. Uma máquina no protocolo 4 ainda se conecta a um Servidor 1.13.0, recebe a licença, assina pelas sessões já vinculadas a ela e pode receber oferta de uma versão, mas nunca recebe desafio nem pedido de PIN, então, para sessões novas, ela conta como offline. O MSI de uma Versão da Estação de Trabalho declara o protocolo que fala, e o Servidor se recusa a guardar uma versão fora da janela dele.

Versão da Estação de Trabalho (Workstation Release)

Um pacote assinado dos componentes da estação de trabalho, o Workstation Service e o Tray App, que um Administrador enviou na tela Versões da Estação de Trabalho para que o Servidor possa oferecê-lo à frota. O Servidor guarda um por versão, no banco de dados, e lê do próprio arquivo a versão, o protocolo que ele fala e o signatário, então ninguém precisa digitá-los. Ele recusa, sem guardar nada, um arquivo sem assinatura, um signatário que o Publisher Pin dele não lista, um protocolo fora da janela dele ou uma versão que ele já tem. Guardar uma versão não muda nenhuma máquina: só uma oferta muda. Não confunda com uma release do Servidor, que é uma linha separada, com versões próprias.

Oferta (Release Offer)

Uma Versão da Estação de Trabalho oferecida por um Administrador a uma máquina Admitida. Uma máquina tem no máximo uma: oferecer outra substitui a anterior, e retirar a oferta a deixa sem nenhuma. A máquina só age sobre uma oferta acima da versão que executa e só se a Diretiva de Grupo deixar as atualizações ligadas. Ela baixa a versão, a confere (o hash anunciado, a assinatura Authenticode e o carimbo de tempo, um signatário no Publisher Pin dela, a revogação, o produto e a versão), espera um momento ocioso, sem assinatura nem pedido de PIN em andamento, instala sem perguntar nada ao titular e informa se a instalação foi concluída, falhou ou foi recusada. Uma versão que falhou ou foi recusada não é tentada de novo até que um Administrador a ofereça outra vez. Oferecer a todas as máquinas abaixo de uma versão é uma seleção feita uma única vez, então uma máquina admitida depois não recebe oferta até que alguém ofereça de novo. Uma máquina com o Workstation 1.3.0 ou anterior não consegue receber oferta; a tela de estações de trabalho indica que ela precisa de atualização manual.

Publisher Pin

A lista de certificados com que uma Versão da Estação de Trabalho pode ser assinada, compilada no produto, tanto no Servidor quanto em cada Workstation Service, de modo que nenhum Servidor, Administrador, diretiva ou configuração consegue alterá-la. Uma máquina não instala nada cujo signatário não esteja no pin que ela já executa, então o pior que um Servidor ou uma conta administrativa comprometidos conseguem fazer pelas atualizações é instalar antes da hora uma versão genuína e mais nova. Cada máquina informa o próprio pin, e o Servidor só oferece uma versão a máquinas cujo pin lista o signatário dela. Como o pin cita certificados, e não um fornecedor, a renovação do certificado de assinatura de código da Lacuna Software sai primeiro numa release de transição, assinada com o certificado antigo e listando os dois; uma máquina que não a recebe é atualizada à mão ou pela Diretiva de Grupo.

Registros

Trilha de Auditoria (Audit Log)

O registro somente de acréscimo (append-only), no Servidor, dos eventos da plataforma: acesso à API, ciclo de vida das sessões e das assinaturas, eventos de estações de trabalho e de PIN, e ações administrativas, com uma entrada por evento contendo o autor, os identificadores do objeto e o resultado. PINs, Provas de PIN, conteúdo de documentos e bytes de assinatura nunca aparecem nela. Uma entrada que o banco de dados não aceita é gravada no Log do Servidor no nível Critical, com a própria linha.

Log do Servidor (Server log)

O relato do próprio Servidor sobre o que estava fazendo, uma linha por evento com um nível, uma categoria e um id de correlação que também aparece em toda resposta HTTP e liga a linha às linhas correspondentes da Trilha de Auditoria. A saída do console é o registro; um arquivo rotativo no diretório temporário alimenta a tela Log do Servidor do console administrativo, e o Application Insights é a cópia retida, quando configurado. Linhas de log, linhas da Trilha de Auditoria, vereditos de certificado e o error.message da API ficam permanentemente em inglês, qualquer que seja o idioma em que a tela é lida.