Custom Certificates

Configure custom TLS certificates for your domains hosted on Stormkit.

Overview

By default, Stormkit uses Let’s Encrypt to issue certificates automatically for all verified domains. If you want to change this behavior for specific domains, you can configure custom certificates.

This is useful when you:

• Have an existing wildcard certificate
• Need to use certificates from a specific Certificate Authority
• Want to use Extended Validation (EV) certificates
• Have organizational requirements for certificate management

Configuring Custom Certificates

1. Navigate to Custom Domains

   Visit your Application > Environment > Custom Domains page and locate the domain that you’d like to use a custom certificate for.

2. Access certificate settings

   Locate the Expand (…) button next to the domain and click on it.

3. Upload certificate

   Click on Custom certificate and provide both:

   • Certificate - The SSL certificate in PEM format
   • Private Key - The private key used while creating the certificate in PEM format
4. Save

   Click save to apply the custom certificate. It will be activated immediately.

Stormkit accepts only PEM encoded files. If you have certificates in other formats, you’ll need to convert them first.

Certificate Format Requirements

PEM Format

Both certificate and private key must be in PEM (Privacy Enhanced Mail) format, which is Base64 encoded.

Complete Chain

Include the full certificate chain, including intermediate certificates if applicable.

Matching Key

The private key must match the certificate. Mismatched keys will cause SSL errors.

Valid Certificate

Certificate must not be expired and must be valid for the domain you’re configuring.

Converting Certificate Formats

CRT to PEM

If you have a certificate with a .crt extension, you can use openssl to convert it into PEM format:

openssl x509 -in example_org.crt -out example_org.pem -outform PEM

DER to PEM

openssl x509 -inform der -in example_org.der -out example_org.pem

PKCS12 (PFX) to PEM

To extract the certificate:

openssl pkcs12 -in example_org.pfx -clcerts -nokeys -out example_org.pem

To extract the private key:

openssl pkcs12 -in example_org.pfx -nocerts -out example_org.key

Certificate Chain

When uploading your certificate, ensure you include the complete certificate chain:

-----BEGIN CERTIFICATE-----
[Your domain certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate certificate 1]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate certificate 2]
-----END CERTIFICATE-----

API Access

You can manage custom certificates programmatically using the Stormkit API:

Upload Custom Certificate

curl -X PUT \
     -H 'Authorization: <api_key>' \
     -H 'Content-Type: application/json' \
     'https://api.stormkit.io/v1/domains/cert' \
     -d '{
       "domainId": "2500",
       "certValue": "-----BEGIN CERTIFICATE-----\n...",
       "certKey": "-----BEGIN PRIVATE KEY-----\n..."
     }'

Delete Custom Certificate

curl -X DELETE \
     -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/domains/cert?id=2500'

See the Domains API documentation for more details.

Reverting to Let’s Encrypt

To revert to automatic Let’s Encrypt certificates:

1. Navigate to Custom Domains
2. Find the domain with custom certificate
3. Click the Expand (…) button
4. Click Delete custom certificate
5. Stormkit will automatically issue a Let’s Encrypt certificate

Security Best Practices

• Protect private keys - Never commit private keys to version control
• Regular renewal - Monitor certificate expiration dates and renew before expiry
• Strong key size - Use at least 2048-bit RSA keys or 256-bit ECC keys
• Secure storage - Store certificates and keys in secure, encrypted locations
• Access control - Limit who can upload and manage certificates

Troubleshooting

Certificate upload fails

• Verify the certificate is in PEM format
• Check that the private key matches the certificate
• Ensure the certificate is valid and not expired
• Verify the certificate is issued for the correct domain

SSL errors after upload

• Check that you included the complete certificate chain
• Verify the certificate is valid for the domain
• Wait a few minutes for the certificate to propagate
• Clear browser cache and try again

Private key format issues

• Ensure the key is not password protected
• Convert the key to PEM format if needed
• Check for proper BEGIN/END markers