How to Use the Command 'step' (with Examples)

The ‘step’ command is a versatile and easy-to-use CLI tool designed to facilitate the creation, management, and automation of Public Key Infrastructure (PKI) systems and workflows. PKI is essential for securing network communications through encryption, digital signatures, and authentication, primarily using certificates. This command provides a user-friendly alternative to more complex tools like OpenSSL, simplifying the process of certificate management and cryptographic operations while offering extensive documentation and community support.

Use Case 1: Inspecting the Contents of a Certificate

Code:

step certificate inspect path/to/certificate.crt

Motivation: Understanding the contents of a certificate is crucial for IT administrators and developers who manage secure communications between servers, devices, and applications. Inspecting certificates helps verify their validity, issuer, expiration, and subject information, all of which are necessary to ensure security and trust in digital communications.

Explanation:

• step: The main command line tool being used.
• certificate inspect: Subcommand used to examine the certificate details.
• path/to/certificate.crt: The file path to the certificate that needs to be inspected.

Example Output:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            01:23:45:67:89:ab:cd:ef
    Signature Algorithm: sha256WithRSAEncryption
    Issuer: C=US, O=Example Org, CN=Example Root CA
    Validity:
        Not Before: Oct 10 12:00:00 2023 GMT
        Not After : Oct 10 12:00:00 2024 GMT
    Subject: C=US, O=Example Org, CN=example.com
    ...

Use Case 2: Creating a Root CA Certificate and Key

Code:

step certificate create "Example Root CA" path/to/root-ca.crt path/to/root-ca.key --profile root-ca

Motivation: Creating a Root Certificate Authority (CA) is the foundational step in building a PKI system. A root CA is the top-most authority in a certificate chain and is used to sign the certificates issued for various systems, applications, or services. It is the cornerstone of trust in a network, making the creation of a secure and trusted root CA critical.

Explanation:

• step: Invokes the CLI.
• certificate create: Subcommand for creating new certificates.
• "Example Root CA": The common name (CN) for the root certificate.
• path/to/root-ca.crt: File path where the root certificate will be saved.
• path/to/root-ca.key: File path where the root key will be saved.
• --profile root-ca: Specifies that this certificate is being created as a root CA.

Example Output:

✔ Root CA certificate and key generated successfully.

Use Case 3: Generating and Signing a Certificate for a Specific Hostname

Code:

step certificate create hostname.example.com path/to/hostname.crt path/to/hostname.key --profile leaf --ca path/to/root-ca.crt --ca-key path/to/root-ca.key

Motivation: Certificates are vital for securing communications with specific hosts or services. By generating a certificate specifically for a hostname, and signing it with a trusted root CA, you ensure that the communication to and from the hostname is encrypted and authenticated, preventing various security threats like eavesdropping and data tampering.

Explanation:

• step: Core command-line tool.
• certificate create: Command to generate a new certificate.
• hostname.example.com: The domain for which the certificate is being generated.
• path/to/hostname.crt: Path for saving the generated certificate.
• path/to/hostname.key: Path for saving the generated private key.
• --profile leaf: Specifies the certificate profile as a leaf, typical for end-entities.
• --ca path/to/root-ca.crt: File path for the root CA certificate used for signing.
• --ca-key path/to/root-ca.key: File path for the root CA key.

Example Output:

✔ Certificate and private key for hostname.example.com created successfully.

Use Case 4: Verifying a Certificate Chain

Code:

step certificate verify path/to/hostname.crt --roots path/to/root-ca.crt --verbose

Motivation: Verifying the certificate chain is crucial to ensure that the certificate presented by a server or application is indeed issued by a trusted CA. This process establishes trust in the certificate by validating each step in the chain against known root CAs, thus averting man-in-the-middle attacks and other security vulnerabilities.

Explanation:

• step: The main CLI interface.
• certificate verify: Subcommand for verification of certificates.
• path/to/hostname.crt: Path to the certificate to verify.
• --roots path/to/root-ca.crt: Indicates the root CA certificate file against which the chain is verified.
• --verbose: Provides detailed output during the verification process.

Example Output:

The certificate chain is valid.

Use Case 5: Converting a PEM Format Certificate to DER

Code:

step certificate format path/to/certificate.pem --out path/to/certificate.der

Motivation: Different systems and applications may require certificates in specific formats. PEM (Privacy Enhanced Mail) and DER (Distinguished Encoding Rules) are two such formats commonly used. Converting a certificate from PEM to DER is necessary when dealing with infrastructures or software that do not support PEM format, ensuring compatibility and functional integration between different systems.

Explanation:

• step: The command-line utility.
• certificate format: Subcommand to change the certificate format.
• path/to/certificate.pem: Input certificate file in PEM format.
• --out path/to/certificate.der: Specifies the output path for the converted DER certificate.

Example Output:

Certificate converted and saved to path/to/certificate.der.

Use Case 6: Installing or Uninstalling a Root Certificate in the System’s Default Trust Store

Code:

step certificate install|uninstall path/to/root-ca.crt

Motivation: Managing certificates in the system’s trust store is pivotal for maintaining security across applications running on a system. Installing a root certificate signals the system and its applications to trust certificates signed by this CA, while uninstalling can be necessary when a CA is no longer trusted or required, thus protecting against untrusted certificate usage.

Explanation:

• step: The command being used.
• certificate install|uninstall: Subcommand for adding or removing root certificates from the trust store.
• path/to/root-ca.crt: File path to the root certificate that will be installed or uninstalled.

Example Output:

Certificate path/to/root-ca.crt installed successfully in the system's trust store.

Use Case 7: Creating an RSA/EC Private and Public Keypair

Code:

step crypto keypair path/to/public_key path/to/private_key --kty RSA|EC

Motivation: Generating cryptographic key pairs is a fundamental part of any PKI system. They are used for encrypting data, digitally signing information, and establishing secure connections. Creating these key pairs securely ensures that sensitive operations like authentication and data protection are robust and reliable.

Explanation:

• step: Refers to the command line tool.
• crypto keypair: Subcommand to generate cryptographic key pairs.
• path/to/public_key: Path where the public key will be saved.
• path/to/private_key: Path where the private key will be saved.
• --kty RSA|EC: Defines the type of key, either RSA or Elliptic Curve (EC).

Example Output:

✔ RSA key pair created and saved to specified paths.

Use Case 8: Showing Help for Subcommands

Code:

step path|base64|certificate|completion|context|crl|crypto|oauth|ca|beta|ssh --help

Motivation: The sheer number of options and subcommands available in a CLI tool like ‘step’ can be overwhelming. Accessing help for these subcommands aids users in understanding their functionalities, available options, and usage guidelines. This is essential for efficient and effective interaction with the tool, ensuring users can harness its full capabilities.

Explanation:

• step: The main executable for the command line tool.
• path|base64|certificate|completion|context|crl|crypto|oauth|ca|beta|ssh: Various subcommands for which help can be requested.
• --help: Requests help information display about the specified subcommand.

Example Output:

Usage: step [OPTIONS] subcommand [arguments...]

Some common step cli options are:
  -h, --help, display the help message
  ...

Conclusion:

The ‘step’ command is an indispensable tool for managing PKI systems, providing a streamlined, accessible way to handle certificates and cryptographic operations. By offering an alternative to traditional tools like ‘openssl’, ‘step’ simplifies complex processes, broadening the accessibility of PKI management to a wider range of IT professionals and developers. Each of these use cases illustrates a different aspect of what ‘step’ can accomplish, demonstrating its versatility and power in enhancing security and trust in digital communications.