DOCSEARCHbyAlgolia
Submit Docs

Step CLI

repository·master·Indexed 26 days ago

https://github.com/smallstep/cli

A versatile tool for managing Public Key Infrastructure (PKI), X.509 and SSH certificates, and cryptographic operations. It serves as a standalone crypto toolkit and a client for the step-ca certificate authority server, providing capabilities for certificate lifecycle management, JOSE (JWT, JWS, JWE), OAuth 2.0 flows, and ACMEv2 compliant CA administration.

Tokens
40.1K
Snippets
97
Records
271
Agent score
87%

What's inside smallstep-cli

  1. Overview of Step CLI

    master
    step is a CLI tool designed for building, operating, and automating Public Key Infrastructure (PKI) systems and workflows. It serves as a client for the step-ca online Certificate Authority (CA) server and provides a wide range of cryptographic and X.509 operations, which can be used independently or in conjunction with an online CA.

  3. Set up local development environment for Step CLI

    master

    To develop on the Step CLI, ensure you have the following prerequisites met:

    1. Golang: Install Go locally. The project supports the latest two versions of Go. Check go.mod for the current minimum version.
    2. make: A version of make must be available to use the Makefile.
    3. GOPATH setup: The repository must be checked out within your $GOPATH. For example, if $GOPATH is ~/go, check out the repository at ~/go/src/github.com/smallstep/cli.

  4. Extend Step CLI with Plugins

    master

    You can extend the step CLI by adding executable files following the naming convention step-<name>-plugin.

    Plugin Discovery: Plugins must be located in your $PATH or in the $STEPPATH/plugins directory (which defaults to $HOME/.step/plugins). When you run step <name>, the CLI automatically executes the corresponding plugin.

    Example Plugins:

    • step-kms-plugin: Manages keys and certificates in a KMS (HSMs, TPMs, YubiKeys, macOS Keychain, cloud KMSs). It is integrated into step for creating certificates, generating CSRs, and signing tokens using KMS-backed keys.
    • step-kmsproxy-plugin: Provides an HSM/KMS-backed authenticating proxy for mTLS services.

  6. Generate shell completion scripts using `step completion <shell>`

    master

    The completion scripts previously located in the autocomplete/ directory are deprecated. To generate shell completion scripts for your environment, use the step completion command followed by your shell name (e.g., bash, zsh, fish).

    step completion <shell>

  7. Add a new command to the Step CLI

    master

    To add a new command, you must define it using the urfave/cli package and register it with the github.com/smallstep/cli/command package. This allows the command to be available in the cmd/step/main.go entrypoint.

    1. Define and Register: Create a new package for your command. In the init() function, define a cli.Command struct and call command.Register().
    2. Import for Registration: For top-level commands, you must add a blank import of your command package in cmd/step/main.go to ensure the init() function executes.
    package validate

import (
  "github.com/urfave/cli"

  "github.com/smallstep/cli/command"
  "github.com/smallstep/cli/flags"
)

func init() {
  cmd := cli.Command{
    Name: "validate",
    Usage: "Returns whether or not the provided token is valid",
    Flags: []cli.Flag{
      flags.Token("The one-time token value to validate"),
    },
    Action: validate,
  }

  command.Register(validate)
}

    In cmd/step/main.go:

    package main

import (
  "github.com/urfave/cli"
  _ "github.com/smallstep/cli/validate"
)

  8. Manage Go dependencies

    master

    Adding a dependency

    Import the package into your code and run go get <pkg>. This updates go.mod and go.sum. You can specify a specific version by manually adding it to the go.mod file.

    Removing a dependency

    Remove the package from your codebase and any references in go.mod, then run go mod tidy to clean up go.sum.

  11. Bootstrap development dependencies

    master
    After cloning the repository to the correct $GOPATH location, run the make bootstrap command. This command installs necessary dependencies, including the correct version of golangci-lint. This typically only needs to be run once.
    make bootstrap

  12. Manage a Certificate Authority with 'step ca'

    master

    The step ca command group provides facilities to initialize a certificate authority, retrieve the root of trust, sign and renew certificates, and create and manage provisioners.

    Common Subcommands

    • init: Initialize a new certificate authority.
    • bootstrap: Configure the ca-url and root in the environment.
    • root: Download the root certificate.
    • health: Check the health status of the CA.
    • token: Generate a token for certificate issuance.
    • certificate: Create a new certificate.
    • renew: Renew an existing certificate.
    • revoke: Revoke a certificate.
    • provisioner: Manage provisioners.
    • policy: Manage CA policies.
    • admin: Perform administrative tasks.
    • acme: Manage ACME-related configurations.
    # Example: Initialize a new CA
step ca init

# Example: Bootstrap the environment with a CA URL and fingerprint
step ca bootstrap \
  --ca-url https://ca.smallstep.com \
  --fingerprint 0d7d3834cf187726cf331c40a31aa7ef6b29ba4df601416c9788f6ee01058cf3

# Example: Download the root certificate
step ca root root_ca.crt \
  --ca-url https://ca.smallstep.com \
  --fingerprint 0d7d3834cf187726cf331c40a31aa7ef6b29ba4df601416c9788f6ee01058cf3

# Example: Check CA health
step ca health --ca-url https://ca.smallstep.com --root /home/user/.step/certs/root_ca.crt

# Example: Create a certificate using a token
TOKEN=$(step ca token internal.example.com)
step ca certificate internal.example.com internal.crt internal.key \
  --token $TOKEN --ca-url https://ca.smallstep.com --root root_ca.crt

# Example: Renew a certificate
step ca renew internal.crt internal.key \
  --ca-url https://ca.smallstep.com --root root_ca.crt