Skip to main content
Version: Next

mTLS Configuration

Mutual Transport Layer Security (mTLS) is a protocol that provides both authentication and encryption for communication between two parties. It ensures that only authorized entities can communicate, and that their data is protected from eavesdropping and tampering. Below is a guide on how to configure mTLS for Lunar.dev's API Consumption Gateway.

mTLS Configuration

Provide Certificate Files​

Ensure that you supply the necessary certificate and key files, following the correct structure. These files should be stored in /etc/lunar-proxy/certs/mtls/ as shown below:

├── /certs/
    ├── /mtls/
    ├── /tls/

Using a Combined Certificate and Key File​

If you prefer to combine the certificate and key into a single .pem file, this simplifies your configuration. You can create this combined file using the following command:

cat server.crt server.key > server.pem

Then, in your gateway_config.yaml, reference the .pem file under the cert field:

/etc/lunar-proxy/gateway_config.yaml
mTLS:
  - domain: api.example.com
    cert: /etc/lunar-proxy/certs/mtls/server.pem

Using Separate Certificate and Key Files​

For enhanced security, you can keep the certificate and private key as separate files. Make sure they have the same base name, with the .crt and .key extensions, and place them in the same directory. Only the .crt file needs to be specified in the gateway_config.yaml file; the key file is automatically matched based on the name.

For example:

/etc/lunar-proxy/gateway_config.yaml
mTLS:
  - domain: api.example.com
    cert: /etc/lunar-proxy/certs/mtls/server.crt

In this case, the system will automatically associate the server.crt.key file with the server.crt.

Unsupported Certificate Files and How to Use Them​

A PFX file (also known as a PKCS#12 file) is a binary format that securely bundles cryptographic data, including:

  • A private key.
  • The associated public key certificate.
  • Optionally, intermediate certificates or CA certificates.

The contents of a PFX file are encrypted using symmetric encryption algorithms (e.g., AES) to protect the private key and certificate data. The file is further secured by a password, which must be provided to decrypt and access the information inside the PFX file.

How to Convert a PFX File to PEM Format

You can use OpenSSL to convert a PFX file to PEM format:

openssl pkcs12 -in yourfile.pfx -out output.pem -nodes -passin pass:yourpfxpassphrase
  • yourfile.pfx: The input PFX file.
  • output.pem: The resulting PEM file containing the private key, certificate, and intermediate certificates.
  • -nodes: Ensures the private key in the PEM file is not encrypted.
  • -passin pass:yourpfxpassphrase: The password for decrypting the PFX file.

Contents of the PEM File​

After conversion, the resulting PEM file will include:

  • A private key section: 
    -----BEGIN PRIVATE KEY-----
    ...
    -----END PRIVATE KEY-----
  • A certificate section: 
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

You can verify the contents of the PEM file using:

cat output.pem

Example mTLS Configuration​

Below is an example configuration for two domains (api.example.com and api.store.com). The certificates and keys are stored in /etc/lunar-proxy/certs/mtls/:

/etc/lunar-proxy/gateway_config.yaml
mTLS:
  - domain: api.example.com
    cert: /etc/lunar-proxy/certs/mtls/example.crt
  - domain: api.store.com
    cert: /etc/lunar-proxy/certs/mtls/store.crt

This configuration ensures that both the certificate and key are automatically associated for secure mTLS communication.

Make sure that your certificate files and their corresponding key files are properly managed and kept up to date to maintain the security of your mTLS connections.