Replacing an SSL Certificate on AEM 6.5

As you may have read in my other post on configuring SSL on AEM, there are some gotchas and eccentricities on configuring SSL on AEM 6.5. Note, this post does not apply to AEM as a Cloud Service. On AEM as a Cloud Service, SSL certs are managed in the Cloud Manager UI – and I’ll link the docs here for that. This is for a self-managed AEM 6.5 installation.

For background, prior to AEM 6.3, doing SSL on AEM meant you were configuring the Felix/Jetty HTTPS service to use an SSL certificate that was stored on-disk in a Java keystore (JKS) file. And while it still is technically possible to do that on AEM 6.5 (I have one customer like that) it’s generally preferred to use the SSL config built in to AEM, which stores the SSL certificate in the JCR.

So if you’re configuring SSL for the first time, you can use this how-to.

Replacing an SSL Cert

Most of the time, replacing an existing SSL cert should be as simple as:

1. Back up the current SSL cert in the repo, so you have a backout plan in your production change
2. Upload the new certificate in the UI
3. Rinse & repeat for all Publishers & Authors

This means that, like other SSL certs, you should have your PEM-encoded certificate, as well as a DER-encoded private key. See this post if you need help with that.

Steps there are:

Extract & back up the current certificate out of AEM

Go to package manager and create package for

/home/users/system/security/ssl-service/keystore/store.p12

Once you’ve downloaded that package, unzip it and you’ll see a “store.p12” file in there which is a PKCS12 keystore.

You May Need Your Original Private Key

In the case you need your original private key in order to actuate your CSR process for the new cert (and you don’t have access to the files from when you did it before) here’s how you extract the private key out of the certificate you got out of AEM above:

Run the following command:

openssl pkcs12 -info -in -nodes store.p12  > store.pem

This will give you a PEM-encoded certificate (ASCII and not binary) where you can go and copy/paste out the private key and certificate. Save out the private key as a separate file so you can use it as input for your cert-signing request (CSR).

What if I forgot my AEM Keystore Password?

In AEM when you go to the SSL Config page (/libs/granite/security/content/sslConfig.html) it will prompt you for the password for your AEM keystore and truststore. But what if you’ve forgotten what your password is there, or have misplaced it somehow?

The SSL Config page won’t let you configure & upload a new SSL cert unless you have the previous password – but if you’re just uploading a brand-new cert and private key that your certificate authority has just provided to you, you can just take a backup of this node

/home/users/system/security/ssl-service/keystore/store.p12

Then, go into CRX DE and delete the whole folder of “/home/users/system/security/ssl-service/keystore/” (as the keystore password is a property in that folder).

Then, once you go through the SSL config on /libs/granite/security/content/sslConfig.html it will generate a new keystore and you’ll be golden.

Make Sure to Use the SSL Config on your HTTP Port

Just remember, when you are using the SSL Config page, run this using your non-SSL port (i.e. 4502/4503) on AEM, and NOT on the SSL port. If you’re in the midst of configuring SSL, and SSL breaks or errors for any reason, you’ll find yourself not able to access the system. So make sure you’re doing this on non-SSL!

Notes

And yes, in case you were wondering, I wrote this blog post mainly so I could document this for myself so that I don’t shoot myself in the foot the next time I have to switch out certs on a 6.5 machine.

Featured image on this post generated by Adobe Firefly using the prompt: “wise hyper_realistic steampunk bloodhound with goggles holding an official certificate, with a rack of servers in a cast-iron cage behind him, cinematic light, dramatic“