How to Set Up Mutual TLS (mTLS) Authentication in the GeoLibre Desktop App

To enable mutual TLS in GeoLibre, set the GEOLIBRE_HTTP_CLIENT_CERT environment variable to your certificate path and optionally GEOLIBRE_HTTP_CLIENT_CERT_PASSWORD for PKCS#12 files, then launch the application.

The GeoLibre desktop application provides enterprise-grade security through mutual TLS (mTLS) authentication for all HTTP communications with its side-car FastAPI server and external services. This Tauri-based client supports both PEM and PKCS#12 certificate formats, automatically selecting the appropriate TLS backend based on your configuration. Understanding how to configure these environment variables ensures secure, certificate-based authentication for your geospatial workflows.

How mTLS Works in GeoLibre's Architecture

The implementation resides in apps/geolibre-desktop/src-tauri/src/lib.rs, where the application initializes its HTTP client during startup. According to the opengeos/GeoLibre source code, the system uses a dual-backend approach: rustls for PEM-encoded certificates and native-tls for PKCS#12 (.p12/.pfx) files or when a password is required.

Certificate Format Detection and Backend Selection

The client_cert_is_pkcs12 function (lines 54–64) determines the TLS backend by checking the file extension or presence of a password. If the path ends in .p12 or .pfx, or if GEOLIBRE_HTTP_CLIENT_CERT_PASSWORD is set, the code switches to native-tls via ClientIdentity::NativeTls. Otherwise, it defaults to ClientIdentity::Rustls for unencrypted PEM files.

The client_identity() Function

Located at lines 35–49 and 84–112 in lib.rs, the client_identity() function reads environment variables and constructs the reqwest::Client with the appropriate identity configuration. For PEM files, it loads the certificate chain and unencrypted PKCS#8 private key. For PKCS#12, it handles encrypted bundles requiring password decryption.

Configuring Environment Variables for mTLS

GeoLibre uses three specific environment variables to control TLS behavior:

• GEOLIBRE_HTTP_CLIENT_CERT: Path to the client certificate file (PEM or PKCS#12)
• GEOLIBRE_HTTP_CLIENT_CERT_PASSWORD: Password for PKCS#12 files (optional)
• GEOLIBRE_HTTP_CA_CERT: Path to additional CA certificates for custom trust anchors (optional)

Setting Up PEM Certificates (No Password)

For PEM-encoded certificates containing the full chain and private key:

export GEOLIBRE_HTTP_CLIENT_CERT=/path/to/cert.pem

# Leave password unset for PEM files

Setting Up PKCS#12 Certificates (With Password)

For Windows-generated .pfx or .p12 files:

export GEOLIBRE_HTTP_CLIENT_CERT=/path/to/cert.p12
export GEOLIBRE_HTTP_CLIENT_CERT_PASSWORD=yourSecurePassword

Adding Custom CA Certificates

If your server uses a private CA, provide the bundle:

export GEOLIBRE_HTTP_CA_CERT=/path/to/ca-bundle.pem

Launching the Application with mTLS

After setting the variables, start the desktop application. The Tauri backend executes extra_ca_certificates() (lines 77–86) to load custom CAs, then builds the reqwest::Client with the specified identity. If you supply a password without a certificate path, the client_cert_password_without_path() function (lines 66–72) raises a configuration error to prevent silent failures.

Example startup sequence:

# Complete example with PKCS#12 and custom CA

export GEOLIBRE_HTTP_CLIENT_CERT=$HOME/certs/client.p12
export GEOLIBRE_HTTP_CLIENT_CERT_PASSWORD=SuperSecret123
export GEOLIBRE_HTTP_CA_CERT=$HOME/certs/internal-ca.pem

npm run tauri:dev  # or launch the built binary

Verification and Troubleshooting

To verify mTLS is active, check side-car server logs for "client certificate presented" messages. You can also use curl to test the certificate outside the app:

curl -v --cert /path/to/cert.p12:SuperSecret123 https://localhost:8765

Summary

• GeoLibre supports mutual TLS through environment variables in apps/geolibre-desktop/src-tauri/src/lib.rs
• PEM files use the rustls backend and require no password
• PKCS#12/PFX files trigger the native-tls backend and require GEOLIBRE_HTTP_CLIENT_CERT_PASSWORD
• The GEOLIBRE_HTTP_CA_CERT variable adds custom trust anchors for private CAs
• Configuration errors are caught early by client_cert_password_without_path() to prevent runtime failures

Frequently Asked Questions

What file formats does GeoLibre support for client certificates?

GeoLibre accepts PEM-encoded files containing the certificate chain and unencrypted PKCS#8 private key, as well as PKCS#12/PFX files. The code automatically detects the format based on file extension (.p12/.pfx) or the presence of a password, selecting rustls for PEM and native-tls for PKCS#12 as implemented in the client_cert_is_pkcs12 logic.

Can I use mTLS without a password?

Yes, if you use PEM-encoded certificates. When GEOLIBRE_HTTP_CLIENT_CERT points to a PEM file and GEOLIBRE_HTTP_CLIENT_CERT_PASSWORD is unset, the application uses rustls and loads the unencrypted key directly. However, PKCS#12 files always require a password if they are encrypted.

Why does GeoLibre switch between rustls and native-tls?

The application defaults to rustls for modern, safe TLS handling of PEM files. However, rustls does not support encrypted PKCS#12 parsing, so the code switches to native-tls when it detects a .p12/.pfx extension or a password is provided, ensuring compatibility with enterprise certificate formats.

How do I trust a private CA in GeoLibre?

Set the GEOLIBRE_HTTP_CA_CERT environment variable to the path of your PEM-encoded CA bundle. The extra_ca_certificates() function in lib.rs loads these certificates during client initialization, adding them to the trust store alongside system defaults.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}