Pete Freitag Pete Freitag

Development SSL / TLS with CommandBox

Updated on February 10, 2022
By Pete Freitag

I've been working on my upcoming Full Day ColdFusion Security Training Class at CFSummit. The training takes place on a VM which I have preloaded with everything the trainees will need. Because I'm a big fan of CommandBox I thought I would set it up fully using CommandBox instead of Apache and the CF installer.

In order to teach certain sections we need HTTPS support, so here's a quick rundown of how I set it up on Linux, but the same approach should work on a Mac.

Using mkcert to generate a CA cert

Normally I use openssl to generate a self-signed certificate authority (CA) cert, which I then import into Firefox as a Trusted Certificate. This time I decided to give another tool a whirl, it's called mkcert, once you have downloaded the binary you just run:

mkcert -install

The above will generate a cacert which we can then import into Firefox or other browsers.

Now your browser will trust any certificate that mkcert generates! Take a second and let the implications of that sink in, you need to be careful when using such a tool because with the private key to your CA SSL certificates can be generated that look valid in your browser for any domain! One solution to this risk is to generate wildcard certs and then delete the rootCA-key.pem to prevent accidental exposure.

Generate a TLS Certificate

While we are here, lets note that the appropriate term is a TLS certificate, but the term SSL will probably be used as a synonym for another 20 years.

If we want to generate a wildcard cert for *.dev.local you can run this:

mkcert "*.dev.local"

The output will be two pem files one is the certificate, and one is the private key.

You can also generate a cert with a bunch of domains, if you don't want to use a wildcard:

mkcert other-dev.local

Using the Self Signed TLS Certificates with CommandBox

Now for the fun part, we can tell CommandBox to use or new certificate and start a server with SSL (er... TLS) enabled. The easiest way to do this is with a server.json file:

    "web": {
        "host": "",
        "SSL": {
            "certFile": "/path/to/dev.local.pem",

In the above case we are running the HTTPS server on port 8443, you can switch it to 443 but unix operating systems only allow root to bind to port numbers less than 1024 for security reasons.

Another Option

Another option for local TLS development is to put another HTTP server in front of CommandBox that handles port 80 and port 443. The server can proxy the requests on to CommandBox's port. Servers like apache and nginx handle the root port issue by starting as root to bind the ports, but then they create child processes that run as a non root user.

commandbox tls ssl

Development SSL / TLS with CommandBox was first published on September 19, 2019.

If you like reading about commandbox, tls, or ssl then you might also like:

FuseGuard Web App Firewall for ColdFusion

The FuseGuard Web Application Firewall for ColdFusion & CFML is a high performance, customizable engine that blocks various attacks against your ColdFusion applications.

The weekly newsletter for the CFML Community


I think you intended to link to and not

It looks like mkcert works with Windows too, but requires using Chocolatey.
by James Moberg on 09/27/2019 at 5:57:20 PM UTC
Upon further review, it looks like pre-built binaries for makecert are available at
by James Moberg on 09/27/2019 at 5:59:12 PM UTC
Yes, I did -- I have updated the link, thanks.
by Pete Freitag on 09/27/2019 at 6:06:09 PM UTC
FYI: According to this post from 2016 RFC-6761 [1] reserves four TLDs: .example, .invalid, .localhost, and .test. (I'm using .test as my TLD.) .DEV is own by Google while .LOCAL & .APP are reserved. (RFC 6762 reserves .LOCAL for Multicast DNS on a local network.)
by James Moberg on 09/27/2019 at 6:23:58 PM UTC
FYI: Chrome & Firefox reject second-level wildcard certificates so I'll be using "*.test.local" instead.
by James Moberg on 09/27/2019 at 6:28:53 PM UTC
Sorry, I meant "*.local.test". (based on other info I provided earlier which hasn't been approved as a blog comment yet.)
by James Moberg on 09/27/2019 at 6:30:15 PM UTC
Had been looking to get local SSL/TLS dev going so this was very useful, thanks! Have you come across it not setting the CGI variables? I get CGI.SERVER_PORT_SECURE set to 1 but all other flags like CGI.HTTPS are empty. This using Adobe CF2018 with CommandBox.
by JohnK on 01/09/2020 at 11:36:30 AM UTC