Step CLI

step is an easy-to-use CLI tool for building, operating, and automating Public Key Infrastructure (PKI) systems and workflows. It's the client counterpart to the step-ca online Certificate Authority (CA). You can use it for many common crypto and X.509 operations—either independently, or with an online CA.

Questions? Ask us on GitHub Discussions or Discord.

Website | Documentation | Installation | Basic Crypto Operations | Contributor's Guide

Features

Step CLI's command groups illustrate its wide-ranging 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 browser's) trust store.
  • Validate certificate deployment and renewal status for automation
  • 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: Administer and use a step-ca server, or any ACMEv2 (RFC8555) compliant CA server. 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
  • With an ACME CA, step supports the http-01 challenge type

• 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, and argo2
  • Generate and check file hashes

• 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 offline step-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

Installation

See our installation docs here.

Example

Here's a quick example, combining step oauth and step crypto to get and verify the signature of a Google OAuth OIDC token:

Plugins

A plugin is an executable file named using the format step-<name>-plugin. Plugins must be available in your $PATH or in the $STEPPATH/plugins directory.

When you run step <name>, the CLI will automatically execute the corresponding plugin if it exists.

Some known plugins include:

• step-kms-proxy: Manage keys and certificates stored in a KMS, including HSMs, TPMs, YubiKeys, the macOS Keychain, and cloud KMSs.
• step-kmsproxy-plugin: Provides an HSM/KMS-backed authenticating proxy for mTLS services. Thanks to @andsens for creating and maintaining this plugin!

[step-kms-proxy] is also integrated directly into step to create certificates, generate CSRs, sign tokens, and more using KMS-backed keys.

Community

• Connect with step users on GitHub Discussions or Discord
• Open an issue and tell us what features you'd like to see
• Contribute to the step codebase
• Follow Smallstep on Twitter

Further Reading

• Full documentation for step
• We have more examples of step and step-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.