step-agent-helper

A Go library for accessing cryptographic identities managed by the Smallstep Agent. This library enables applications to use hardware-backed certificates and keys for mTLS authentication without directly handling sensitive key material.

Overview

The Smallstep Agent manages cryptographic identities using hardware security features:

• macOS: Secure Enclave via CryptoTokenKit
• Linux/Windows: Trusted Platform Module (TPM)

step-agent-helper provides a simple API to access these identities, making it easy to establish secure mTLS connections from your Go applications.

Installation

go get github.com/smallstep/step-agent-helper

Requirements

• Go 1.24 or later
• Smallstep Agent installed and configured on the system
• Platform-specific requirements:
  • macOS: CryptoTokenKit framework (built-in)
  • Linux/Windows: TPM 2.0 hardware or emulator

Usage

Basic Example

package main

import (
    "context"
    "crypto/tls"
    "net/http"

    stepagenthelper "github.com/smallstep/step-agent-helper"
)

func main() {
    ctx := context.Background()

    // Create a new agent client
    agent, err := stepagenthelper.New(ctx)
    if err != nil {
        panic(err)
    }

    // Get a specific endpoint by name
    endpoint, err := agent.Endpoint(ctx, "MyEndpoint")
    if err != nil {
        panic(err)
    }

    // Get the TLS certificate for mTLS
    tlsCert, err := endpoint.TLSCertificate()
    if err != nil {
        panic(err)
    }

    // Create an HTTP client with mTLS
    client := &http.Client{
        Transport: &http.Transport{
            TLSClientConfig: &tls.Config{
                Certificates: []tls.Certificate{tlsCert},
                MinVersion:   tls.VersionTLS12,
            },
        },
    }

    // Make authenticated requests
    resp, err := client.Get("https://secure-api.example.com")
    // ...
}

Listing All Endpoints

agent, _ := stepagenthelper.New(ctx)

endpoints, err := agent.Endpoints(ctx)
if err != nil {
    panic(err)
}

for _, ep := range endpoints {
    fmt.Printf("Endpoint: %s (ID: %s)\n", ep.Name(), ep.ID())

    // Get certificate details
    subject, _ := ep.Subject()
    dnsNames, _ := ep.DNSNames()
    fmt.Printf("  Subject: %s\n", subject)
    fmt.Printf("  DNS Names: %v\n", dnsNames)
}

Accessing Cryptographic Primitives

endpoint, _ := agent.Endpoint(ctx, "MyEndpoint")

// Get the crypto.Signer for signing operations
signer, err := endpoint.Signer()

// Get the leaf certificate
cert, err := endpoint.Certificate()

// Get the full certificate chain
chain, err := endpoint.CertificateChain()

// Get the public key
pubKey, err := endpoint.PublicKey()

API Reference

Agent

func New(ctx context.Context) (*Agent, error)

Creates a new Agent client that connects to the Smallstep Agent on the system.

func (a *Agent) Endpoints(ctx context.Context) ([]*endpoint, error)

Returns all configured endpoints from the Smallstep Agent.

func (a *Agent) Endpoint(ctx context.Context, name string) (*endpoint, error)

Returns a specific endpoint by name. Returns an error if the endpoint does not exist.

Endpoint

Method	Return Type	Description
ID()	string	Returns the endpoint's unique identifier
Name()	string	Returns the endpoint's name
Signer()	(crypto.Signer, error)	Returns a signer backed by the hardware security module
Certificate()	(*x509.Certificate, error)	Returns the leaf certificate
CertificateChain()	([]*x509.Certificate, error)	Returns the full certificate chain
TLSCertificate()	(tls.Certificate, error)	Returns a TLS certificate ready for use in TLS configurations
PublicKey()	(crypto.PublicKey, error)	Returns the public key
DNSNames()	([]string, error)	Returns DNS SANs from the certificate
IPAddresses()	([]string, error)	Returns IP SANs from the certificate
Subject()	(string, error)	Returns the certificate subject as a string

Configuration

The library automatically discovers the Smallstep Agent configuration. You can override the default paths using environment variables:

Variable	Description
STEP_AGENT_PATH	Override the agent configuration directory (highest priority)
STEPPATH	Override the general Step configuration directory

Agent Binary Locations

The library searches for the Smallstep Agent binary in platform-specific locations:

• Linux: /usr/bin/step-agent-plugin, /usr/local/bin/step-agent-plugin
• macOS: /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent
• Windows: %PROGRAMFILES%\Smallstep\SmallstepApp\smallstep-agent.exe

License

See LICENSE for details.