step
is a toolkit for working with your public key infrastructure (PKI). It's also the client counterpart to the step-ca
online Certificate Authority (CA).
Here's a quick example, combining step oauth
and step crypto
to get and verify the signature of a Google OAuth OIDC token:
Questions? Find us on gitter.
Website | Documentation | Installation Guide | Examples | FAQs | Contribution Guide
Step CLI's command groups illustrate some of its uses:
-
step certificate
: Work with X.509 (TLS/HTTPS) certificates.- Create, revoke, validate, lint, and bundle X.509 certificates.
- Install (and remove) X.509 certificates into your system's (and brower's) trust store.
- Create key pairs (RSA, ECDSA, EdDSA) and certificate signing requests (CSRs)
- Sign CSRs
- Create RFC5280 and CA/Browser Forum-compliant certificates that work for TLS and HTTPS
- Create CA certificates (root and intermediate signing certificates)
- Create self-signed & CA-signed certificates
- Inspect and lint certificates on disk or in use by a remote server
- Install root certificates so your CA is trusted by default (issue development certificates that work in browsers)
-
step ca
: Set up your own CA, or make requests of any ACMEv2 (RFC8555) CA, includingstep-ca
. ACME is the protocol used by Let's Encrypt to automate the issuance of HTTPS certificates.- Initialize an X.509 and/or SSH CA in one command
- Authenticate and obtain a certificate using any enrollment mechanism supported by
step-ca
- Securely distribute root certificates and bootstrap PKI relying parties
- Renew and revoke certificates issued by
step-ca
- Submit CSRs to be signed by
step-ca
-
step crypto
: A general-purpose crypto toolkit- Work with JWTs (RFC7519) and other JOSE constructs
- Sign, verify, and inspect JSON Web Tokens (JWTs)
- Sign, verify, and inspect arbitrary data using JSON Web Signature (JWS)
- Encrypt and decrypt data and wrap private keys using JSON Web Encryption (JWE)
- Create JWKs and manage key sets for use with JWT, JWE, and JWS
- Generate and verify TOTP tokens for multi-factor authentication (MFA)
- Work with NaCl's high-speed tools for encryption and signing
- Apply key derivation functions (KDFs) and verify passwords using
scrypt
,bcrypt
, andargo2
- Generate and check file hashes
- Work with JWTs (RFC7519) and other JOSE constructs
-
step oauth
: Add an OAuth 2.0 single sign-on flow to any CLI application.- Supports OAuth authorization code, out-of-band (OOB), JWT bearer, and refresh token flows
- Get OAuth access tokens and OIDC identity tokens at the command line from any provider.
- Verify OIDC identity tokens (
step crypto jwt verify
)
-
step ssh
: Create and manage SSH certificates (requires an online or offlinestep-ca
instance)- Generate SSH user and host key pairs and short-lived certificates
- Add and remove certificates to the SSH agent
- Inspect SSH certificates
- Login and use single sign-on SSH
These instructions will install the step
binary on your local machine. To build from source, see getting started with development.
Install step
via Homebrew:
$ brew install step
Download and install the Debian package from our latest release:
$ wget https://github.com/smallstep/cli/releases/download/vX.Y.Z/step-cli_X.Y.Z_amd64.deb
$ sudo dpkg -i step-cli_X.Y.Z_amd64.deb
We are using the Arch User Repository to distribute
step
binaries for Arch Linux.
- The
step-cli
binary tarball can be found here. - The
step-ca
binary tarball (for step certificates - a sibling repository) can be found here.
You can use pacman to install the packages.
We have amd64
, arm64
, and armv7
releases available to download from our latest release.
$ step certificate inspect https://smallstep.com
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 326381749415081530968054238478851085504954 (0x3bf265673332db2d0c70e48a163fb7d11ba)
Signature Algorithm: SHA256-RSA
Issuer: C=US,O=Let's Encrypt,CN=Let's Encrypt Authority X3
Validity
Not Before: Feb 8 13:07:44 2019 UTC
Not After : May 9 13:07:44 2019 UTC
Subject: CN=smallstep.com
[...]
This example assumes you already have step-ca
running at https://ca.local
.
Get your root certificate fingerprint (run this on the step-ca
server):
$ step certificate fingerprint $(step path)/certs/root_ca.crt
0eea955785796f0a103637df88f29d8dfc8c1f4260f35c8e744be155f06fd82d
On a new machine, connect to step-ca
and configure your local CA client:
$ step ca bootstrap --ca-url https://ca.local \
--fingerprint 0eea955785796f0a103637df88f29d8dfc8c1f4260f35c8e744be155f06fd82d
Now create a key pair, generate a CSR, and get a certificate from step-ca
:
$ step ca certificate foo.local foo.crt foo.key
Use the arrow keys to navigate: โ โ โ โ
What provisioner key do you want to use?
โธ [email protected] (JWK) [kid: XXX]
โ Please enter the password to decrypt the provisioner key: ...
โ CA: https://ca.local
โ Certificate: foo.crt
โ Private Key: foo.key
Use step certificate inspect
to check our work:
$ step certificate inspect --short foo.crt
X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2982...2760]
Subject: foo.local
Issuer: Intermediate CA
Provisioner: [email protected] [ID: EVct...2B-I]
Valid from: 2019-08-31T00:14:50Z
to: 2019-09-01T00:14:50Z
Renew a certificate, using the CA's default validity policy:
$ step ca renew foo.crt foo.key --force
Your certificate has been saved in foo.crt.
Revoke a certificate:
$ step ca revoke --cert foo.crt --key foo.key
โ CA: https://ca.local
Certificate with Serial Number 202784089649824696691681223134769107758 has been revoked.
$ step ca renew foo.crt foo.key --force
error renewing certificate: Unauthorized
You can install your root certificate locally:
$ step certificate install $(step path)/certs/root_ca.crt
Now, all certificates issued by your CA will work in your browser and with tools like curl
. See our blog post for more info.
Alternatively, for internal service-to-service communication, you can configure your code and infrastructure to trust your root certificate.
The step certificate
command group can also be used to create an offline CA and self-signed certificates.
Create a self-signed certificate:
$ step certificate create foo.local foo.crt foo.key --profile self-signed --subtle
Your certificate has been saved in foo.crt.
Your private key has been saved in foo.key.
Create a root CA, an intermediate, and a leaf X.509 certificate. Bundle the leaf with the intermediate for use with TLS:
$ step certificate create --profile root-ca \
"Example Root CA" root-ca.crt root-ca.key
Please enter the password to encrypt the private key:
Your certificate has been saved in root-ca.crt.
Your private key has been saved in root-ca.key.
$ step certificate create \
"Example Intermediate CA 1" intermediate-ca.crt intermediate-ca.key \
--profile intermediate-ca --ca ./root-ca.crt --ca-key ./root-ca.key
Please enter the password to decrypt ./root-ca.key:
Please enter the password to encrypt the private key:
Your certificate has been saved in intermediate-ca.crt.
Your private key has been saved in intermediate-ca.key.
$ step certificate create \
example.com example.com.crt example.com.key \
--profile leaf --ca ./intermediate-ca.crt --ca-key ./intermediate-ca.key
Please enter the password to decrypt ./intermediate-ca.key:
Please enter the password to encrypt the private key:
Your certificate has been saved in example.com.crt.
Your private key has been saved in example.com.key.
$ step certificate bundle \
example.com.crt intermediate-ca.crt example.com-bundle.crt
Your certificate has been saved in example.com-bundle.crt.
Extract the expiration date from a certificate (requires
jq
):
$ step certificate inspect example.com.crt --format json | jq -r .validity.end
2019-02-28T17:46:16Z
$ step certificate inspect https://smallstep.com --format json | jq -r .validity.end
2019-05-09T13:07:44Z
Create a JSON Web Key (JWK), add the public key to a keyset, and sign a JSON Web Token (JWT):
$ step crypto jwk create pub.json key.json
Please enter the password to encrypt the private JWK:
Your public key has been saved in pub.json.
Your private key has been saved in key.json.
$ cat pub.json | step crypto jwk keyset add keys.json
$ JWT=$(step crypto jwt sign \
--key key.json \
--iss "[email protected]" \
--aud "[email protected]" \
--sub "[email protected]" \
--exp $(date -v+15M +"%s"))
Please enter the password to decrypt key.json:
# Verify your JWT and return the payload:
$ echo $JWT | step crypto jwt verify \
--jwks keys.json --iss "[email protected]" --aud "[email protected]"
{
"header": {
"alg": "ES256",
"kid": "X6yaHYNyxr-psAqvSNKCWc9oYDetvGdo2n2PSRZjxss",
"typ": "JWT"
},
"payload": {
"aud": "[email protected]",
"exp": 1551290879,
"iat": 1551289983,
"iss": "[email protected]",
"nbf": 1551289983,
"sub": "[email protected]"
},
"signature": "JU7fPGqBJcIfauJHA7KP9Wp292g_G9s4bLMVLyRgEQDpL5faaG-3teJ81_igPz1zP7IjHmz8D6Gigt7kbnlasw"
}
Here we'll use step
to run through an OAuth 2.0 authorization code flow with Google, and obtain an OIDC token. You'll need an OAuth Client ID and Client Secret from Google Cloud Platform's Credentials panel.
Login with Google and obtain an OAuth OIDC identity token for single sign-on:
$ step oauth \
--provider https://accounts.google.com \
--client-id 1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com \
--client-secret udTrOT3gzrO7W9fDPgZQLfYJ \
--bare --oidc
Your default web browser has been opened to visit:
https://accounts.google.com/o/oauth2/v2/auth?client_id=[...]
xxx-google-xxx.yyy-oauth-yyy.zzz-token-zzz
That outputs the raw JWT. Now let's decode it and verify its signature:
$ step oauth \
--provider https://accounts.google.com \
--client-id 1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com \
--client-secret udTrOT3gzrO7W9fDPgZQLfYJ \
--bare --oidc \
| step crypto jwt verify \
--jwks https://www.googleapis.com/oauth2/v3/certs \
--iss https://accounts.google.com \
--aud 1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com
Your default web browser has been opened to visit:
https://accounts.google.com/o/oauth2/v2/auth?client_id=[...]
{
"header": {
"alg": "RS256",
"kid": "f24d6a1930669cb75f19",
"typ": "JWT"
},
"payload": {
"iss": "https://accounts.google.com",
"azp": "1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com",
"aud": "1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com",
"sub": "103209689286000948507",
"hd": "smallstep.com",
"email": "[email protected]",
"email_verified": true,
"at_hash": "euBvS34BVu0SJQ-EsbBT3A",
"iat": 1551293134,
"exp": 1551296734
},
"signature": "[...]"
}
Here's another flow. Let's use step
to get a Google bearer token using OAuth 2.0, make an HTTP Authorization:
header from it, and use curl
to make a request to Google's APIs:
$ curl -H"$(step oauth --header)" https://www.googleapis.com/oauth2/v3/userinfo
Your default web browser has been opened to visit:
https://accounts.google.com/o/oauth2/v2/auth?client_id=1087160488420-AAAAAAAAAAAAAAA.apps.googleusercontent.com&code_challenge=XXXXX
{
"sub": "AAAAAAAAAAAAA",
"picture": "https://lh6.googleusercontent.com/photo.jpg",
"email": "[email protected]",
"email_verified": true,
"hd": "smallstep.com"
}
Generate a TOTP token and a QR code:
$ step crypto otp generate \
--issuer smallstep.com --account [email protected] \
--qr smallstep.png > smallstep.totp
Scan the QR Code (smallstep.png
) using Google Authenticator, Authy or similar
software and use it to verify the TOTP token:
$ step crypto otp verify --secret smallstep.totp
- Connect with
step
users on Gitter - Open an issue and tell us what features you'd like to see
- Follow Smallstep on Twitter
- We have more examples of
step
andstep-ca
in action on the Smallstep blog. - If you're new to PKI and X.509 certificates, or you want a refresher on the core concepts, you may enjoy Everything PKI.