Basic Crypto Operations Using step

Description

You don't need to run an online Certificate Authority to create certificates and perform basic crypto operations using the step CLI tool. This document gives some examples of things you can do with the step command by itself.

Overview

Here's a few common uses of the step command:

Requirements

Create and work with X.509 certificates

Let's take a look at the step certificate command group. This command group is a Swiss Army knife for working with certificates. You can use it to create certificate signing requests (CSRs), sign CSRs, create self-signed certificates (e.g., a root certificate authority), create leaf or intermediate CA certificates, validate and inspect certificates, renew certificates, generate certificate bundles, and to key-wrap private keys.

Shall we try it out?

Create a Certificate Authority

Create a Root CA:

Typically you will also want an intermediate CA. Create an Intermediate CA that is signed by your Root CA:

Now you can store your root_ca.key in a safe place offline, because you'll only need the intermediate CA key to issue TLS leaf certificates.

Issue a Leaf Certificate Bundle

Use your intermediate CA to sign leaf (end entity) certificates for your servers.

Create a leaf TLS certificate for example.com, valid for a year:

By using the --bundle flag we automatically bundle the new leaf certificate with the signing intermediate certificate. TLS-based services will require the bundle in order to verify the full chain.

Inspect an X.509 Certificate

To inspect the certificate you just made, run:

You can get a certificate in JSON format by calling step certificate inspect with --format json. This example uses jq to parse the JSON and extract a specific value:

You can also inspect the TLS certificate for any URL:

Get a TLS Certificate From Let's Encrypt

step is a full-fledged ACME client (the protocol used by Let's Encrypt. Unlike other ACME clients, step connects to a configured step-ca daemon by default. To use it with Let's Encrypt or another ACME server instead, you can pass an --acme endpoint:

This command will:

If you don't want step to run a standalone server to respond to the ACME challenge, you can pass --webroot <path> to specify a path where step will place the .well-known/acme-challenge/<TOKEN> token file.

For a dry run, you can use Let's Encrypt's staging server URL: https://acme-staging-v02.api.letsencrypt.org/directory

Generate JSON Web Tokens (JWTs) and JSON Web Keys (JWKs)

The following command groups work with JOSE objects like JWTs and JWEs:

In this example, you'll create a JSON Web Key (JWK), add the public key to a keyset, and sign a JSON Web Token (JWT) that expires in 15 minutes:

We can then verify the JWT and return the payload:

Obtain and Work With OAuth Tokens

The step oauth command group supports API authorization and single sign on with OAuth and OIDC.

This command group requires that you supply your own OAuth provider URL, client ID, and client secret.

Obtain OAuth OIDC Identity Tokens

In this example, we'll sign into Google and get an OIDC identity token. Replace the --client-id and --client-secret with your own values obtained from Google Cloud Console's APIs & Services menu.

The --provider URL must have a discovery endpoint, created by appending /.well-known/openid-configuration to the URL. This is a JSON file describing endpoints and keys for OpenID Connect. For example, see https://accounts.google.com/.well-known/openid-configuration.

Once you have an OIDC identity token, you can verify it. The --jwks value comes from the jwks_uri value at the OpenID discovery endpoint.

Miscellaneous Tools (TOTP Tokens, NaCl, SSH Certificates)

Generate TOTP Tokens for Multi-Factor Authentication (MFA)

With step crypto otp, you can generate a TOTP token and a QR code:

Scan the QR Code using Google Authenticator, Authy, or similar software and use it to verify the TOTP token:

Sign and Encrypt Arbitrary Data

You can use the step crypto nacl command group to sign or encrypt arbitrary data for internal use. This command group uses the NaCl library's high-speed crypto primitives.

Work with SSH Certificates

The step ssh command group is usually used in conjunction with step-ca's SSH CA functionality. But not all the subcommands require an SSH CA. You can inspect an SSH certificate:

And you can get the fingerprint of an SSH certificate or public key: