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 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 e as configurações salvas por um Administrador.

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.

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, coleta o PIN quando uma Sessão de Assinatura precisa de um, mostra se a máquina está aguardando admissão e tem um painel de diagnóstico com as linhas recentes do log do serviço. 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. Há no máximo uma ativa por CPF; criar uma nova substitui a anterior. 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 desse CPF:

• para um Certificado de Estação de Trabalho, quando o PIN confere com o digitado no Tray App de uma única estação de trabalho;
• para um Certificado do Cofre, quando o PIN abre a própria chave do certificado.

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 reproduz as sessões de uso único da implementação de referência.

É 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 numa falha por PIN errado, mas não quando o token é removido. Por padrão o cache fica só em memória e, opcionalmente, pode sobreviver a reinicializações. Criar uma sessão ou assinar consome um PIN em cache quando há um; um tempo de vida não governa o outro.

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

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, 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 ú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 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 quando a licença do PKI SDK está ausente ou vencida.
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.

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

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.

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

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.

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.

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.

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.

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