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, no SQL Server ou, no Docker, no PostgreSQL (Servidor 1.20.0): 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, a Atividade de assinatura, o último Relatório da Estação de Trabalho de cada estação 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. A partir do Workstation 1.8.0, ele envia ao Servidor um Relatório da Estação de Trabalho sobre a própria situação e reinicia uma leitora de cartão USB que o Windows não conseguiu iniciar. A partir do Workstation 1.10.0, esse relatório também diz quem está no console da máquina, a Conta no console.

Estação de trabalho (Workstation)

Uma máquina que a plataforma conhece pela Chave da Estação de Trabalho dela: um computador Windows que executa um Workstation Service e o Tray App dele, num dos estados da Admissão. "Estação de trabalho", sem qualificação, significa a máquina, nunca o serviço dela e nunca um certificado nela; então uma contagem de estações de trabalho conta máquinas, quantos certificados cada uma tiver. O Cofre de Certificados não é uma estação de trabalho, e nada que ele assina é atribuído a uma.

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 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 ou quando um token é inserido (o Pedido de PIN na inserção), 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.

Cada entrada no Windows o inicia só como ícone, sem janela. A partir do Workstation 1.9.0, o atalho TrustBridge do menu Iniciar abre a janela dele: traz para a frente um Tray App que já está rodando na sessão, inicia um quando não há nenhum e substitui um que não responde em 5 segundos. Assim, o titular cujo Tray App foi fechado ou parou de responder o recupera sem sair da sessão do Windows.

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. Onde a implantação a ativou, ela também leva à página pública de Assinatura de teste. Não confunda com o lugar aonde chega um administrador que entrou, que é o Painel.

Painel (Dashboard)

A página inicial do console administrativo (Servidor 1.17.0): a tela em que um administrador chega depois de entrar. Ela lê a Atividade de assinatura da plataforma (a de hoje, a deste mês e a dos últimos 30 dias) ao lado do que precisa de um Administrador, da situação da frota e de quanto tempo a assinatura leva. Ela só lê e não muda nada, e nada do que mostra é coletado no caminho de uma chamada de assinatura: uma assinatura nunca fica mais lenta porque o Painel existe. Os dias e os meses dela são os da implantação, no fuso horário que Dashboard:TimeZone indica. Não confunda com a página inicial (Landing Page), que fica fora do login e não mostra nenhum estado da plataforma.

Assinatura de teste (Test Signature)

Uma assinatura pedida para ver a plataforma assinar: um operador comprovando que uma implantação funciona de ponta a ponta, ou uma demonstração. Quem pede digita a chave de API de uma Aplicação Cliente, um CPF e, a menos que essa aplicação crie as sessões dela sem o PIN, o PIN dele numa página que o Servidor serve para isso. Ela é real em todos os aspectos, exceto em quem a pediu: uma Sessão de Assinatura real, vinculada como qualquer outra, um documento real no Signer, ou no REST PKI Core quando essa aplicação assina com ele, para que o teste comprove o caminho que o integrador dela usa, e um PDF assinado válido, uma página que o Servidor escreve descrevendo o certificado. A partir do Servidor 1.23.0, quem pede pode mandar assinar até cinquenta cópias dessa página de uma vez, ou menos onde Signing:MaxBatchItems for menor, na mesma chamada em lote que um integrador faria; um lote em que algumas cópias são assinadas e outras não continua contando como feito. A sessão é encerrada assim que a assinatura dá certo ou falha. Ela é pedida pelo console administrativo, por um Administrador, sempre, ou pela página inicial, por qualquer pessoa, só onde a implantação a ativou. As chamadas dela são feitas como a Aplicação Cliente cuja chave foi digitada; o Servidor não guarda nenhuma chave própria para elas. Como na criação de qualquer sessão, ela substitui uma sessão já ativa para o mesmo CPF e CNPJ, e um PIN errado conta para o bloqueio do titular. Ela é contada à parte do resto da Atividade de assinatura.

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. Por padrão, o TrustBridge assina hashes e o Signer faz o resto. Para uma Aplicação Cliente que assina os documentos dela com o REST PKI Core, quem faz o resto é o REST PKI Core, e o Signer não participa desse documento. Nos dois casos, o TrustBridge nunca monta nem armazena um documento assinado.

REST PKI Core

O Lacuna REST PKI Core, um serviço externo que assina PDFs em torno de uma chave que ele não tem (Servidor 1.18.0). Para uma Aplicação Cliente que um Administrador configurou para usá-lo (Assinar documentos com o REST PKI Core), ele faz com os documentos dessa aplicação o que o Signer faz com os de todas as outras: calcula o hash a assinar, monta o PDF assinado depois que a chave do titular assina esse hash, e guarda e disponibiliza o documento assinado. As mesmas chamadas respondem nos mesmos formatos, então o integrador não consegue saber qual dos dois assinou. Qual deles assina é decidido a cada chamada de assinatura pela aplicação cuja chave a faz, nunca pela que criou a Sessão de Assinatura. Ele muda quem monta o documento e nada sobre quem o assina: o certificado do titular continua fazendo exatamente uma assinatura, sob as mesmas regras de custódia, de PIN e de Autorização de assinatura. Qual política de assinatura ele aplica, se marca as páginas, em quais certificados confia e por quanto tempo guarda um documento são configurações do REST PKI Core que a implantação usa, e não do TrustBridge. O veredito dele sobre um certificado é um segundo veredito ao lado do da plataforma, e os dois podem discordar. Não é a Assinatura de hash, em que a própria Aplicação Cliente monta o envelope assinado.

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 única exceção à comprovação do PIN é uma Aplicação Cliente com o PIN dispensado na criação ligado (veja PIN por transação): uma sessão que ela cria sem PIN só se vincula quando exatamente um certificado poderia atendê-la.

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 Aplicação Cliente que a criou tem 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 cuja estação de trabalho foi removida nunca mais assina e expira sozinha. 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 Interrompida, e o cliente cria uma nova. A exceção é uma sessão de PIN por transação vinculada ao cofre, que não guarda nenhum segredo entre as chamadas e por isso sobrevive a um reinício: o PIN da chamada seguinte abre o certificado de novo.

"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 ou, quando o REST PKI Core montou o documento, o do REST PKI Core, exposto da mesma forma. O Servidor não gera nenhum. Uma Operação de Assinatura registra qual dos dois montou o documento dela. Uma cuja estação de trabalho foi removida depois mantém o registro e diz só que a estação de trabalho dela foi removida.

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 do valor que um Administrador definiu na Aplicação Cliente que criou a sessão, na tela Aplicações Cliente (Servidor 1.17.0), e fica fixa durante toda a vida dessa sessão: mudar o valor da aplicação só vale para as sessões criadas depois. Fica ausente por padrão, em toda Aplicação Cliente, e uma sessão sem franquia é limitada apenas pela janela de ociosidade. Ela já foi um valor único para toda a implantação (Sessions:SignatureAllowance, que não é mais lida desde o Servidor 1.17.0). 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. Não é a Atividade de assinatura, que conta o que foi assinado, e não chamadas de assinatura.

PIN por transação (Per-Transaction PIN)

Uma configuração de uma Aplicação Cliente, ligada por um Administrador, com a qual toda chamada de assinatura das Sessões de Assinatura que ela cria precisa do PIN do titular só para aquela chamada. Para um Certificado de Estação de Trabalho, token ou A1, o titular o digita no Tray App da máquina vinculada, que mostra quem está assinando o quê: isso é uma Autorização de assinatura, e a aplicação cliente não envia PIN. Para um Certificado do Cofre, em que não há a quem pedir, a aplicação cliente o envia com a chamada, e ele abre a chave só para essa chamada. A sessão registra na criação se é uma delas, e de qual dos dois tipos, e mantém isso durante toda a vida (o transactionPin do contrato: null, "workstation" ou "client"); ligar ou desligar o recurso não altera nenhuma sessão já criada. A criação da sessão não muda, e o PIN continua sendo comprovado nela, a menos que um Administrador também tenha configurado a aplicação para o PIN dispensado na criação (Sessions without a PIN, Servidor 1.18.0), uma segunda opção que só é oferecida enquanto esta está ligada: então um PIN que ela envie continua sendo comprovado, e sem ele a sessão só se vincula quando exatamente um certificado poderia atendê-la, deixando o PIN para cada chamada. Nos dois casos, uma sessão assim deixa de autorizar sozinha uma assinatura, e é por isso que um cliente que usa esse modo mantém uma sessão de longa duração por usuário. Uma chamada pede o PIN uma vez só, quantos documentos ou hashes ela tiver. Não é uma Franquia de Assinaturas, que limita quantas chamadas uma sessão pode fazer e não pede nada a ninguém. Exige o protocolo 6 das estações de trabalho (Workstation 1.6.0 ou posterior).

Autorização de assinatura (Signing Authorization)

A aprovação, pelo titular, de uma chamada de assinatura numa sessão de PIN por transação vinculada a um Certificado de Estação de Trabalho. O Tray App, só na Sessão de console, mostra o nome da Aplicação Cliente e o que a chamada vai assinar (os documentos pelo nome, ou quantos hashes), e o titular digita o PIN, que o token verifica ou que, num Certificado A1, é conferido com o PIN do Certificado A1. O Workstation Service então guarda esse PIN em memória para as assinaturas daquela chamada e de nenhuma outra, e o apaga quando a chamada termina, quando os usos dele se esgotam ou quando o tempo dele acaba. Um pedido de assinatura que não cita nenhuma autorização aberta é recusado: ele nunca recorre ao Cache de PIN, e o PIN digitado para ele nunca chega a esse cache. A Trilha de Auditoria registra cada autorização pedida, concedida ou recusada, e a cita em cada assinatura que ela permitiu; nunca o PIN. Uma máquina mantém no máximo Signing:MaxPendingAuthorizations chamadas esperando o titular.

Assinatura de hash (Hash Signing)

Uma chamada de assinatura que entrega ao titular de uma Sessão de Assinatura hashes que uma Aplicação Cliente calculou ela mesma, e responde as assinaturas: sem documento, sem Signer, nada a buscar depois (POST /v1/signatures/hashes). A Aplicação Cliente monta em torno delas o envelope assinado que quiser, e é por isso que uma sessão responde o certificado e a cadeia dele antes de qualquer assinatura. Ela não gera Operação de Assinatura. Uma chamada de Assinatura de hash gasta uma unidade da Franquia de Assinaturas, quantos hashes tiver, e ou todas as assinaturas são respondidas ou nenhuma é. Como ela deixa a Aplicação Cliente escolher exatamente o que a chave do titular assina, o que nada consegue inspecionar, só uma Aplicação Cliente a que um Administrador concedeu esse recurso pode fazer uma.

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.

Conta no console (Console Account)

A conta do Windows conectada à Sessão de console de uma estação de trabalho: quem está diante da máquina, até onde o Windows sabe (Workstation 1.10.0, Servidor 1.23.0). Uma conta, não uma pessoa: a plataforma sabe que alguém entrou com essa conta e nada sobre quem digitou a senha dela. Ela é identificada pelo identificador de segurança (SID) do Windows, e o nome DOMÍNIO\usuário é um rótulo para quem lê a tela. A máquina não tem nenhuma enquanto ninguém está conectado no console, e ela muda quando alguém sai da sessão ou outro usuário troca para a dele. Ela existe com ou sem um Tray App rodando nessa sessão, e é isso que permite a um operador distinguir "não há ninguém na máquina" de "há alguém, e o Tray App dessa pessoa sumiu". As contas conectadas às outras sessões de logon da máquina, pela Área de Trabalho Remota ou pela troca rápida de usuário, não são ela, e nenhum pedido de PIN chega a elas. Ela nunca é o titular de um certificado, embora a mesma pessoa possa ser as duas coisas. O Relatório da Estação de Trabalho a traz, e a tela Estações de Trabalho a mostra na coluna Conta no console.

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: no pedido de PIN da criação de uma sessão, num Pedido de PIN na inserção ou quando o titular pede para digitar um. 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. Uma assinatura por transação nunca o usa: o PIN digitado para uma Autorização de assinatura não é lido dele nem gravado nele, e não renova nenhuma das entradas dele. O Cache de PIN trata só de tokens: o PIN de um Certificado A1 é um PIN do Certificado A1, guardado como verificador.

Pedido de PIN na inserção (Insertion Prompt)

A oferta que o Tray App faz, quando um token chega a uma leitora, de guardar o PIN desse token no Cache de PIN, para que as assinaturas seguintes não precisem de nenhum pedido de PIN (Workstation 1.7.0). Ela é feita uma vez por token, quantos certificados ele tiver, e só para um token cujo PIN ainda não está em cache e no qual pelo menos um certificado capaz de assinar é lido. Só na Sessão de console, e só enquanto ela está desbloqueada: um token que chega com a máquina bloqueada recebe a oferta no desbloqueio, se ainda estiver conectado e o PIN dele ainda não estiver em cache. Nunca para os tokens que já estavam presentes quando o Tray App se conecta, nunca para um token bloqueado e nunca para um Certificado A1. Ela mostra o token, a leitora e o titular de cada certificado nele, dá lugar a qualquer pedido de PIN aberto pelo Servidor e volta depois, se o token ainda estiver conectado e o PIN dele ainda não estiver em cache. O titular pode recusá-la, e ela expira se ninguém responder. Uma implantação pode desligá-la por máquina (Tray:InsertionPrompt), e então a chegada de um token é avisada, sem pedido de PIN. Ela não aprova nada nem comprova nada: nenhuma Sessão de Assinatura é criada por ela, e nenhuma Autorização de assinatura é dada por ela, então uma sessão de PIN por transação continua pedindo o PIN a cada chamada. Um PIN digitado ali é registrado na estação de trabalho, e não na Trilha de Auditoria, que só fica sabendo dele quando uma sessão o usa.

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 ou posterior.

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 deixar um Certificado do Cofre 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 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.

Uma leitora com falha é uma leitora de cartão conectada à estação de trabalho que o Windows não conseguiu iniciar: nenhum middleware consegue consultá-la e nenhum token nela pode ser visto, e, num token USB, que é a própria leitora, é o próprio token que não aparece. A partir do Workstation 1.8.0, a aba Tokens a indica, e o Workstation Service reinicia sozinho, até três vezes, uma leitora USB que o Windows deixou com o código de problema 10 (falha ao iniciar), a menos que a implantação tenha desligado isso (Certificates:RestartFailedReaders). Cada nova conexão dá direito a uma nova série de tentativas, e uma leitora que continua com falha depois delas fica a cargo do titular, que a desconecta e conecta de novo. Uma leitora que continua com falha é informada no Relatório da Estação de Trabalho, e a tela Estações de Trabalho marca a máquina dela com Leitora com falha.

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. O que uma sessão exige continua sendo decidido por quem a criou e fixado na criação: a Franquia de Assinaturas e as opções de PIN por transação da criadora acompanham a sessão até qualquer chave que assine nela. Se os documentos são assinados pelo Signer ou pelo REST PKI Core funciona ao contrário: é uma escolha sobre o que quem chama recebe, e não sobre o que o titular aceitou, então é lida da aplicação que faz cada chamada de assinatura.

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 dono da conta 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 um novo cadastro. Os Códigos de Recuperação são substitutos de uso único, emitidos como um conjunto no cadastro 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. A única exceção é escolha do próprio Servidor: uma máquina que foi removida é esquecida junto com a chave, então a mesma chave pedindo de novo é uma máquina nova. 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 enquanto a linha dela existir. Uma máquina revogada que pede de novo é recusada e nunca volta para Pendente. Só Remover, que esquece a linha e a recusa junto, deixa a chave dela pedir de novo, como uma máquina nova.

Uma máquina pode ser devolvida de Admitida para Pendente sem perder a chave nem o histórico; o pedido dela então nunca expira, e ela espera na fila até alguém admiti-la de novo ou removê-la. 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.

Remover (Remove)

O que um Administrador faz quando o Servidor deve esquecer uma máquina que ele já admitiu (Servidor 1.21.0): a linha dela, o que ela informou por último e o bloqueio sobre a Chave da Estação de Trabalho dela. Vale para uma máquina em qualquer um dos estados da Admissão, desde que alguém a tenha admitido alguma vez; um pedido que ninguém nunca admitiu expira em vez disso. Uma máquina removida que ainda está instalada e pede de novo é uma máquina que a plataforma nunca viu, sem histórico, aguardando admissão.

Organização, e não um controle de segurança. Uma máquina perdida, roubada ou comprometida é Revogada, o que a deixa de fora e mantém a chave dela recusada. Remover uma máquina Revogada levanta essa recusa junto com a linha.

O que aconteceu continua registrado. A Trilha de Auditoria mantém todas as entradas sobre a máquina, e a remoção acrescenta uma que a identifica por completo. As Sessões de Assinatura e as Operações de Assinatura feitas por meio dela continuam existindo e só dizem que a estação de trabalho delas foi removida. As contagens do Painel sobre o que ela assinou ficam como estavam.

Não é desinstalar. Desinstalar é feito na máquina e destrói a chave dela; remover é feito no Servidor e esquece a máquina. Uma coisa pode acontecer sem a outra.

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.
6	1.15.0 (janela 5–6)	1.6.0 a 1.10.0	Autorizações de assinatura, para o PIN por transação.

O protocolo 5 exigia que os dois fossem atualizados juntos: uma máquina no protocolo 4 ainda se conectava a um Servidor 1.13.0 ou 1.14.x, mas nunca recebia desafio nem pedido de PIN, então, para sessões novas, contava como offline. No protocolo 6, o Servidor volta a ir primeiro: uma máquina no protocolo 5 se conecta ao Servidor 1.15.0 e atende todas as sessões como antes, mas nunca é escolhida para uma sessão de PIN por transação. Do Workstation 1.7.0 ao 1.10.0, todos continuam no protocolo 6; o 1.8.0 e os posteriores são distribuídos com o Servidor 1.20.0 ou posterior, o primeiro cujo canal das estações de trabalho aceita um Relatório da Estação de Trabalho de até 1 MB. O que as releases seguintes acrescentaram, de um lado ou do outro, trafega no protocolo 6 como campos opcionais que a outra ponta, se for mais antiga, ignora: o console informado pelo Workstation 1.10.0 aparece a partir do Servidor 1.23.0, e um Servidor a partir do 1.23.0 indica que uma máquina que não o informa precisa do Workstation 1.10.0. 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 Política 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 Estações de Trabalho a mostra como 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, política 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 Política 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 (inclusive a Assinatura de hash e as Autorizações de assinatura), eventos de estações de trabalho e de PIN, Assinaturas de teste e ações administrativas, com uma entrada por evento contendo o autor, os identificadores do objeto e o resultado. A entrada de uma chamada à API também guarda o código de erro com que ela foi respondida (Servidor 1.24.0), e só o código. 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.

Código de erro (Error Code)

O nome legível por máquina que o SignSession Contract dá ao motivo de uma chamada não ter sido atendida como foi pedida, como SESSION_EXPIRED ou SERVER_BUSY: o code do envelope de erro, ao lado de uma message escrita para pessoas. Ele faz parte de um conjunto que o contrato publica e que pode crescer. Fica em inglês onde quer que apareça, porque é a string que um integrador informa ao suporte. A partir do Servidor 1.24.0, a Trilha de Auditoria o guarda junto com a chamada que ele respondeu e o mostra depois do status HTTP (GET /v1/certificates/info 401 SESSION_EXPIRED), já que um mesmo status pode corresponder a vários códigos; a mensagem e os detalhes não são guardados, porque os detalhes podem repetir o que o cliente enviou. Uma chamada respondida sem envelope de erro não tem código. Não é o motivo de uma Recusa da Estação de Trabalho, que o operador fica sabendo e o integrador não, nem um erro do Relatório da Estação de Trabalho, que o software da máquina registrou.

Atividade de assinatura (Signing Activity)

A contagem, na plataforma, do que as chaves dos titulares assinaram e a plataforma respondeu (Servidor 1.17.0), mantida em duas unidades que nunca são somadas: documentos assinados, as Operações de Assinatura concluídas, e hashes assinados pelas chamadas de Assinatura de hash bem-sucedidas, inclusive os de um Certificado do Cofre. Assinado quer dizer respondido à Aplicação Cliente: uma execução que falhou ou foi interrompida não é atividade. As falhas são contadas ao lado dela, nunca dentro dela. Ela não identifica nenhum titular: quem assinou é a Trilha de Auditoria que responde. Uma Assinatura de teste é uma assinatura real, mas é contada à parte, para que comprovar que uma implantação funciona nunca pareça uso de alguém. Ela é atribuída à Aplicação Cliente que pediu e à estação de trabalho, ou ao Cofre de Certificados, que assinou, e é contada desde a instalação, e não só enquanto a Trilha de Auditoria mantém as linhas dela. Ela é consolidada, e não em tempo real: um processo em segundo plano a lê da Trilha de Auditoria alguns minutos atrás, então um valor pode estar atrás da Trilha de Auditoria, mas nunca a contradiz. O Painel a mostra. Não é uma unidade gasta da Franquia de Assinaturas, que conta chamadas de assinatura.

Relatório da Estação de Trabalho (Workstation Report)

O que uma estação de trabalho informou por último ao Servidor sobre a própria situação (Servidor 1.20.0, Workstation 1.8.0), para que o suporte veja o problema de uma máquina sem estar diante dela e um administrador veja o mesmo problema em toda a frota. São seis tipos: as leitoras com falha que continuam com falha; cada token que ela enxerga, por fabricante, modelo e número de série, com quão perto o PIN dele está de bloquear; o middleware que ela consulta, com as versões; os erros que o Workstation Service e o Tray App registraram; dados da máquina que o suporte pede, como a licença da PKI que ela tem e as opções com que roda; e, a partir do Workstation 1.10.0 e do Servidor 1.23.0, o console dela: a Conta no console, se essa sessão está bloqueada, se um Tray App roda na Sessão de console e em qual versão, e quantas outras sessões de logon têm um, sem identificar as contas delas. A máquina o informa sem que ninguém peça, sempre que se conecta e sempre que ele muda: o Servidor guarda o que recebeu por último, nunca o pede, e uma máquina offline mantém o último relatório. A tela Estações de Trabalho, o Painel e a tela Relatórios das Estações de Trabalho o mostram. Ele não é a Trilha de Auditoria, que registra quem fez o quê, nem o log da própria máquina, que fica na máquina. Uma implantação pode desligá-lo numa máquina (WorkstationReport:Enabled), que então só informa que não informa e aparece como Sem relatório, para que o silêncio nunca seja lido como uma máquina saudável.

Recusa da Estação de Trabalho (Workstation Refusal)

Uma chamada de um titular que uma estação de trabalho não concluiu: uma Autorização de assinatura que ela recusou, ou o pedido de PIN da criação de uma Sessão de Assinatura que ela não conseguiu mostrar, que expirou ou cujo PIN não conferiu. A Trilha de Auditoria registra cada uma com o motivo e, quando nenhum Tray App pôde ser contatado, o porquê: a partir do Servidor 1.22.0 com o Workstation 1.9.0, para uma Autorização de assinatura, e a partir do Servidor 1.23.0 com o Workstation 1.10.0, para o pedido de PIN de uma criação. Duas são escolha de alguém, o titular recusar ou a Aplicação Cliente desistir da espera, e aparecem, mas não são um problema da máquina; o mesmo vale para uma chamada que o titular autorizou depois que a Sessão de Assinatura dela já tinha terminado. Todas as outras são, inclusive um PIN que não conferiu, já que alguns desses seguidos bloqueiam um token. A partir do Servidor 1.23.0, a tela Estações de Trabalho conta, para cada máquina, as recusas das últimas 24 horas que são um problema, N recusas (24h), e a aba Eventos do painel dela descreve cada uma em palavras, com o que perguntar ao titular. Não é um erro do Relatório da Estação de Trabalho, que o software da máquina registrou mesmo sem ninguém pedindo nada, nem a recusa que a Aplicação Cliente recebe, que diz menos: o integrador fica sabendo que o PIN não estava disponível, e o operador fica sabendo por quê.

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.