This page lists Cloudflare requirements for custom certificates and explains how to upload and update these certificates using Cloudflare dashboard or API.
Certificate requirements
Before accepting custom certificates, Cloudflare parses them and checks for validity according to a list of requirements. Each custom certificate you upload must: Be encoded in PEM format (PEM, PKCS#7, or PKCS#12). See Converting Using OpenSSLOpen external link for conversion examples. Not have a key file password. Not be expiring in less than 14 days from time of upload. Have a subject alternative name (SAN) matching at least one hostname in the zone where it is being uploaded. Use a private key greater than or equal to a minimum length. Currently, 2048 bit for RSA and 225 bit for ECDSA. Be publicly trusted by a major browser. This does not apply for certificates that specify Be one of the following certificate types:Full list of requirements
User Defined as their bundling methodology.
Upload a custom certificate
To upload a custom SSL certificate in the dashboard:
Log in to the Cloudflare dashboardOpen external link and select your account.
Select your application.
Go to SSL/TLS.
In Edge Certificates, select Upload Custom SSL Certificate.
Copy and paste relevant values into SSL Certificate and Private key text areas (or select Paste from file).
Choose the appropriate Bundle Method.
Select a value for Private Key Restriction.
See AlsoKB5017811—Manage Transport Layer Security (TLS) 1.0 and 1.1 after default behavior change on September 20, 2022How to Access and Change Hidden Advanced Settings in Chrome and FirefoxError when accessing: Unsafe TLS Security Settings - Encyro, Inc.How to Check the TLS Version on a Website: 4 Easy MethodsSelect a value for Legacy Client Support, which toggles Server Name Indication (SNI) support:
- Modern (recommended): SNI only
- Legacy: Supports non-SNI
Select Upload Custom Certificate. If you see an error for
The key you provided does not match the certificate, contact your Certificate Authority to ensure the private key matches the certificate.(optional) Add a CAA DNS record.
The following call will upload a certificate for use with app.example.com. Cloudflare will automatically bundle the certificate with a certificate chain optimized for maximum compatibility with browsers.
- Update the file and build the payload
$ cat app_example_com.pem
-----BEGIN CERTIFICATE-----
MIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E
...
SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O
OeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7
-----END CERTIFICATE-----
$ MYCERT="$(cat app_example_com.pem|perl -pe 's/\r?\n/\\n/'|sed -e 's/..$//')"
$ MYKEY="$(cat app_example_com.key|perl -pe 's/\r?\n/\\n/'|sed -e's/..$//')"
With the certificate and key saved to environment variables (using escaped newlines), build the payload:
$ request_body=$(< <(cat <<EOF
{
"certificate": "$MYCERT",
"private_key": "$MYKEY",
"bundle_method":"ubiquitous"
}
EOF
))
You can optionally add geographic restrictionsOpen external link that specify where your private key can physically be decrypted:
$ request_body=$(< <(cat <<EOF
{
"certificate": "$MYCERT",
"private_key": "$MYKEY",
"bundle_method":"ubiquitous",
"geo_restrictions":{"label":"us"}'
}
EOF
))
You can also enable support for legacy clients which do not include SNI in the TLS handshake.
$ request_body=$(< <(cat <<EOF
{
"certificate": "$MYCERT",
"private_key": "$MYKEY",
"bundle_method":"ubiquitous",
"geo_restrictions":{"label":"us"}',
"type":"sni_custom"
}
EOF
))
sni_custom is recommended by Cloudflare. Use legacy_custom when a specific client requires non-SNI support. The Cloudflare API treats all Custom SSL certificates as Legacy by default.
- Upload your certificate and key
Use the POSTOpen API docs link endpoint to upload your certificate and key.
$ curl -sX POST https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_certificates \
-H "X-Auth-Email: {email}" -H "X-Auth-Key: {key}" \
-H "Content-Type: application/json" -d "$request_body"
- (Optional) Add a CAA record.
A Certificate Authority Authorization (CAA) DNS record specifies which certificate authorities (CAs) are allowed to issue certificates for a domain. This record reduces the chance of unauthorized certificate issuance and promotes standardization across your organization.
For more guidance, refer to Create a CAA record.
Update an existing custom certificate
Before you update an existing custom certificate, you might want to consider having active universal or advanced certificates as fallback options. Go to SSL/TLS > Edge CertificatesOpen external link to check a list of hostnames and status of the edge certificates in your zone.
If you are on an Enterprise plan and want to update a custom (modern) certificate, also consider requesting access to Staging environment (Beta).
To update a certificate in the dashboard:
- Log in to the Cloudflare dashboardOpen external link and select your account.
- Select your application.
- Go to SSL/TLS.
- In Edge Certificates, locate a custom certificate.
- Select the wrench icon and select Replace SSL certificate and key.
- Follow the same steps as upload a new certificate.
To update a certificate using the API, send a PATCHOpen API docs link command.
