For the complete documentation index, see llms.txt. This page is also available as Markdown.

Using mTLS

Mutual TLS (mTLS) provides enhanced security for API communications by requiring both the client and server to authenticate each other using X.509 certificates. This guide explains how to use your Certta certificates to establish mTLS connections with Certta APIs.

Overview

In traditional TLS, only the server authenticates itself to the client. In mTLS, both parties authenticate to each other:

  1. Client initiates a connection to Certta API

  2. Certta server presents its certificate

  3. Client verifies the server certificate

  4. Client presents its own certificate

  5. Certta server verifies the client certificate

  6. If both verifications succeed, a secure connection is established

This bidirectional authentication ensures that only trusted clients can access Certta APIs, and clients only connect to legitimate Certta servers.

Prerequisites

Before implementing mTLS, ensure you have:

  1. Downloaded your client certificate (.crt file) and have your private key (.key file)

  2. The correct Certta API endpoint for your production environment

API Endpoint: For all mTLS-enabled API requests, use the base URL https://mtls.us.prd.caf.io. This is the production endpoint that supports mutual TLS authentication.

Implementing mTLS in your application

Converting certificate formats (if needed)

Depending on your programming language and framework, you might need to convert your certificate format:

Converting .crt to other formats (if needed):

Code examples

Below are examples of implementing mTLS in various programming languages:

Java (OkHttp)

Python (Requests)

Node.js

Curl

Testing mTLS connections from the command line can be helpful for debugging. Here's how to use curl with mTLS certificates:

When using curl for testing, you may need to provide the full certificate chain using the --cert option or specify the certificate authority with --cacert if you're using a non-public CA.

For more information about certificate validity, renewal, and management best practices, see Managing Certificates.

Troubleshooting mTLS connections

If you encounter issues with your mTLS connection, consider the following troubleshooting steps:

  1. Certificate Validation Failed: Ensure your certificate is active and not expired or revoked.

  2. Private Key Issues: Verify that your private key matches the certificate.

  3. Incorrect Certificate Format: Make sure you're using the correct format for your language/framework.

  4. Certificate Issues: Confirm your certificate is still valid and not revoked.

  5. Network Issues: Check if there are any firewalls or proxies interfering with your HTTPS connection.

Best practices

  • Keep certificates and private keys secure in your application's deployment environment.

  • Use secure storage for certificate files in your deployment environments.

  • Implement certificate rotation procedures to handle certificate expiration.

  • Set up monitoring for certificate expiration to avoid service interruptions.

  • Follow the principle of least privilege when assigning permissions to services using mTLS.

Last updated