{"title":"Run a private online TLS certificate authority in a Docker container","byline":null,"dir":null,"lang":null,"content":"

This guide will illustrate how to run open source step-ca inside a Docker container.\nAs an example, you will send secure communications between a standalone webserver and curl.

\n

About this tutorial

\n\n\n

Overview

\n\n

Requirements

\n\n

Quickstart

\n

On your Docker host, run:

\n
docker run -d -v step:/home/step \\\n    -p 9000:9000 \\\n    -e \"DOCKER_STEPCA_INIT_NAME=Smallstep\" \\\n    -e \"DOCKER_STEPCA_INIT_DNS_NAMES=localhost,$(hostname -f)\" \\\n    smallstep/step-ca\n
\n

The following environment variables are available for CA configuration:

\n\n

Once step-ca is running, the CA's URL and SHA256 fingerprint are all clients need to bootstrap with the CA.

\n

Let's bootstrap the step client. Run:

\n
{\n  CA_FINGERPRINT=$(docker run -v step:/home/step smallstep/step-ca step certificate fingerprint certs/root_ca.crt)\n  step ca bootstrap --ca-url https://localhost:9000 --fingerprint $CA_FINGERPRINT\n}\n
\n

Output:

\n
The root certificate has been saved in /Users/alice/.step/certs/root_ca.crt.\nYour configuration has been saved in /Users/alice/.step/config/defaults.json.\n
\n

Your CA is ready for use. You can view your CA password via:

\n
docker run -v step:/home/step smallstep/step-ca cat secrets/password\n
\n

Manual installation

\n

1. Pull down the Docker image

\n

Get the latest version of step-ca

\n
docker pull smallstep/step-ca\n
\n

2. Bring up PKI bootstrapping container

\n

The Docker volume step will hold your CA configuration, keys, and database.

\n
docker run -it -v step:/home/step smallstep/step-ca step ca init\n
\n

The init command will step you through the bootstrapping process. Example output:

\n
✔ What would you like to name your new PKI? (e.g. Smallstep): Smallstep\n✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): localhost\n✔ What address will your new CA listen at? (e.g. :443): :9000\n✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): admin@smallstep.com\n✔ What do you want your password to be? [leave empty and we'll generate one]:\n\nGenerating root certificate...\nall done!\n\nGenerating intermediate certificate...\nall done!\n\n✔ Root certificate: /home/step/certs/root_ca.crt\n✔ Root private key: /home/step/secrets/root_ca_key\n✔ Root fingerprint: 86a278f34e58c7ab04313aff0e8e5114f1d1da955ecb20412b3d32cc2267ddcd\n✔ Intermediate certificate: /home/step/certs/intermediate_ca.crt\n✔ Intermediate private key: /home/step/secrets/intermediate_ca_key\n✔ Database folder: /home/step/db\n✔ Default configuration: /home/step/config/defaults.json\n✔ Certificate Authority configuration: /home/step/config/ca.json\n\nYour PKI is ready to go. To generate certificates for individual services see 'step help ca'.\n
\n

Save the root fingerprint value! You'll need it for client bootstrapping.

\n

3. Place the PKI root password in a known safe location.

\n

The image is expecting the password to be placed in /home/step/secrets/password. Bring up the shell prompt in the container again and write that file:

\n
docker run -it -v step:/home/step smallstep/step-ca sh\n
\n

Inside your container, write the file into the expected location:

\n
 echo \"<your password here>\" > /home/step/secrets/password\n
\n

Your CA is configured and ready to run.

\n

4. Start step-ca

\n

The CA runs an HTTPS API on port 9000 inside the container. Expose the server address locally and run the step-ca with:

\n
docker run -d -p 9000:9000 -v step:/home/step smallstep/step-ca\n
\n

Now, on your Docker host, bootstrap your step client configuration:

\n
{\n  CA_FINGERPRINT=$(docker run  -v step:/home/step smallstep/step-ca step certificate fingerprint /home/step/certs/root_ca.crt)\n  step ca bootstrap --ca-url https://localhost:9000 --fingerprint $CA_FINGERPRINT\n}\n
\n

Output:

\n
The root certificate has been saved in /Users/alice/.step/certs/root_ca.crt.\nYour configuration has been saved in /Users/alice/.step/config/defaults.json.\n
\n

Your localstep CLI is now configured to use the container instance of step-ca and our new root certificate is trusted by our local environment (inserted into local trust store).

\n

Run a health check:

\n
curl https://localhost:9000/health\n
\n

Output:

\n
{\"status\":\"ok\"}\n
\n

Next steps:

\n\n

Setting Up a Development Environment

\n

You will need:

\n\n

Run this section on your host machine where Docker is installed.

\n

Once you've bootstrapped your local environment, you can now run web services configured with TLS and mTLS. First, get a certificate for localhost:

\n
step ca certificate localhost localhost.crt localhost.key\n
\n

Output:

\n
✔ Key ID: aTPGWP0qbuQdflR5VxtNouDIOXyNMH1H9KAZKP-UcHo (admin)\n✔ Please enter the password to decrypt the provisioner key:\n✔ CA: <https://localhost:9000/1.0/sign>\n✔ Certificate: localhost.crt\n✔ Private Key: localhost.key\n
\n

Now save a copy of your root CA certificate:

\n
step ca root root_ca.crt\n
\n

Output:

\n
The root certificate has been saved in root_ca.crt.\n
\n

Next, let's launch a web server secured by HTTPS:

\n
{\ncat <<EOF > server.py\nimport BaseHTTPServer, ssl\n\nclass HelloHandler(BaseHTTPServer.BaseHTTPRequestHandler):\n    def do_GET(self):\n        self.send_response(200);\n        self.send_header('content-type', 'text/html; charset=utf-8');\n        self.end_headers()\n        self.wfile.write(b'\\\\n\\\\xf0\\\\x9f\\\\x91\\\\x8b Hello! Welcome to TLS \\\\xf0\\\\x9f\\\\x94\\\\x92\\\\xe2\\\\x9c\\\\x85\\\\n\\\\n')\n\nhttpd = BaseHTTPServer.HTTPServer(('', 8443), HelloHandler)\nhttpd.socket = ssl.wrap_socket(httpd.socket,\n                   server_side=True,\n                   keyfile=\"localhost.key\",\n                   certfile=\"localhost.crt\",\n                   ca_certs=\"root_ca.crt\")\nhttpd.serve_forever()\nEOF\n\npython server.py\n}\n
\n

Open up another terminal to see your server running:

\n
$ curl https://localhost:8443\n👋 Hello! Welcome to TLS 🔒✅\n\n
\n\n

Further Reading

\n\n

Troubleshooting

\n

Raspberry Pi Badger database errors

\n

When you run step-ca on a Raspberry Pi, you might get the following error in\nyour container logs:

\n
step-ca  | badger 2021/05/08 20:13:12 INFO: All 0 tables opened in 0s\nstep-ca  | Error opening database of Type badger with source /home/step/db: error opening Badger database: Mmap value log file. Path=/home/step/db/000000.vlog. Error=cannot allocate memory\n\n
\n

To fix it, edit the db configuration block in the file config/ca.json.

\n
docker run -v step:/home/step -it smallstep/step-ca vi /home/step/config/ca.json\n
\n

Change the value of badgerFileLoadingMode from \"\" to \"FileIO\".

\n

You will end up with this:

\n
    \"db\": {\n          \"type\": \"badger\",\n          \"dataSource\": \"/home/step/db\",\n          \"badgerFileLoadingMode\": \"FileIO\"\n    },\n
\n

Save and restart the container.

","textContent":"This guide will illustrate how to run open source step-ca inside a Docker container.\nAs an example, you will send secure communications between a standalone webserver and curl.\nAbout this tutorial\n\nLearn how to Bootstrap and run a private X.509 online Certificate Authority in a Docker container.\nEstimated effort: Reading time ~4 mins, Lab time ~20 to 60 mins.\n\n\nOverview\n\nQuickstart\nManual installation\nSetting Up a Development Environment\n\nRequirements\n\nOpen source - To interact with step-ca, you'll want to install the step client in your host environment. See our installation docs.\n\nQuickstart\nOn your Docker host, run:\ndocker run -d -v step:/home/step \\\n -p 9000:9000 \\\n -e \"DOCKER_STEPCA_INIT_NAME=Smallstep\" \\\n -e \"DOCKER_STEPCA_INIT_DNS_NAMES=localhost,$(hostname -f)\" \\\n smallstep/step-ca\n\nThe following environment variables are available for CA configuration:\n\nDOCKER_STEPCA_INIT_NAME (required) the name of your CA—this will be the issuer of your CA certificates\nDOCKER_STEPCA_INIT_DNS_NAMES (required) the hostname(s) or IPs that the CA will accept requests on\nDOCKER_STEPCA_INIT_PROVISIONER_NAME a label for the initial admin (JWK) provisioner. Default: \"admin\"\nDOCKER_STEPCA_INIT_SSH set this to a non-empty value to create an SSH CA\nDOCKER_STEPCA_INIT_PASSWORD specify a password for the encrypted CA keys and the default CA provisioner. A password is generated by default. Note: In a production environment, a more secure option for specifying a password is to use the manual installation process, below.\n\nOnce step-ca is running, the CA's URL and SHA256 fingerprint are all clients need to bootstrap with the CA.\nLet's bootstrap the step client. Run:\n{\n CA_FINGERPRINT=$(docker run -v step:/home/step smallstep/step-ca step certificate fingerprint certs/root_ca.crt)\n step ca bootstrap --ca-url https://localhost:9000 --fingerprint $CA_FINGERPRINT\n}\n\nOutput:\nThe root certificate has been saved in /Users/alice/.step/certs/root_ca.crt.\nYour configuration has been saved in /Users/alice/.step/config/defaults.json.\n\nYour CA is ready for use. You can view your CA password via:\ndocker run -v step:/home/step smallstep/step-ca cat secrets/password\n\nManual installation\n1. Pull down the Docker image\nGet the latest version of step-ca\ndocker pull smallstep/step-ca\n\n2. Bring up PKI bootstrapping container\nThe Docker volume step will hold your CA configuration, keys, and database.\ndocker run -it -v step:/home/step smallstep/step-ca step ca init\n\nThe init command will step you through the bootstrapping process. Example output:\n✔ What would you like to name your new PKI? (e.g. Smallstep): Smallstep\n✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): localhost\n✔ What address will your new CA listen at? (e.g. :443): :9000\n✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): admin@smallstep.com\n✔ What do you want your password to be? [leave empty and we'll generate one]:\n\nGenerating root certificate...\nall done!\n\nGenerating intermediate certificate...\nall done!\n\n✔ Root certificate: /home/step/certs/root_ca.crt\n✔ Root private key: /home/step/secrets/root_ca_key\n✔ Root fingerprint: 86a278f34e58c7ab04313aff0e8e5114f1d1da955ecb20412b3d32cc2267ddcd\n✔ Intermediate certificate: /home/step/certs/intermediate_ca.crt\n✔ Intermediate private key: /home/step/secrets/intermediate_ca_key\n✔ Database folder: /home/step/db\n✔ Default configuration: /home/step/config/defaults.json\n✔ Certificate Authority configuration: /home/step/config/ca.json\n\nYour PKI is ready to go. To generate certificates for individual services see 'step help ca'.\n\nSave the root fingerprint value! You'll need it for client bootstrapping.\n3. Place the PKI root password in a known safe location.\nThe image is expecting the password to be placed in /home/step/secrets/password. Bring up the shell prompt in the container again and write that file:\ndocker run -it -v step:/home/step smallstep/step-ca sh\n\nInside your container, write the file into the expected location:\n echo \"\" > /home/step/secrets/password\n\nYour CA is configured and ready to run.\n4. Start step-ca\nThe CA runs an HTTPS API on port 9000 inside the container. Expose the server address locally and run the step-ca with:\ndocker run -d -p 9000:9000 -v step:/home/step smallstep/step-ca\n\nNow, on your Docker host, bootstrap your step client configuration:\n{\n CA_FINGERPRINT=$(docker run -v step:/home/step smallstep/step-ca step certificate fingerprint /home/step/certs/root_ca.crt)\n step ca bootstrap --ca-url https://localhost:9000 --fingerprint $CA_FINGERPRINT\n}\n\nOutput:\nThe root certificate has been saved in /Users/alice/.step/certs/root_ca.crt.\nYour configuration has been saved in /Users/alice/.step/config/defaults.json.\n\nYour localstep CLI is now configured to use the container instance of step-ca and our new root certificate is trusted by our local environment (inserted into local trust store).\nRun a health check:\ncurl https://localhost:9000/health\n\nOutput:\n{\"status\":\"ok\"}\n\nNext steps:\n\nSee our Basic CA Operations guide.\nSee our Configuration Guide to learn more about tailoring step-ca to your infrastructure.\nOr, set up a development environment in the next section.\n\nSetting Up a Development Environment\nYou will need:\n\nA Python 2.7.x interpreter to bring up a standalone webserver (optional)\n\nRun this section on your host machine where Docker is installed.\nOnce you've bootstrapped your local environment, you can now run web services configured with TLS and mTLS. First, get a certificate for localhost:\nstep ca certificate localhost localhost.crt localhost.key\n\nOutput:\n✔ Key ID: aTPGWP0qbuQdflR5VxtNouDIOXyNMH1H9KAZKP-UcHo (admin)\n✔ Please enter the password to decrypt the provisioner key:\n✔ CA: \n✔ Certificate: localhost.crt\n✔ Private Key: localhost.key\n\nNow save a copy of your root CA certificate:\nstep ca root root_ca.crt\n\nOutput:\nThe root certificate has been saved in root_ca.crt.\n\nNext, let's launch a web server secured by HTTPS:\n{\ncat < server.py\nimport BaseHTTPServer, ssl\n\nclass HelloHandler(BaseHTTPServer.BaseHTTPRequestHandler):\n def do_GET(self):\n self.send_response(200);\n self.send_header('content-type', 'text/html; charset=utf-8');\n self.end_headers()\n self.wfile.write(b'\\\\n\\\\xf0\\\\x9f\\\\x91\\\\x8b Hello! Welcome to TLS \\\\xf0\\\\x9f\\\\x94\\\\x92\\\\xe2\\\\x9c\\\\x85\\\\n\\\\n')\n\nhttpd = BaseHTTPServer.HTTPServer(('', 8443), HelloHandler)\nhttpd.socket = ssl.wrap_socket(httpd.socket,\n server_side=True,\n keyfile=\"localhost.key\",\n certfile=\"localhost.crt\",\n ca_certs=\"root_ca.crt\")\nhttpd.serve_forever()\nEOF\n\npython server.py\n}\n\nOpen up another terminal to see your server running:\n$ curl https://localhost:8443\n👋 Hello! Welcome to TLS 🔒✅\n\n\n\nFurther Reading\n\n[step Documentation](https://smallstep.com/docs/step-cli)\nGetting Started\nGitHub Repository\n\nTroubleshooting\nRaspberry Pi Badger database errors\nWhen you run step-ca on a Raspberry Pi, you might get the following error in\nyour container logs:\nstep-ca | badger 2021/05/08 20:13:12 INFO: All 0 tables opened in 0s\nstep-ca | Error opening database of Type badger with source /home/step/db: error opening Badger database: Mmap value log file. Path=/home/step/db/000000.vlog. Error=cannot allocate memory\n\n\nTo fix it, edit the db configuration block in the file config/ca.json.\ndocker run -v step:/home/step -it smallstep/step-ca vi /home/step/config/ca.json\n\nChange the value of badgerFileLoadingMode from \"\" to \"FileIO\".\nYou will end up with this:\n \"db\": {\n \"type\": \"badger\",\n \"dataSource\": \"/home/step/db\",\n \"badgerFileLoadingMode\": \"FileIO\"\n },\n\nSave and restart the container.","length":7833,"excerpt":"This guide will illustrate how to run open source step-ca inside a Docker container.\nAs an example, you will send secure communications between a standalone webserver and curl.","siteName":null}