> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codezero.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TLS

> How cordon intercepts HTTPS traffic using a local CA certificate.

To inject credentials into HTTPS requests, cordon performs TLS man-in-the-middle (MITM) for hosts with matching routes. This is the same technique used by tools like mitmproxy and Charles Proxy.

Unmatched HTTPS traffic is not decrypted. It passes through as a transparent CONNECT tunnel, so the upstream server's real certificate is presented to the client.

## How it works

1. Your app sends a `CONNECT` request to the proxy for the target host
2. Cordon responds with `200 Connection Established`
3. Cordon generates a certificate for the target hostname, signed by the local CA
4. Your app establishes a TLS connection with cordon (trusting the local CA)
5. Cordon establishes a separate TLS connection with the upstream API (using the system trust store)
6. Cordon can now strip and replace auth headers before forwarding the request

## CA certificate setup

The `cordon setup` command generates CA certificates automatically:

```bash theme={null}
cordon setup
```

`cordon.toml` stores absolute paths to the generated CA files. Use the real paths from your generated config; see [Scopes](/configuration/overview#scopes) for certificate storage locations.

```toml theme={null}
[tls]
enabled = true
# Substitute paths from your real `cordon.toml`.
ca_cert_path = "/path/to/ca-cert.pem"
ca_key_path = "/path/to/ca-key.pem"
```

## Trusting the CA

Your system and tools need to trust the CA certificate for HTTPS interception to work without certificate errors.

### System trust store

```bash theme={null}
cordon trust
```

This adds the CA to the system trust store. To remove it later:

```bash theme={null}
cordon untrust
```

System trust is enough for clients that read the OS trust store. Other runtimes need their own proxy or CA settings:

* Use [`cordon env`](/cli/env) or the [generic tool guide](/guides/generic) for the standard proxy and CA bundle variables.
* Use the [SDK compatibility guide](/guides/sdk-compatibility#runtime-ca-and-proxy-notes) for runtime-specific details such as Node.js, Java, Ruby, PHP, curl, and wget.

## Troubleshooting certificate errors

Certificate failures usually mean the calling process either is not using Cordon's CA configuration or is using the raw CA cert where it needs the combined bundle.

Use the same source of truth for all manual setups:

```bash theme={null}
cordon env
```

Common checks:

* `NODE_EXTRA_CA_CERTS` points to `ca-cert.pem` for Node.js.
* `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, and `CURL_CA_BUNDLE` point to `combined-ca.pem`, not `ca-cert.pem`.
* `cordon trust` has been run for tools that use the system trust store.
* Runtime-specific proxy handling is covered in [SDK Compatibility](/guides/sdk-compatibility).

## Security considerations

* The CA private key is stored on disk with `0600` permissions (owner-only read/write)
* The CA certificate must be explicitly trusted — cordon never modifies trust stores without user action
* Per-host certificates include `SubjectAltName: DNS:<hostname>` as required by modern TLS clients
* The downstream connection (app to cordon) uses the local CA; the upstream connection (cordon to API) uses the system trust store — these are never mixed

<Warning>
  The CA private key grants the ability to intercept any HTTPS traffic on the machine. Keep it secure and don't share it. Treat it like an SSH private key.
</Warning>