Gecert Connect

O Gecert Connect é o aplicativo que leva os certificados do GeCert ao Windows do usuário. Depois que o usuário entra com a conta do GrantID, o aplicativo instala no repositório de certificados do Windows os certificados a que ele tem acesso e, a partir daí, qualquer aplicação pode assinar ou decriptar com eles. A chave privada continua no repositório de chaves do servidor: cada operação é enviada ao servidor pelo Gecert Connect e registrada na organização.

Requisitos

• Windows 10 versão 1809 (build 17763) ou mais recente, x64 ou x86.
• Um servidor GeCert com a seção GecertConnect configurada e uma conta do GrantID com acesso a pelo menos uma organização do GeCert.
• Acesso HTTPS do computador do usuário ao servidor GeCert e ao GrantID.

Instalação

O instalador do Gecert Connect é um pacote único, em português, que instala o que falta na máquina, nesta ordem:

1. Microsoft .NET 6 Desktop Runtime (6.0.21)
2. Microsoft Edge WebView2 Runtime, usado pela tela de login
3. Microsoft Visual C++ Redistributable 2015-2022 (x86 e, no instalador x64, também x64)
4. Lacuna Key Storage Provider, o provedor CNG do Windows por meio do qual as aplicações usam as chaves
5. O Gecert Connect, em C:\Program Files\Lacuna Software\GecertConnect, com um atalho no menu Iniciar e outro na pasta Inicializar do usuário, para que o aplicativo abra junto com o Windows

Ao atualizar, o instalador encerra o Gecert Connect em execução e substitui a versão anterior. Peça o instalador à Lacuna ou ao administrador da sua instância do GeCert.

Configuração do servidor

O Gecert Connect precisa saber qual servidor GeCert usar. A configuração é feita por um link com o esquema gecertconnect, que o administrador da instância distribui aos usuários:

gecertconnect://server/endereco-do-seu-gecert

Ao abrir o link, o aplicativo consulta https://endereco-do-seu-gecert/api/app-configuration/gecert-connect/server, recebe o endereço do servidor e os dados do GrantID (autoridade, aplicação, nome da API e URI de redirecionamento), guarda tudo localmente e mostra a mensagem Servidor configurado. Se o servidor não responder ou não tiver a seção GecertConnect configurada, aparece Erro ao configurar o servidor. A cada abertura, o aplicativo consulta o servidor configurado de novo para atualizar esses dados.

Enquanto nenhum servidor estiver configurado, o aplicativo mostra A aplicação não está configurada para usar um servidor. Configure um servidor antes de continuar. Se o servidor configurado ficar fora do ar, aparece a tela Não é possível acessar o servidor configurado no momento, com o botão Tentar novamente.

Veja como preencher a seção GecertConnect do servidor em Configuração do Gecert Connect no servidor.

Login

Clique em Acessar. A tela de login do GrantID abre dentro do aplicativo, e o usuário entra com a mesma conta que usa na aplicação web do GeCert. O login usa o OpenID Connect com os escopos openid, profile, offline_access e a API do GeCert, de modo que o aplicativo recebe um token de acesso e um refresh token, guardados de forma protegida no perfil do usuário no Windows. Quando o token de acesso expira, o aplicativo o renova sozinho; se a renovação falhar, ele mostra A sessão do usuário expirou. Por favor, tente fazer login novamente. e volta à tela de login.

Para sair da conta, abra Configurações > Configurações avançadas e clique em Sair da conta.

Certificados

Depois do login, a página Certificados mostra os certificados a que o usuário tem acesso, com o titular, a organização e a data de expiração (Expira em), e o contador Você tem acesso a N certificados.

A cada 60 segundos, o aplicativo consulta o servidor (GET /api/certificates/my) e, para cada certificado:

1. Confere que a chave existe no Lacuna Key Storage Provider, com o nome igual ao ID da chave no GeCert.
2. Confere que o certificado está instalado no repositório pessoal do usuário no Windows e ligado a essa chave. Se o certificado estiver instalado de outra forma (por exemplo, importado manualmente), ele é removido e reinstalado da forma correta.
3. Se faltar, baixa o certificado (GET /api/certificates/{id}/public-bytes) e o instala, ligado à chave do KSP.

Enquanto isso acontece, a página mostra Verificando certificados. Um certificado cujo acesso foi removido no GeCert é desinstalado do Windows na verificação seguinte.

Uso pelas aplicações

Os certificados instalados aparecem para qualquer aplicação que use o repositório de certificados do Windows e a CNG: Adobe Acrobat, Microsoft Office, navegadores e as suas próprias aplicações. Para o Windows, a chave é uma chave do provedor Lacuna Key Storage Provider. Quando a aplicação pede uma operação, o provedor envia a requisição ao Gecert Connect pelo named pipe gecert-connect-pipe, e o Gecert Connect a repassa ao servidor com o token do usuário.

Operação pedida à CNG	O que o Gecert Connect chama no servidor
Listar as chaves do usuário	GET /api/keys
Obter a chave pública	GET /api/keys/{id}
Assinar um hash (SHA-256 ou SHA-512, padding PKCS #1 v1.5)	POST /api/keys/{id}/signature
Decriptar (padding PKCS #1 v1.5)	POST /api/keys/{id}/decryption
Encriptar	POST /api/keys/{id}/encryption
Verificar uma assinatura	POST /api/keys/{id}/signature-verification

Por isso, o Gecert Connect precisa estar em execução e com o usuário autenticado para que as operações funcionem. Fechar a janela só a esconde: o aplicativo continua na bandeja, com as opções Mostrar/Ocultar e Sair.

Configurações

Em Configurações > Configurações avançadas:

• Idioma: português, inglês ou espanhol.
• Logging Detalhado: grava logs em nível verbose, para diagnóstico.
• Abrir pasta do log: abre a pasta dos logs do aplicativo.
• Checar conexão com o servidor: mede o tempo de resposta do servidor na listagem de chaves e na leitura dos dados de uma chave, separando o tempo total no cliente e no servidor, o acesso ao banco de dados, a conexão ao repositório de chaves e a obtenção dos parâmetros da chave. A página também mostra a versão do aplicativo, a versão do servidor e o tempo de resposta atual, com um indicador de cor.
• Sair da conta.

Logs

Os logs ficam em %LOCALAPPDATA%\GecertConnect\logs.txt, com um arquivo por dia e os últimos 7 dias guardados. Os links abaixo, com o mesmo esquema gecertconnect, ajudam no diagnóstico:

Link	O que faz
gecertconnect://logs/folder	Abre a pasta dos logs
gecertconnect://logs/enable/first-chance-exceptions	Passa a registrar no log todas as exceções, inclusive as tratadas
gecertconnect://logs/disable/first-chance-exceptions	Volta ao registro normal

Versão mínima e manutenção

A cada requisição, o aplicativo consulta GET /api/app-configuration/gecert-connect no servidor. Se a versão instalada for menor que a versão mínima configurada no servidor, aparece a tela Atualização Necessária, com a versão atual e a mínima; se o servidor estiver em manutenção, aparece a tela de manutenção, e o aplicativo tenta de novo a cada 60 segundos. Veja Configuração do Gecert Connect no servidor.

Notificações

O aplicativo avisa pelas notificações do Windows. Quando várias ocorrem em 30 minutos, elas são agrupadas em N notificações ocorreram recentemente.

Notificação	Causa
Gecert Connect iniciado	O aplicativo abriu
Erro do servidor Gecert: O servidor está inacessível	O servidor configurado não respondeu
Erro do servidor Gecert: O servidor retornou um código de erro	O servidor respondeu com erro; veja os logs
Acesso negado	O servidor recusou a requisição (HTTP 403), por exemplo porque o usuário não tem mais acesso ao certificado ou à organização
Não foi possível instalar o certificado: sem uma chave associada, a chave parece não existir no servidor ou não conseguiu pegar o certificado	O certificado no GeCert não pôde ser instalado no Windows
Erro do Gecert Connect: Um erro inesperado aconteceu	Falha interna; veja os logs

Veja também

• GeCert
• Configuração do Gecert Connect no servidor
• API do GeCert
• Histórico de versões