cli

module
v0.11.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 13, 2019 License: Apache-2.0

README

Step CLI

step is a zero trust swiss army knife. 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

GitHub release CA Image Go Report Card Build Status License CLA assistant

GitHub stars Twitter followers

Animated terminal showing step in practice

Installation Guide

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.

Mac OS

Install step via Homebrew:


$ brew install step

Note: If you have installed step previously through the smallstep/smallstep tap you will need to run the following commands before installing:


$ brew untap smallstep/smallstep
$ brew uninstall step
Linux
Debian

Download and install the latest Debian package from releases:


$ wget https://github.com/smallstep/cli/releases/download/X.Y.Z/step_X.Y.Z_amd64.deb

# Install the Debian package:
$ sudo dpkg -i step_X.Y.Z_amd64.deb
Arch Linux

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.

Test

$ 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
[...]

Examples

X.509 Certificates

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

You can install your root certificate locally:

$ step certificate install root-ca.crt

And issued certificates will work in your browser and with tools like curl. See our blog post for more info.

Browser demo of HTTPS working without warnings

Alternatively, for internal service-to-service communication, you can configure your code and infrastructure to trust your root certificate.

If you need certificates for your microservices, containers, or other internal services see step certificates, a sub-project that adds an online certificate authority and automated certificate management tools to step.

JSON Object Signing & Encryption (JOSE)

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 "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"
}
Single Sign-On

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-zzz

Obtain 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": "[...]"
}
Multi-factor Authentication

Generate a TOTP token and a QR code:


$ step crypto otp generate \
    --issuer smallstep.com --account name@smallstep.com \
    --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

Documentation

Documentation can be found in three places:

  1. On the command line with step help xxx where xxx is the subcommand you are interested in. Ex: step help crypto jwk

  2. On the web at https://smallstep.com/docs/cli

  3. On your browser by running step help --http :8080 and visiting http://localhost:8080

The Future

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.

Further Reading

  • 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.

Directories

Path Synopsis
cmd
ca
crypto
kdf
pki
pkg
blackfriday
Package blackfriday is a markdown processor.
Package blackfriday is a markdown processor.
x509
Package x509 parses X.509-encoded keys and certificates.
Package x509 parses X.509-encoded keys and certificates.
x509/pkix
Package pkix contains shared, low level structures used for ASN.1 parsing and serialization of X.509 certificates, CRL and OCSP.
Package pkix contains shared, low level structures used for ASN.1 parsing and serialization of X.509 certificates, CRL and OCSP.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL