cli

Step CLI

step is an easy-to-use CLI tool for building, operating, and automating Public Key Infrastructure (PKI) systems and workflows. It's also a client for the step-ca online Certificate Authority (CA) server. 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 (that's $HOME/.step/plugins, by default).

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

Some known plugins include:

• step-kms-plugin: 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-plugin 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.