TLS & Certificates
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate utilizes Transport Layer Security (TLS) to secure communications across its supported protocols, including HTTPS, MySQL, and PostgreSQL. The system manages certificates for its own listeners and provides flexible verification options when connecting to target hosts. Warpgate's core TLS implementation is built on the rustls library, ensuring a memory-safe and modern cryptographic foundation.
The project handles two primary TLS contexts: providing a server certificate for incoming client connections (e.g., users accessing the admin UI or database proxies) and validating certificates when Warpgate acts as a client connecting to internal targets.
Sources: README.md:1-25, warpgate-common/Cargo.toml:40-42
Certificate Management and Setup
During the initial setup of Warpgate, the system automatically generates a self-signed TLS certificate if one is not provided. This ensures that the admin interface and database listeners are encrypted by default immediately after installation.
Automated Setup Logic
The setup command generates a certificate valid for warpgate.local and localhost. The resulting certificate and private key are stored in the application's data directory as PEM files.
The setup process applies secure file permissions to the generated private key using a secure_file helper.
Sources: warpgate/src/commands/setup.rs:168-176, warpgate/src/commands/setup.rs:260-275
Configuration Parameters
TLS settings are part of the HttpConfig, MySqlConfig, and PostgresConfig structures. By default, the database protocols share the same certificate paths as the HTTP listener.
| Configuration Field | Description | Default Path (Example) |
|---|---|---|
http.certificate | Path to the PEM-encoded server certificate | tls.certificate.pem |
http.key | Path to the PEM-encoded private key | tls.key.pem |
mysql.certificate | Certificate for MySQL protocol listener | Shared with HTTP |
postgres.certificate | Certificate for PostgreSQL protocol listener | Shared with HTTP |
Sources: warpgate/src/commands/setup.rs:168-176
Implementation Detail: Rustls Integration
Warpgate leverages rustls for high-performance, safe TLS operations. It includes custom verifiers to support specific requirements such as internal self-signed certificates or domain mismatches.
Server Certificate Resolution
The ResolveServerCert structure implements the ResolvesServerCert trait from rustls. This is used by the Warpgate server to provide a specific CertifiedKey during the TLS handshake with connecting clients.
Sources: warpgate-common/src/tls/rustls_helpers.rs:15-22
Client Connector Configuration
When Warpgate connects to a target, the configure_tls_connector function determines how strictly the target's certificate should be validated.
Key verifiers include:
- DummyTlsVerifier: Used when the user explicitly allows invalid certificates. It asserts that certificates and signatures are valid without performing actual checks.
- NoHostnameTlsVerifier: Wraps a standard verifier but specifically ignores
InvalidCertificate(CertificateError::NotValidForName)errors, which is useful for internal targets accessed via IP.
Sources: warpgate-common/src/tls/rustls_helpers.rs:24-65, warpgate-common/src/tls/rustls_helpers.rs:118-140
Admin Interface Configuration
Administrators can configure TLS behavior for specific targets through the Web UI. This is particularly relevant for HTTP, MySQL, and PostgreSQL targets where Warpgate acts as a proxy.
Target TLS Options
For each target, the UI provides options to:
- Enable/Disable TLS: Toggle encryption for the backend connection.
- Verify Certificate: Choose whether to validate the backend's certificate against known CAs.
- Verify Hostname: Choose whether to ensure the certificate matches the target's hostname.
The UI also includes a reminder for database targets to ensure the client is configured to require TLS and cleartext password authentication, as Warpgate acts as a gateway.
Sources: warpgate-web/src/admin/Target.svelte:243-245, warpgate-web/src/admin/Target.svelte:272, warpgate-web/src/common/ConnectionInstructions.svelte:85-87
Summary
TLS & Certificates in Warpgate provide a secure foundation for bastion host operations. By automating certificate generation during setup and providing granular verification controls (including custom rustls verifiers) for backend targets, Warpgate balances security with the practicalities of managing internal network infrastructure.
Sources: warpgate/src/commands/setup.rs:260-275, warpgate-common/src/tls/rustls_helpers.rs:24-65