Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Deploy custom certificate

Enterprise customers who do not wish to install a Cloudflare certificate have the option to upload their own root certificate to Cloudflare. This feature is sometimes referred to as Bring Your Own Public Key Infrastructure (BYOPKI). Gateway will use your uploaded certificate to encrypt all sessions between the end user and Gateway, enabling all HTTPS inspection features that previously required a Cloudflare certificate. You can upload multiple certificates to your account, but only one can be active at any given time. You also need to upload a private key to intercept domains with JIT certificates and to enable the block page.

You can upload either a root certificate or a full certificate chain (root certificate plus intermediate certificates). Uploading a certificate chain allows end-user devices to only install the root certificate, which can simplify certificate management for larger enterprises.

You can upload up to five custom root certificates. If your organization requires more than five certificates, contact your account team.

Generate a custom root CA

  1. Open a terminal.

  2. (Optional) Create a directory for the root CA and change into it.

    Terminal window
    mkdir -p /root/customca
    cd /root/customca

    You can generate the certificate files in any directory. This step keeps things organized. If you skip it, files will be created in your current working directory.

  3. Generate a private key for the root CA.

    Terminal window
    openssl genrsa -out <CUSTOM-ROOT-PRIVATE-KEY>.pem 2048

    The 2048 value specifies the RSA key size in bits. You can use 4096 for stronger security at the cost of slightly slower TLS handshakes.

  4. Generate a self-signed root certificate.

    Terminal window
    openssl req -x509 -sha256 -new -nodes \
      -key <CUSTOM-ROOT-PRIVATE-KEY>.pem \
      -days 365 \
      -out <CUSTOM-ROOT-CERT>.pem \
      -addext "basicConstraints=critical,CA:TRUE" \
      -addext "keyUsage=critical,keyCertSign,cRLSign"

    The -addext flags add the basicConstraints and keyUsage extensions required by RFC 5280 ↗ for CA certificates. Without them, some TLS clients may reject certificates signed by your custom CA. In particular, Python 3.13 and later enforce strict RFC 5280 compliance by default (ssl.VERIFY_X509_STRICT), causing HTTPS requests to fail for devices using the Cloudflare One Client when the uploaded CA does not include these extensions.

    The -days 365 value controls certificate expiry. A shorter duration reduces risk if the key is compromised, but requires more frequent rotation. Rotating a deployed BYOPKI certificate is a disruptive operation, so choose an expiry that balances security with operational overhead.

    Error: Unknown cipher or option -addext

    If your system runs OpenSSL versions older than 1.1.1, the -addext flag is not available. Use a config file instead:

    Terminal window
    openssl req -x509 -sha256 -new -nodes \
      -key <CUSTOM-ROOT-PRIVATE-KEY>.pem \
      -days 365 \
      -out <CUSTOM-ROOT-CERT>.pem \
      -config <(printf '[req]\ndistinguished_name=dn\n[dn]\n[v3_ca]\nbasicConstraints=critical,CA:TRUE\nkeyUsage=critical,keyCertSign,cRLSign') \
      -extensions v3_ca

  5. Verify the required RFC 5280 extensions are present:

    Terminal window
    openssl x509 -in <CUSTOM-ROOT-CERT>.pem -noout -ext keyUsage,basicConstraints

    The output should include:

    X509v3 Basic Constraints: critical
        CA:TRUE
    X509v3 Key Usage: critical
        Certificate Sign, CRL Sign

    If these fields are missing, regenerate the certificate using the command in step 4.

  6. To review the private key, run the following command:

    Terminal window
    openssl rsa -in <CUSTOM-ROOT-PRIVATE-KEY>.pem -text

    To review the certificate, run the following command:

    Terminal window
    openssl x509 -in <CUSTOM-ROOT-CERT>.pem -text

When preparing your certificate and private key for upload, be sure to remove any unwanted characters, such as mismatching subdomains in the certificate's common name.

Deploy a custom root certificate

You can upload a single root certificate or a full certificate chain. When uploading a certificate chain via the dashboard, API, or Terraform, concatenate the root certificate and any intermediate certificates in PEM format, with the root certificate first.

  1. In Cloudflare One ↗, go to Traffic policies > Traffic settings > Certificates.

  2. Select Upload certificate.

  3. Enter the private key and SSL certificate you generated or select Paste certificate from file to upload them from a file. If uploading a certificate chain, paste all certificates (root and intermediates) in PEM format with the root certificate first.

  4. Select Upload custom certificate.

    You can now use the generated custom root certificate for inspection.

Use a custom root certificate

To use a custom root certificate you generated and uploaded to Cloudflare, refer to Activate a root certificate.

Troubleshooting

Error 526: Invalid SSL certificate

If Gateway returns an HTTP Response Code: 526 after deploying a custom certificate, refer to the Error 526 documentation.

Python 3.13+ SSL errors with the Cloudflare One Client

Python 3.13 and later enable ssl.VERIFY_X509_STRICT by default, which requires CA certificates to comply with RFC 5280 ↗. If your BYOPKI certificate was generated without the keyUsage and basicConstraints extensions, Python HTTPS requests will fail when the Cloudflare One Client is active. To resolve the issue, generate a new custom root CA and upload it to Cloudflare.