CA Certificates

iron-proxy intercepts TLS traffic by acting as a man-in-the-middle: it terminates the client’s TLS connection, inspects or transforms the request, then opens a new TLS connection to the upstream server. To do this, it needs a CA certificate and private key to mint leaf certificates on the fly for each upstream host.

Generating a CA Certificate

Generate the CA in two steps: first create a private key, then issue a self-signed certificate with the proper X.509 extensions.


mkdir -p certs
 
openssl genrsa -out certs/ca.key 4096
 
openssl req -x509 -new -nodes \
  -key certs/ca.key \
  -sha256 -days 90 \
  -subj "/CN=iron-proxy CA" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "keyUsage=critical,keyCertSign" \
  -out certs/ca.crt

Parameters

Parameter	Value	Purpose
`-x509`		Generate a self-signed certificate instead of a CSR.
`-new -nodes`		Create a new certificate with an unencrypted private key.
`-key`	`certs/ca.key`	Path to the private key generated by `openssl genrsa`.
`-sha256`		Use SHA-256 for the certificate signature hash.
`-out`	`certs/ca.crt`	Output path for the CA certificate (PEM format).
`-days`	`90`	Certificate validity period in days. See Expiry Recommendations.
`-subj`	`/CN=iron-proxy CA`	Certificate subject. The CN value is arbitrary: pick something descriptive so the cert is easy to identify.

X.509 Extensions

The -addext flags set X.509v3 extensions that mark this certificate as a CA. Both are required:

Extension	Value	Purpose
`basicConstraints`	`critical,CA:TRUE`	Identifies the certificate as a certificate authority. The `critical` flag means clients must reject the certificate if they do not understand this extension.
`keyUsage`	`critical,keyCertSign`	Restricts the key to signing other certificates. This is the minimum permission iron-proxy needs to mint leaf certificates for TLS interception.

Without these extensions, some TLS implementations will reject leaf certificates signed by the CA because the issuer is not properly marked as a certificate authority.

Expiry Recommendations

The CA certificate’s lifetime should match how the proxy is deployed:

Deployment	Recommended Expiry	Rationale
CI/CD (e.g., GitHub Actions)	Ephemeral, generated per-run	The CA only needs to live for the duration of the job. No trust management needed.
Short-lived containers	1 to 90 days	Keep the validity window tight. Rotate by redeploying with a new cert.
Long-running infrastructure	90 to 365 days	Balance operational overhead against security. Automate rotation if possible.

Shorter is better. A compromised CA key lets an attacker mint trusted certificates for any domain within your environment, so limit the blast radius by keeping expiry short and rotating regularly.

Configuring iron-proxy

Point iron-proxy at the CA certificate and key in your config file:


tls:
  ca_cert: "/certs/ca.crt"
  ca_key: "/certs/ca.key"

Both fields are required and must be PEM-encoded files. See the TLS configuration reference for additional options like cert_cache_size and leaf_cert_expiry_hours.

Trusting the CA in Workloads

Clients that make HTTPS requests through iron-proxy need to trust the CA certificate. Otherwise, TLS verification will fail with a certificate authority error. How you install trust depends on the runtime.

System Trust Store (Debian/Ubuntu/Alpine)


cp ca.crt /usr/local/share/ca-certificates/iron-proxy.crt
update-ca-certificates

Most tools that use OpenSSL or the system trust store (curl, wget, apt) will pick this up automatically. On Alpine, you may need to install the ca-certificates package first:


apk add ca-certificates

System Trust Store (RHEL/Fedora)


cp ca.crt /etc/pki/ca-trust/source/anchors/iron-proxy.crt
update-ca-trust

Node.js

Node.js does not use the system trust store by default. Set the NODE_EXTRA_CA_CERTS environment variable:


export NODE_EXTRA_CA_CERTS=/certs/ca.crt

Python (requests/pip)

The requests library and pip respect the REQUESTS_CA_BUNDLE and SSL_CERT_FILE variables:


export SSL_CERT_FILE=/certs/ca.crt
export REQUESTS_CA_BUNDLE=/certs/ca.crt

Alternatively, if the system trust store has been updated, pip and requests will use it automatically on most distributions.

Java

Import the CA into the JVM’s trust store:


keytool -importcert -trustcacerts -noprompt \
  -alias iron-proxy \
  -file /certs/ca.crt \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit

Docker Compose

Share the CA certificate via a volume and install trust in your container’s entrypoint:


services:
  proxy:
    volumes:
      - certs:/certs
 
  app:
    volumes:
      - certs:/certs:ro
    environment:
      - NODE_EXTRA_CA_CERTS=/certs/ca.crt
 
volumes:
  certs:

For containers that use the system trust store, add update-ca-certificates (or equivalent) to the container’s entrypoint or Dockerfile.