step is a zero trust swiss army knife that integrates with step-ca for automated certificate management. It's an easy-to-use and hard-to-misuse utility for building, operating, and automating systems that use zero trust technologies like authenticated encryption (X.509, TLS), single sign-on (OAuth OIDC, SAML), multi-factor authentication (OATH OTP, FIDO U2F), encryption mechanisms (JSON Web Encryption, NaCl), and verifiable claims (JWT, SAML assertions).
Website | Documentation | Installation Guide | Examples | Contribution Guide
step is a powerful security tool that's been carefully designed to be safe and easy to use, even if you don't have a favorite elliptic curve or if you're inclined to forget to check the aud when you verify a JWT.
- Safe and sane defaults everywhere encourage best practices by making the right thing easy
- Insecure or subtle operations are gated with flags to prevent accidental misuse
- In-depth help with examples is available via
step help
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
- Create key pairs (RSA, ECDSA, EdDSA) and certificate signing requests (CSRs)
- Create RFC5280 and CA/Browser Forum compliant X.509 certificates that work for TLS and HTTPS
- Create root and intermediate signing certificates (CA certificates)
- Create self-signed & CA-signed certificates, and sign CSRs
- 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)
- Get certificates from any ACME compliant CA (coming soon)
Connect to step-ca and get certificates from your own private certificate authority
- 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
- Get OAuth access tokens and OIDC identity tokens at the command line from any provider
- Supports OAuth authorization code, implicit, OOB, jwt-bearer, and refresh token flows
- Automatically launch browser to complete OAuth flow (or use console flow)
- Verify OIDC identity tokens (using
step crypt jwt verify) - Generate and verify TOTP tokens
- Work with NaCl box, secretbox, and sign constructs
- Apply key derivation functions (KDFs) and verify passwords using
scrypt,bcrypt, andargo2 - Generate and check file hashes
These instructions will install an OS specific version of the step binary on
your local machine. To build from source see getting started with
development below.
Install step via Homebrew:
$ brew install stepNote: If you have installed
steppreviously through thesmallstep/smallsteptap you will need to run the following commands before installing:$ brew untap smallstep/smallstep $ brew uninstall step
Download and install the latest Debian package from releases:
$ wget https://github.com/smallstep/cli/releases/download/vX.Y.Z/step-cli_X.Y.Z_amd64.deb
# Install the Debian package:
$ sudo dpkg -i step_X.Y.Z_amd64.debWe are using the Arch User Repository to distribute
step binaries for Arch Linux.
- The
step-clibinary tarball can be found here. - The
step-cabinary tarball (for step certificates - a sibling repository) can be found here.
You can use pacman to install the packages.
$ 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 from the machine running step-ca:
ca$ step certificate fingerprint $(step path)/certs/root_ca.crt
0eea955785796f0a103637df88f29d8dfc8c1f4260f35c8e744be155f06fd82dBootstrap a new machine to trust and connect to step-ca:
$ step ca bootstrap --ca-url https://ca.local \
--fingerprint 0eea955785796f0a103637df88f29d8dfc8c1f4260f35c8e744be155f06fd82dCreate 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?
▸ bob@smallstep.com (JWK) [kid: XXX]
Google (OIDC) [client: XXX.apps.googleusercontent.com]
Auth0 (OIDC) [client: XXX]
AWS IID Provisioner (AWS)
✔ CA: https://ca.local
✔ Certificate: foo.crt
✔ Private Key: foo.keyUse 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: bob@smallstep.com [ID: EVct...2B-I]
Valid from: 2019-08-31T00:14:50Z
to: 2019-09-01T00:14:50ZRenew certificate:
$ step ca renew foo.crt foo.key --force
Your certificate has been saved in foo.crt.Revoke 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: UnauthorizedYou can install your root certificate locally:
$ step certificate install $(step path)/certs/root_ca.crtAnd issued certificates 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:44ZCreate 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 "issuer@example.com" \
--aud "audience@example.com" \
--sub "subject@example.com" \
--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 "issuer@example.com" --aud "audience@example.com"
{
"header": {
"alg": "ES256",
"kid": "X6yaHYNyxr-psAqvSNKCWc9oYDetvGdo2n2PSRZjxss",
"typ": "JWT"
},
"payload": {
"aud": "audience@example.com",
"exp": 1551290879,
"iat": 1551289983,
"iss": "issuer@example.com",
"nbf": 1551289983,
"sub": "subject@example.com"
},
"signature": "JU7fPGqBJcIfauJHA7KP9Wp292g_G9s4bLMVLyRgEQDpL5faaG-3teJ81_igPz1zP7IjHmz8D6Gigt7kbnlasw"
}Login with Google, get an access token, and use it 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": "bob@smallstep.com",
"email_verified": true,
"hd": "smallstep.com"
}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-zzzObtain and verify a Google-issued OAuth OIDC identity token:
$ 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": "name@smallstep.com",
"email_verified": true,
"at_hash": "euBvS34BVu0SJQ-EsbBT3A",
"iat": 1551293134,
"exp": 1551296734
},
"signature": "[...]"
}Generate a TOTP token and a QR code:
$ step crypto otp generate \
--issuer smallstep.com --account name@smallstep.com \
--qr smallstep.png > smallstep.totpScan 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.totpDocumentation can be found in three places:
-
On the command line with
step help xxxwherexxxis the subcommand you are interested in. Ex:step help crypto jwk -
On the web at https://smallstep.com/docs/cli
-
On your browser by running
step help --http :8080and visiting http://localhost:8080
We plan to build more tools that facilitate the use and management of zero trust networks.
- Tell us what you like and don't like about managing identity in your network - we're eager to help solve problems in this space.
- Tell us what features you'd like to see - open issues or hit us on Twitter.
- Check out our blog.
- Eliminate the pain of managing a PKI with
step certificates- an online certificate authority and related tools for secure automated certificate management, so you can use TLS everywhere.