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

> Secure your GeoLibre desktop app with mutual TLS mTLS authentication. Learn how to set environment variables for certificates and passwords to enable secure connections easily.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash

# 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:

```bash
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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/lib.rs) loads these certificates during client initialization, adding them to the trust store alongside system defaults.