Gecert Connect

Gecert Connect is the application that brings GeCert certificates to the user's Windows. Once the user signs in with their GrantID account, the application installs the certificates the user has access to in the Windows certificate store, and from then on any application can sign or decrypt with them. The private key stays in the server's key store: every operation is sent to the server by Gecert Connect and recorded in the organization.

Requirements

• Windows 10 version 1809 (build 17763) or later, x64 or x86.
• A GeCert server with the GecertConnect section configured and a GrantID account with access to at least one GeCert organization.
• HTTPS access from the user's computer to the GeCert server and to GrantID.

Installation

The Gecert Connect installer is a single bundle, in Portuguese, that installs whatever is missing on the machine, in this order:

1. Microsoft .NET 6 Desktop Runtime (6.0.21)
2. Microsoft Edge WebView2 Runtime, used by the login screen
3. Microsoft Visual C++ Redistributable 2015-2022 (x86 and, in the x64 installer, also x64)
4. Lacuna Key Storage Provider, the Windows CNG provider through which applications use the keys
5. Gecert Connect itself, in C:\Program Files\Lacuna Software\GecertConnect, with a shortcut in the Start menu and another in the user's Startup folder, so that the application opens together with Windows

When updating, the installer closes the running Gecert Connect and replaces the previous version. Ask Lacuna or the administrator of your GeCert instance for the installer.

Server configuration

Gecert Connect needs to know which GeCert server to use. It is configured through a link with the gecertconnect scheme, which the instance administrator hands out to the users:

gecertconnect://server/your-gecert-address

When the link is opened, the application calls https://your-gecert-address/api/app-configuration/gecert-connect/server, receives the server address and the GrantID data (authority, application, API name and redirect URI), saves everything locally and shows the Server configured message. If the server does not answer or does not have the GecertConnect section configured, the message is Error configuring server. On every start, the application queries the configured server again to refresh this data.

While no server is configured, the application shows The application is not configured to use a server. Please configure a server before proceeding. If the configured server goes down, it shows Unable to reach the currently configured server, with a Try again button.

See how to fill the server's GecertConnect section in Configure Gecert Connect on the server.

Login

Click Login. The GrantID login screen opens inside the application, and the user signs in with the same account they use on the GeCert web application. The login uses OpenID Connect with the openid, profile, offline_access and GeCert API scopes, so the application receives an access token and a refresh token, kept protected in the user's Windows profile. When the access token expires, the application renews it by itself; if the renewal fails, it shows The user session has expired. Please try to login again. and goes back to the login screen.

To sign out, open Settings > Advanced Settings and click Logout.

Certificates

After login, the Certificates page lists the certificates the user has access to, with the subject, the organization and the expiration date (Expires on), and the You have access to N certificates counter.

Every 60 seconds, the application queries the server (GET /api/certificates/my) and, for each certificate:

1. Checks that the key exists in the Lacuna Key Storage Provider, named after the key's ID in GeCert.
2. Checks that the certificate is installed in the user's personal certificate store on Windows and bound to that key. A certificate installed in any other way (for example, imported by hand) is removed and reinstalled correctly.
3. If it is missing, downloads the certificate (GET /api/certificates/{id}/public-bytes) and installs it, bound to the KSP key.

Meanwhile, the page shows Verifying certificates. A certificate whose access was removed in GeCert is uninstalled from Windows on the next check.

Use by applications

The installed certificates are visible to any application that uses the Windows certificate store and CNG: Adobe Acrobat, Microsoft Office, browsers and your own applications. To Windows, the key is a key of the Lacuna Key Storage Provider. When an application requests an operation, the provider sends the request to Gecert Connect over the gecert-connect-pipe named pipe, and Gecert Connect forwards it to the server with the user's token.

Operation requested from CNG	What Gecert Connect calls on the server
List the user's keys	GET /api/keys
Get the public key	GET /api/keys/{id}
Sign a hash (SHA-256 or SHA-512, PKCS #1 v1.5 padding)	POST /api/keys/{id}/signature
Decrypt (PKCS #1 v1.5 padding)	POST /api/keys/{id}/decryption
Encrypt	POST /api/keys/{id}/encryption
Verify a signature	POST /api/keys/{id}/signature-verification

For this reason, Gecert Connect must be running, with the user signed in, for the operations to work. Closing the window only hides it: the application stays in the tray, with the Show/Hide and Exit options.

Settings

Under Settings > Advanced Settings:

• Language: Portuguese, English or Spanish.
• Verbose Logging: writes verbose-level logs, for diagnostics.
• Open log folder: opens the application's log folder.
• Check server connection: measures the server's response time when listing the keys and reading the data of one key, separating the total time on the client and on the server, the database access, the key store connection and the reading of the key parameters. The page also shows the application version, the server version and the current response time, with a color indicator.
• Logout.

Logs

The logs are in %LOCALAPPDATA%\GecertConnect\logs.txt, one file per day, with the last 7 days kept. The links below, with the same gecertconnect scheme, help with diagnostics:

Link	What it does
gecertconnect://logs/folder	Opens the log folder
gecertconnect://logs/enable/first-chance-exceptions	Starts logging every exception, including handled ones
gecertconnect://logs/disable/first-chance-exceptions	Goes back to normal logging

Minimum version and maintenance

Before every request, the application calls GET /api/app-configuration/gecert-connect on the server. If the installed version is lower than the minimum version configured on the server, the Update Required screen appears, with the current and the minimum version; if the server is under maintenance, the maintenance screen appears, and the application tries again every 60 seconds.

See Configure Gecert Connect on the server.

Notifications

The application reports through Windows notifications. When several happen within 30 minutes, they are grouped as N notifications occurred recently.

Notification	Cause
Gecert Connect started	The application started
Gecert Server error: The server is unreachable	The configured server did not answer
Gecert Server error: The server returned an error code	The server answered with an error; check the logs
Access denied	The server refused the request (HTTP 403), for example because the user no longer has access to the certificate or to the organization
Unable to install certificate: The certificate appears to not have an associated key, The certificate key appears to not exist on the Gecert server or Gecert Connect was unable to get the certificate	The certificate in GeCert could not be installed on Windows
Gecert Connect error: An unexpected error occured	Internal failure; check the logs

See also

• GeCert
• Configure Gecert Connect on the server
• GeCert API
• Changelog