An open source solution for secure automated certificate management

At smallstep we've been focused, lately, on building technology that makes it easier for you to access your stuff. As things stand today, access is really hard. It's really hard for developers to access internal services in production and pre-production environments (e.g., to debug using curl ). It's really hard for your stuff running in AWS to access your stuff running in GCP and vice-versa. It's really hard for employees to access enterprise IT applications from their iPhones while they're on the bus heading into work. Supporting these use cases, and dozens more like them, is so hard that it's often not done. Access that would make people more productive, make systems better, reduce costs, improve performance, and generally improve software and employee well-being is simply denied. That sucks.

There's a simple and universal answer that makes access easy. Fundamentally, if you're able to authenticate the identities of two things that are trying to communicate, and if that communication is encrypted, nothing else matters. Instead of relying on trusted networks, access can be authorized based on identity, and security can be guaranteed cryptographically. Even better, you can ditch VPNs and whatever operational nightmare powers your network policy rube goldberg machine. For code and devices it's actually really easy to do this using TLS. But there's a catch: to use TLS you need certificates — a sort of credential that TLS uses for authentication.

Certificates are the best way to identify code and devices. The problem is that certificate management is really hard. So hard, and so abstruse, that many people assume it's not for them… or at least not worth their while. That's wrong. It is. But it's true that there's no good way to automate the secure delivery of certificates to devices and workloads, and to manage certificate lifecycle (renewal and whatnot). That's why we built step certificates (GitHub). It's an open source project that makes secure automated certificate management easy, so you can use TLS and easily access anything, running anywhere, from everywhere.

step certificates open sourced on GitHub: Star Watch Fork

Before we start, you might want to install step so you can follow along.

On macOS using brew:

$ brew install step

Binary tarballs are also available for Linux. For instructions on building from source see GitHub.

More than a Certificate Authority

At the core of step certificates is an online certificate authority (CA): a piece of infrastructure that most production environments don't have (but should). A CA signs certificates. Other components verify certificates by checking signatures. The step CA is lightweight, fast, and easy to operate. It scales horizontally, and multiple instances can be deployed for high availability.

But step certificates is more than a certificate authority. It provides all the missing bits you need to run your own internal public key infrastructure (PKI). It exposes APIs and extends the step CLI (blog, GitHub) with subcommands to fill all the gaps that keep internal PKI out of reach for most teams and organizations. It's all the stuff you need to issue certificates everywhere, and to securely access your stuff from anywhere using TLS.

To use TLS your code and devices need to generate keys and obtain certificates from the CA. The root certificate that belongs to the CA also needs to be distributed everywhere (it's used to verify certificate signatures). Certificates expire and stop working, so they need to be renewed before that happens. These processes need to be secure. They also need to be automated. Step certificates does all this and more.

Let's look at some example workflows to see how.

Generating keys and getting certificates

Once you have a CA up and running, step certificates makes generating keys and obtaining a certificate trivial. You need just one simple command:

$ step ca certificate \ > --ca-url https://127.0.0.1:4443 svc.example.com svc.crt svc.key ✔ Key ID: ngipT8B4OflglLFbHeoUALBqgbcf2mxRyvXLIbwqPHI (mike@example.com) Please enter the password to decrypt the provisioner key: ✔ CA: https://127.0.0.1:4443/1.0/sign

The positional arguments in the step ca certificate command indicate the name we'd like bound in the certificate (e.g., the DNS host name of a service) and the filenames to write the certificate and private key out to.

We can check our work using step certificate inspect :

$ step certificate inspect svc.crt Certificate: Data: Version: 3 (0x2) Serial Number: 99511617599707626862884213396651347299 (0x4add3d8bd5dccde77b1822af06038d63) Signature Algorithm: ECDSA-SHA256 Issuer: CN=Smallstep Intermediate CA Validity Not Before: Dec 8 00:27:47 2018 UTC Not After : Dec 9 00:27:47 2018 UTC Subject: CN=svc.example.com Subject Public Key Info: Public Key Algorithm: ECDSA Public-Key: (256 bit) X: 46:84:96:f3:f9:12:cc:36:e4:40:15:a9:d0:e1:39: 15:ae:36:49:7e:77:39:bb:c4:b9:0f:8a:da:3e:88: 33:5b Y: c7:59:12:eb:7e:76:b4:d1:f8:9e:19:07:c0:81:a9: 1a:c5:25:33:ee:16:9b:76:d4:c2:10:bf:9d:45:e6: d0:23 Curve: P-256 X509v3 extensions: X509v3 Key Usage: critical Digital Signature, Key Encipherment X509v3 Extended Key Usage: TLS Web Server Authentication, TLS Web Client Authentication X509v3 Subject Key Identifier: 11:E7:0C:13:59:99:1F:ED:C5:DB:FE:CD:84:A1:E9:98:64:9D:E6:53 X509v3 Authority Key Identifier: keyid:F5:56:DA:43:03:26:5C:3B:01:20:E7:48:47:2C:89:47:05:AE:24:53 X509v3 Subject Alternative Name: DNS:svc.example.com X509v3 Step Provisioner: Type: JWK Name: puppet CredentialID: 9-xRy5cOcz95L_JrsRy9VdPBccXcgmli-xkVMkkDMb4 Signature Algorithm: ECDSA-SHA256 30:45:02:21:00:b1:34:bd:fc:84:c2:63:5c:9d:9c:27:06:f9: f0:b9:d0:e5:5a:5e:5f:c1:3a:ef:2b:92:48:99:2e:f1:b4:1b: 97:02:20:4b:4b:f7:44:9c:02:62:b8:50:75:1d:54:61:98:b4: 62:a9:34:b4:6c:4e:8e:31:44:4e:a8:1f:67:8a:8a:ef:6c

If you already have a certificate signing request, that's fine too. Just use step ca sign instead:

$ step certificate create --csr foo.example.com foo.csr foo.key Please enter the password to encrypt the private key: $ step ca sign --ca-url https://127.0.0.1:4443 foo.csr foo.crt ✔ Key ID: ngipT8B4OflglLFbHeoUALBqgbcf2mxRyvXLIbwqPHI (mike@example.com) Please enter the password to decrypt the provisioner key: ✔ CA: https://127.0.0.1:4443/1.0/sign

Subscribe to updates Unsubscribe anytime, see Privacy Policy

Using certificates with TLS

As mentioned, clients and servers need to be configured to use the CA's root certificate. step can grab this root certificate from the CA and verify it using a fingerprint (which can be produced using step certificate fingerprint and embedded in scripts):

$ step certificate fingerprint $(step path)/certs/root_ca.crt 88396437f52fce12d8e281cb4f30dc8cdab3a7b69fc801d1b1407719dfad5fe2 $ step ca root --ca-url https://127.0.0.1:4443 \ > --fingerprint 88396437f52fce12d8e281cb4f30dc8cdab3a7b69fc801d1b1407719dfad5fe2 \ > root.crt $ step certificate inspect root.crt Certificate: Data: Version: 3 (0x2) Serial Number: 97076258001818714665341080528039489243 (0x4908350c345c28a45b766721789caedb) Signature Algorithm: ECDSA-SHA256 Issuer: CN=Smallstep Root CA Validity Not Before: Dec 7 23:20:20 2018 UTC Not After : Dec 4 23:20:20 2028 UTC Subject: CN=Smallstep Root CA Subject Public Key Info: Public Key Algorithm: ECDSA Public-Key: (256 bit) X: f8:38:f7:6a:a8:ae:d9:3f:9e:4f:bc:47:5d:b1:04: ea:89:1a:8c:22:d9:7b:2b:69:d4:f6:5f:54:f5:27: 95:13 Y: de:7b:bc:59:67:3f:c3:13:4d:46:ad:9f:fd:aa:a1: b2:21:be:7a:cd:90:f4:33:dc:fd:1e:dd:44:f8:eb: 0e:34 Curve: P-256 X509v3 extensions: X509v3 Key Usage: critical Digital Signature, Key Encipherment, Certificate Sign, CRL Sign X509v3 Basic Constraints: critical CA:TRUE, pathlen:1 X509v3 Subject Key Identifier: A1:22:E7:72:B1:5B:AA:06:CD:CA:EF:13:7E:9D:4B:DE:63:6E:13:B3 Signature Algorithm: ECDSA-SHA256 30:44:02:20:69:f8:69:59:84:a9:9a:6c:59:7f:73:27:0c:3d: eb:a2:c5:58:bb:e0:34:0c:a5:ec:6c:70:83:61:02:29:c0:93: 02:20:4c:b0:78:bf:e0:03:1d:6d:14:a6:5d:86:66:b3:22:7e: ea:38:8b:c6:7b:1c:f0:f1:ad:cb:2e:0a:36:7f:ba:37

You can use this root certificate to curl a service using TLS:

$ curl --cacert root.crt https://svc.example.com hi

If your service requires mutual authentication (mTLS) you can also generate a short-lived certificate for yourself, for client authentication with curl :

$ step ca certificate mike@example.com mike.crt mike.key \ > --not-after 10m \ > --ca-url https://127.0.0.1:4443 $ curl --cacert root.crt --cert mike.crt --key mike.key https://svc.example.com hi

If work takes longer than expected, you can use step to renew this certificate before it expires:

$ step certificate inspect mike.crt --format json | jq .validity.end "2018-12-07T23:37:16Z" $ step ca renew mike.crt mike.key --ca-url https://127.0.0.1:4443 Would you like to overwrite mike.crt [Y/n]: Y $ step certificate inspect mike.crt --format json | jq .validity.end "2018-12-07T23:40:43Z"

Setting up services to use these certificates is generally not that hard (though it helps to have a good understanding of how certificates and PKI work). One nice thing about TLS is that you have the option of baking it into your applications for complete end-to-end encryption or deploying a sidecar proxy to terminate TLS with no code change required. Let's look quickly at both scenarios.

Baking TLS into an application might sound hard, but once you have certificates it's really not that bad. You'll have to check out the docs for your language or framework for particulars but, generally, you'll just need to parameterize some TLS API with your root certificate, leaf certificate, and private key. Here's a working example in golang:

package main import ( "net/http" "log" ) func HiHandler(w http.ResponseWriter, req *http.Request) { w.Header().Set("Content-Type", "text/plain") w.Write([]byte("Hello, world!

")) } func main() { http.HandleFunc("/hi", HiHandler) err := http.ListenAndServeTLS(":8443", "svc.crt", "svc.key", nil) if err != nil { log.Fatal(err) } }

There's still some work to do because this certificate will eventually expire. We'll need to renew and rotate it somehow before that happens. If you're doing end-to-end TLS like this, the only thing that ever needs the private key is the application itself. So it's unfortunate that we're generating the private key outside the application and putting it on disk. Fixing all this is a bit more work. To make all of this easy, step certificates includes a golang SDK that generates keys and obtains a certificate for you and will automatically renew it before it expires. There's an example in the step certificates repository. Another example provides a more thorough demonstration of everything the SDK can do.

We'd like to provide SDKs for other languages. Right now it's golang only. This is a relatively easy and high value area to contribute, if anyone's interested!

If you'd rather not change any code, pretty much every proxy can do [m]TLS with a bit of light configuration. For this sort of deployment you can throw step ca renew in a cron job with the --expires-in and --force flags to keep your certificates fresh. Some proxies require a kill -HUP to pick up the new certificates, so consult your docs.

So far we've used step ca certificate to generate a key pair, construct a certificate signing request (CSR), and make an authenticated request to the CA to obtain a certificate with a single command. To authenticate we've been prompted for a password to decrypt a provisioner key. A provisioner is simply a thing that's authorized by the CA to assign names and enroll people and things in your PKI (i.e., get certificates). We'll discuss how all this works in more detail in the next section.

Provisioners are specified simply in the CA's configuration file, located by default at $(step path)/config/ca.json . You can use step to manage this file, or edit it directly. A single provisioner is added automatically when the CA is first initialized, but you can add more by creating a key pair and registering it with the CA (i.e., adding the provisioner's name and key to the CA configuration file). If you do add multiple provisioners, you'll be prompted to select which to use when you create certificates.

$ step crypto jwk create puppet.pub.json puppet.key.json Please enter the password to encrypt the private JWK: $ step ca provisioner add \ > --ca-config $(step path)/config/ca.json \ > puppet puppet.key.json Please enter the password to decrypt puppet.key.json: Please enter the password to encrypt the private JWK: $ step ca certificate \ > --not-after 10m \ > --ca-url https://127.0.0.1:4443 \ > max@example.com max.crt max.key Use the arrow keys to navigate: ↓ ↑ → ← What provisioner key do you want to use? ngipT8B4OflglLFbHeoUALBqgbcf2mxRyvXLIbwqPHI (mike@example.com) ▸ 9-xRy5cOcz95L_JrsRy9VdPBccXcgmli-xkVMkkDMb4 (puppet)

Interactive workflows and passwords make sense for people, but they're no good for automation. Let's take a closer look at the bootstrapping protocol and, more broadly, at how step certificates makes it easy to automate certificate management.

Automated Certificate Management

Provisioners are instrumental in facilitating automation. Name assignments are made via signed attestations that are generated by the provisioner, passed to the thing being provisioned, then used to authenticate certificate requests submitted to the CA — to obtain a certificate.

The hardest problem here is securing this first interaction between a thing that needs a certificate and the CA. Authentication is required, but we can't use certificates because a thing that needs a certificate obviously doesn't have one yet.

What's needed is some trusted component that can measure and attest to the identity of a thing that needs a certificate. For systems under operational automation, the right tool for this job is whatever's already being used to provision systems and deploy code: Puppet, Chef, Ansible, Kubernetes, Terraform, etc. You already trust this stuff to deploy the right code to the right places. To do so these tools must have some notion of identity. So they're trusted and capable of assigning names and signing attestations. The stuff you're already using for provisioning should be your step certificates “provisioner” (hence the name). Step certificates makes using these tools for this purpose super easy. That's how we automate certificate management.

Summarizing, provisioners help authenticate the initial request for a certificate. They do this by putting the name of the thing being provisioned in an attestation that the CA can verify: a short-lived one-time token called a bootstrap token. Bootstrap tokens are signed by the provisioner's private key, and passed to whatever's being provisioned to authenticate with the CA.

The unified step ca certificate command we used above is actually a wrapper around this more elaborate process. For automation we'll break this process into its constituent parts. The bootstrap token will be generated in one place and used in another.

If you're confused, an example should clear things up. Let's start by generating a bootstrap token for svc.example.com and use it to obtain a certificate:

$ step ca token --ca-url https://127.0.0.1:4443 svc.example.com ✔ Key ID: 9-xRy5cOcz95L_JrsRy9VdPBccXcgmli-xkVMkkDMb4 (puppet) Please enter the password to decrypt the provisioner key: eyJhbGciOiJFUzI1NiIsImtpZCI6IjkteFJ5NWNPY3o5NUxfSnJzUnk5VmRQQmNjWGNnbWxpLXhrVk1ra0RNYjQiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovLzEyNy4wLjAuMTo0NDQzLzEuMC9zaWduIiwiZXhwIjoxNTQ0MjQ3MTE5LCJpYXQiOjE1NDQyNDY4MTksImlzcyI6InB1cHBldCIsImp0aSI6IjMyNDViN2Y5MmJjYjA1NjIxNDNlZWNhYWRjYzQ3ZWI5Y2NmYjdiNDIzYzVkODUzNTg1NGNiOTE5MDAzOTE4MWMiLCJuYmYiOjE1NDQyNDY4MTksInNoYSI6Ijg4Mzk2NDM3ZjUyZmNlMTJkOGUyODFjYjRmMzBkYzhjZGFiM2E3YjY5ZmM4MDFkMWIxNDA3NzE5ZGZhZDVmZTIiLCJzdWIiOiJzdmMuZXhhbXBsZS5jb20ifQ.kqvZ4UdZSJI3sPEWVHqVBFB3xtnTwgDaho4ud-nOr8l5D37lvuFrfIxpWXZY1fZq0rU9mkYAr8mP7s8J2OLegA

This opaque looking token is actually a JWT: an RFC standard, JSON-based, base64-encoded signed assertion with good library support in pretty much every programming language. For fun, let's take a peek at the token contents (using step crypto jwt inspect ):

$ step ca token --ca-url https://127.0.0.1:4443 svc.example.com \ > | step crypto jwt inspect --insecure ✔ Key ID: 9-xRy5cOcz95L_JrsRy9VdPBccXcgmli-xkVMkkDMb4 (puppet) Please enter the password to decrypt the provisioner key: { "header": { "alg": "ES256", "kid": "9-xRy5cOcz95L_JrsRy9VdPBccXcgmli-xkVMkkDMb4", "typ": "JWT" }, "payload": { "aud": "https://127.0.0.1:4443/1.0/sign", "exp": 1544247162, "iat": 1544246862, "iss": "puppet", "jti": "5de525fc8e6aea2c78a3fca50b537dc212a0441db97224aab1e88e2a69048f7d", "nbf": 1544246862, "sha": "88396437f52fce12d8e281cb4f30dc8cdab3a7b69fc801d1b1407719dfad5fe2", "sub": "svc.example.com" }, "signature": "AG4vyZDDjI3Wn9y_E6vP9xhZAI9-5iEK4XnCSWccpa0B5yoxqn9JcImbnheuaB2L1ICVr2wsJ0tJKG8efYDvxw" }

The best way to generate bootstrap tokens and get them where they're needed depends on which tools you're using and the particulars of your environment. Stay tuned for more guidance here as we document best practices for various tools.

For now, in general, the easiest thing to do is to place the private key on a machine that's been locked down and is only accessible by your configuration management or orchestration system. With a provisioner's unencrypted private key available, a bootstrap token can be generated non-interactively to support automation:

$ step crypto jwe decrypt < puppet.key.json > puppet-cleartext.key.json Please enter the password to decrypt the content encryption key: $ step ca token svc.example.com \ > --offline \ > --kid 9-xRy5cOcz95L_JrsRy9VdPBccXcgmli-xkVMkkDMb4 \ > --issuer puppet \ > --key puppet-cleartext.key.json \ > --ca-url https://127.0.0.1:443 eyJhbGciOiJFUzI1NiIsImtpZCI6IjkteFJ5NWNPY3o5NUxfSnJzUnk5VmRQQmNjWGNnbWxpLXhrVk1ra0RNYjQiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovLzEyNy4wLjAuMTo0NDMvMS4wL3NpZ24iLCJleHAiOjE1NDQyMjg2NjIsImlhdCI6MTU0NDIyODM2MiwiaXNzIjoicHVwcGV0IiwianRpIjoiZGJkZTEwN2E2OTg1YjNmMDc4ZTA1NDU2MDAzNjc1YzY2ZDk1M2FlOGYyN2U1ZGM0ODhhNDRkNmQ3YWRkNzE1YSIsIm5iZiI6MTU0NDIyODM2Miwic2hhIjoiODgzOTY0MzdmNTJmY2UxMmQ4ZTI4MWNiNGYzMGRjOGNkYWIzYTdiNjlmYzgwMWQxYjE0MDc3MTlkZmFkNWZlMiIsInN1YiI6InN2Yy5leGFtcGxlLmNvbSJ9.82nW7kAAbd8H3W_HypU003nilbpGkbUl33HRSVqZDFfzBEcK3UbDwY3DQYijnVE-YIJ3hUAytIWU-_qI8up1cw

The various flags here specify which provisioner to use (the key ID and issuer). You can get this information using step ca provisioner list .

Once a token has been generated it can be transmitted and used locally wherever a certificate is required:

$ export TOKEN="eyJhbGciOiJFUzI1NiIsImtpZCI6IjkteFJ5NWNPY3o5NUxfSnJzUnk5VmRQQmNjWGNnbWxpLXhrVk1ra0RNYjQiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJodHRwczovLzEyNy4wLjAuMTo0NDMvMS4wL3NpZ24iLCJleHAiOjE1NDQyMjg2NjIsImlhdCI6MTU0NDIyODM2MiwiaXNzIjoicHVwcGV0IiwianRpIjoiZGJkZTEwN2E2OTg1YjNmMDc4ZTA1NDU2MDAzNjc1YzY2ZDk1M2FlOGYyN2U1ZGM0ODhhNDRkNmQ3YWRkNzE1YSIsIm5iZiI6MTU0NDIyODM2Miwic2hhIjoiODgzOTY0MzdmNTJmY2UxMmQ4ZTI4MWNiNGYzMGRjOGNkYWIzYTdiNjlmYzgwMWQxYjE0MDc3MTlkZmFkNWZlMiIsInN1YiI6InN2Yy5leGFtcGxlLmNvbSJ9.82nW7kAAbd8H3W_HypU003nilbpGkbUl33HRSVqZDFfzBEcK3UbDwY3DQYijnVE-YIJ3hUAytIWU-_qI8up1cw" $ step ca certificate --token $TOKEN svc.example.com svc.crt svc.key ✔ CA: https://127.0.0.1:4443/1.0/sign

Starting the CA

To wrap up our demo let's initialize a CA from scratch and start it running.

Like provisioner management, step certificates provides a command line workflow to simplify initial configuration. It asks you a couple questions then writes a working configuration to the default location:

$ step ca init ✔ What would you like to name your new PKI? (e.g. Smallstep): Smallstep ✔ What DNS/IP address(es) will your CA use? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): 127.0.0.1 ✔ What address will your new CA listen on? (e.g. :443): :4443 ✔ What would you like to name your first provisioner? (e.g. you@example.com): mike@example.com ✔ What do you want your password to be? [leave empty and we'll generate one]: Generating root certificate... all done! Generating intermediate certificate... all done! ✔ Root certificate: ~/.step/certs/root_ca.crt ✔ Root private key: ~/.step/secrets/root_ca_key ✔ Root fingerprint: 922eb076c7430e5b0ceca3a2be13a7329f7879a2c35a514017554cb11fd1c249 ✔ Intermediate certificate: ~/.step/certs/intermediate_ca.crt ✔ Intermediate private key: ~/.step/secrets/intermediate_ca_key ✔ Certificate Authority configuration: ~/.step/config/ca.json Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.

If you have an existing PKI, step certificates can also federate or operate as a subordinate to your existing root. See the documentation for step ca init for more information.

That's it. Once you've run this initialization process you're ready to go. The online certificate authority itself ships as a separate binary called step-ca , so it's not necessary to have step installed to run the CA (though it doesn't hurt and is useful to have available).

All that's left is to start the CA:

$ step-ca $(step path)/config/ca.json Please enter the password to decrypt ~/.step/secrets/intermediate_ca_key: 2018/12/07 17:49:59 Serving HTTPS on :4443 …

Roadmap

Everything documented here is ready to go, but we've got a long roadmap of features we'd like to add to step certificates in the future. We're committed to open source — we believe everyone deserves world class PKI — and we're also working on an enterprise offering to better integrate in enterprise environments and address enterprise-specific use cases. We'd love your input on where to draw the line between these two offerings.

Anyways, there are a bunch of advanced features to add like revocation (CRL and OCSP), HSM support, and certificate transparency (CT). We'd also like to add a UI to supplement the command line tool and to help with certificate management (e.g., present a searchable certificate inventory built off of CT). The bootstrap protocol is great, but we'd like to support alternative authentication mechanisms like mTLS and OAuth OIDC for agent-based certificate provisioning and to allow people to easily obtain certificates for themselves, respectively. Bootstrapping was designed to be simple and universal for MVP, but we'd like to harden the protocol with support for additional factors like instance identity documents in cloud environments and MFA for people. As mentioned, we'd also like to provide SDKs in other languages.

Try it out

We'd love to hear from you if there are any other missing features, bugs, or oversights, and to help prioritize these existing ideas. If you have thoughts, please shoot us a tweet or open an issue on GitHub.

Please, clone, and fork us on GitHub! Step certificates builds on step CLI, so you might want to check that out too. We'd love to hear your feedback and merge your pull requests.

step certificates open sourced on GitHub: Star Watch Fork