# GeoLibre mTLS and Certificate Handling: Environment Variables for Native HTTP Client Configuration

> Configure GeoLibre's native HTTP client mTLS and certificate handling using five key environment variables. Learn how REQWEST_TLS_CA_CERT, REQWEST_TLS_CLIENT_CERT, and others manage secure connections.

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

---

**GeoLibre uses five environment variables—`REQWEST_TLS_CA_CERT`, `REQWEST_TLS_CLIENT_CERT`, `REQWEST_TLS_CLIENT_KEY`, `REQWEST_TLS_REJECT_UNAUTHORIZED`, and `REQWEST_TLS_SERVER_NAME`—to control mutual TLS (mTLS) and certificate validation in its Tauri-based native HTTP client.**

GeoLibre's native HTTP client runs inside the **Tauri desktop runtime** and relies on the Rust **reqwest** library for secure network communication. While the application behaves like a standard browser by default, developers can override TLS behavior using environment variables read from `process.env` before any request is dispatched. This article explains each variable's purpose, default behavior, and practical implementation based on the actual source code in `opengeos/GeoLibre`.

## REQWEST_TLS_CA_CERT: Custom Root Certificate Authority

The `REQWEST_TLS_CA_CERT` environment variable specifies the path to a **CA bundle in PEM format** that the client should trust during server certificate validation.

When this variable is omitted, reqwest falls back to the system's native root-CA store. This variable becomes essential when connecting to private services secured by an internal certificate authority that is not distributed through the operating system's trust store.

```typescript
// Trust a private CA for internal API calls
process.env.REQWEST_TLS_CA_CERT = "/etc/ssl/certs/my-org-ca.pem";

await fetch("https://internal.geolibre.example.com/secure-data");

```

The CA bundle validation logic is referenced indirectly in [`src/lib/fetch-error.ts`](https://github.com/opengeos/GeoLibre/blob/main/src/lib/fetch-error.ts), where TLS-related failures are classified and surfaced to users.

## REQWEST_TLS_CLIENT_CERT and REQWEST_TLS_CLIENT_KEY: Mutual TLS Authentication

**Mutual TLS (mTLS)** requires the client to present a certificate that the server can validate. GeoLibre supports mTLS through two coordinated environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `REQWEST_TLS_CLIENT_CERT` | Yes | Path to the **client certificate** (PEM format) |
| `REQWEST_TLS_CLIENT_KEY` | Only if cert is set | Path to the **private key** (PEM format) matching the certificate |

The private key variable is ignored unless `REQWEST_TLS_CLIENT_CERT` is also defined. Neither variable has a default—no client certificate is transmitted unless explicitly configured.

```typescript
// Complete mTLS configuration for a protected API
process.env.REQWEST_TLS_CA_CERT = "/path/to/ca-bundle.pem";
process.env.REQWEST_TLS_CLIENT_CERT = "/path/to/client.crt";
process.env.REQWEST_TLS_CLIENT_KEY = "/path/to/client.key";

await fetch("https://mtls.api.example.com/protected-resource");

```

## REQWEST_TLS_REJECT_UNAUTHORIZED: Bypass Certificate Verification

Set `REQWEST_TLS_REJECT_UNAUTHORIZED` to `"0"` to **disable server certificate verification entirely**. This is useful for development environments using self-signed certificates but should never be enabled in production.

Default behavior rejects unauthorized certificates (equivalent to `"1"`).

```typescript
// Development-only: accept self-signed certificates
process.env.REQWEST_TLS_REJECT_UNAUTHORIZED = "0";

await fetch("https://localhost:8443/api"); // No certificate validation error

```

Warning: Disabling verification exposes the connection to man-in-the-middle attacks. The [`src/lib/diagnostics.ts`](https://github.com/opengeos/GeoLibre/blob/main/src/lib/diagnostics.ts) module generates user-facing warnings when this configuration is detected.

## REQWEST_TLS_SERVER_NAME: Override TLS SNI/Hostname

The `REQWEST_TLS_SERVER_NAME` variable overrides the **Server Name Indication (SNI)** hostname sent during the TLS handshake. This is valuable when connecting via IP address to a server that expects a specific hostname for certificate matching.

Default behavior uses the hostname extracted from the request URL.

```typescript
// Connect by IP but present correct SNI for certificate validation
process.env.REQWEST_TLS_SERVER_NAME = "api.internal.geolibre.io";

await fetch("https://10.0.0.5/metrics"); // TLS handshake advertises "api.internal.geolibre.io"

```

## Where These Variables Are Processed

The environment variables flow through several key files in the GeoLibre codebase:

- **[`apps/geolibre-desktop/src/lib/fetch-error.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/fetch-error.ts)** — Classifies native HTTP (reqwest) failures and reads TLS-related environment variables to determine error context
- **[`apps/geolibre-desktop/src/lib/diagnostics.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/diagnostics.ts)** — Generates user-facing diagnostic messages based on classified TLS errors
- **[`apps/geolibre-desktop/vite.config.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/vite.config.ts)** — Propagates Tauri-specific environment variables into the bundled frontend code
- **[`backend/geolibre_server/pyproject.toml`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/pyproject.toml)** — Declares the `reqwest` dependency on the Rust side; the compiled binary respects TLS env vars at runtime

## Complete Configuration Example

This example combines multiple variables for a complex enterprise scenario: connecting to a private API with custom CA, mTLS, and IP-based routing with SNI override.

```typescript
// Enterprise mTLS configuration
process.env.REQWEST_TLS_CA_CERT = "/certs/enterprise-ca.pem";
process.env.REQWEST_TLS_CLIENT_CERT = "/certs/service-account.crt";
process.env.REQWEST_TLS_CLIENT_KEY = "/certs/service-account.key";
process.env.REQWEST_TLS_SERVER_NAME = "api.geolibre.enterprise";

// Request routes through internal network to load balancer IP
const response = await fetch("https://192.168.100.10/v1/data");

```

## Summary

- **Five environment variables** control GeoLibre's native HTTP client TLS behavior: `REQWEST_TLS_CA_CERT`, `REQWEST_TLS_CLIENT_CERT`, `REQWEST_TLS_CLIENT_KEY`, `REQWEST_TLS_REJECT_UNAUTHORIZED`, and `REQWEST_TLS_SERVER_NAME`
- **mTLS authentication** requires both certificate and key paths; the CA certificate enables trust of private certificate authorities
- **Development shortcuts** like disabling verification are available but carry security risks
- **SNI override** solves hostname/certificate mismatches when connecting by IP address
- Variables are processed in [`fetch-error.ts`](https://github.com/opengeos/GeoLibre/blob/main/fetch-error.ts) and passed to the underlying reqwest instance before request execution

## Frequently Asked Questions

### How do I enable mTLS in GeoLibre's native HTTP client?

Set `REQWEST_TLS_CLIENT_CERT` and `REQWEST_TLS_CLIENT_KEY` to the paths of your PEM-formatted certificate and private key. Optionally set `REQWEST_TLS_CA_CERT` if your server uses a private certificate authority. These variables are read by the Tauri runtime before each request.

### Can I use self-signed certificates during development?

Yes. Set `REQWEST_TLS_REJECT_UNAUTHORIZED="0"` to disable certificate validation. This is implemented in the reqwest-backed native client and surfaced through error classification in [`fetch-error.ts`](https://github.com/opengeos/GeoLibre/blob/main/fetch-error.ts). Remove this setting before deploying to production.

### Where does GeoLibre read these TLS environment variables?

The variables are read from `process.env` early in the native request pipeline. The [`apps/geolibre-desktop/src/lib/fetch-error.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/fetch-error.ts) module inspects TLS-related failures, while [`vite.config.ts`](https://github.com/opengeos/GeoLibre/blob/main/vite.config.ts) propagates these variables into the bundled application. The actual TLS configuration is applied by the reqwest library in the Rust backend.

### What happens if no TLS environment variables are set?

The client behaves like a standard browser request: it validates server certificates against the system root-CA store and does not send a client certificate. No mutual TLS is performed, and SNI uses the hostname from the request URL.