### Run Basic Client Example

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

This command demonstrates how to run the basic client example. It requires setting the STEP_CA_URL environment variable and passing a CA token as an argument.

```bash
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/basic-client/client.go $(step ca token client.smallstep.com)
```

--------------------------------

### Starting the Step-CA Server in Go

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/README.md

This Go code snippet demonstrates how to initialize and start the Step-CA server using a configuration object. It includes error handling for initialization and server startup.

```go
cfg := &config.Config{}
// ... load configuration

auth, err := authority.New(cfg)
if err != nil {
    log.Fatal(err)
}

ca := &CA{
    auth: auth,
}

// Start HTTPS server
if err := ca.Run(); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Build and Run NGINX with Step CA Docker Example

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

This snippet demonstrates the commands to build Docker images for NGINX, Step CA, and a certificate renewer, then starts them using Docker Compose. It's used to test serving services with certificates managed by Step CA.

```bash
certificates $ cd examples/docker/
docker $ make
```

```bash
GOOS=linux go build -o ca/step-ca github.com/smallstep/certificates/cmd/step-ca
GOOS=linux go build -o renewer/step github.com/smallstep/cli/cmd/step
docker build -t nginx-test:latest nginx
...
docker-compose up
```

--------------------------------

### Step-CA Dockerfile for Container Deployment

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/README.md

This Dockerfile demonstrates how to build a Docker image for Step-CA by installing the step-ca binary using `go install` and setting it as the entrypoint.

```dockerfile
FROM golang:latest
RUN go install github.com/smallstep/certificates/cmd/step-ca@latest
ENTRYPOINT ["step-ca"]
```

--------------------------------

### Start Bootstrap TLS Server

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Starts the bootstrap TLS server and prompts for the provisioner password. Sets STEPPATH and STEP_CA_URL environment variables.

```sh
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-tls-server/server.go $(step ca token localhost)
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
Please enter the password to decrypt the provisioner key:
Listening on :8443 ...
```

--------------------------------

### Start Smallstep CA Server

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Command to start the Smallstep Certificate Authority server. It requires a configuration file.

```sh
certificates $ bin/step-ca examples/pki/config/ca.json
2018/11/02 18:29:25 Serving HTTPS on :9000 ...
```

--------------------------------

### Inspect Certificate Rotation in NGINX Docker Example

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

This command inspects the certificate details served by NGINX in the Docker example. It's used to observe the certificate rotation process, which is set to occur every minute in this test setup.

```bash
docker $ make inspect | head
step certificate inspect https://localhost:4443 --insecure
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 220353801925419530569669982276277771655 (0xa5c6993a7e110e6f009c83c79edc1d87)
    Signature Algorithm: ECDSA-SHA256
        Issuer: CN=Smallstep Intermediate CA
        Validity
            Not Before: Nov 10 02:13:00 2018 UTC
            Not After : Nov 11 02:13:00 2018 UTC
```

```bash
docker $ make inspect | head
step certificate inspect https://localhost:4443 --insecure
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 207756171799719353821615361892302471392 (0x9c4c621c04d3e8be401ff0d14c5440e0)
    Signature Algorithm: ECDSA-SHA256
        Issuer: CN=Smallstep Intermediate CA
        Validity
            Not Before: Nov 10 02:14:00 2018 UTC
            Not After : Nov 11 02:14:00 2018 UTC
```

--------------------------------

### Complete Smallstep CA Configuration Example

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/configuration.md

A comprehensive example of the Smallstep Certificate Authority configuration file. It includes settings for root certificates, intermediate certificates, network addresses, DNS names, logging, database, provisioners, TLS, SSH, CRL, and metrics.

```json
{
  "root": [
    "/var/lib/step-ca/certs/root_ca.crt"
  ],
  "crt": "/var/lib/step-ca/certs/intermediate_ca.crt",
  "key": "/var/lib/step-ca/secrets/intermediate_ca.key",
  "address": ":9000",
  "insecureAddress": ":8080",
  "dnsNames": [
    "ca.example.com",
    "ca.internal"
  ],
  "logger": {
    "format": "json",
    "level": "info"
  },
  "db": {
    "type": "badger",
    "dataSource": "/var/lib/step-ca/db"
  },
  "authority": {
    "provisioners": [
      {
        "type": "jwk",
        "name": "admin@example.com",
        "key": {
          "use": "sig",
          "kty": "RSA",
          "kid": "admin-key",
          "n": "...",
          "e": "AQAB"
        }
      },
      {
        "type": "oidc",
        "name": "google",
        "clientID": "client-id.apps.googleusercontent.com",
        "clientSecret": "client-secret",
        "configurationURI": "https://accounts.google.com/.well-known/openid-configuration"
      }
    ],
    "enableAdmin": true,
    "backdate": "1m",
    "crlCacheDuration": "24h"
  },
  "tls": {
    "cipherSuites": ["TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"],
    "minVersion": "1.2",
    "maxVersion": "1.3"
  },
  "ssh": {
    "hostKey": "/var/lib/step-ca/secrets/ssh_host_ca_key",
    "userKey": "/var/lib/step-ca/secrets/ssh_user_ca_key"
  },
  "crl": {
    "enabled": true,
    "generateOnRevoke": true,
    "cacheDuration": "24h",
    "renewPeriod": "48h",
    "idpURL": "https://ca.example.com/crl"
  },
  "metricsAddress": ":9090"
}
```

--------------------------------

### Cleanup NGINX Docker Example Resources

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

This command stops and removes the containers, networks, and volumes created by the NGINX with Step CA Docker example, ensuring a clean state after testing.

```bash
docker $ make down
docker-compose down
Stopping docker_nginx_1   ... done
Stopping docker_renewer_1 ... done
Stopping docker_ca_1      ... done
Removing docker_nginx_1   ... done
Removing docker_renewer_1 ... done
Removing docker_ca_1      ... done
Removing network docker_default
```

--------------------------------

### Database Configuration Example (PostgreSQL)

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/configuration.md

Configures the PostgreSQL database backend. Requires the type and a connection string for the data source.

```json
{
  "db": {
    "type": "postgresql",
    "dataSource": "postgresql://user:pass@localhost:5432/stepca"
  }
}
```

--------------------------------

### Install PCSC Support on Fedora

Source: https://github.com/smallstep/certificates/blob/master/CONTRIBUTING.md

Installs the PCSC development package on Fedora systems, a prerequisite for building step-ca with CGO.

```shell
sudo yum install pcsc-lite-devel
```

--------------------------------

### Database Configuration Example (MySQL)

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/configuration.md

Configures the MySQL database backend. Requires the type and a connection string for the data source.

```json
{
  "db": {
    "type": "mysql",
    "dataSource": "user:pass@tcp(localhost:3306)/stepca"
  }
}
```

--------------------------------

### Example Git Commit Message

Source: https://github.com/smallstep/certificates/blob/master/CONTRIBUTING.md

An example of a well-formatted Git commit message, including a concise subject, a detailed body, and a reference to a GitHub issue.

```text
Add step certificate install

Add a command line utility for installing (and uninstalling) certificates to the
local system truststores. This should help developers with local development
flows.

Fixes #75
```

--------------------------------

### Start Server for Certificate Rotation Demo

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Launches the bootstrap server with a provisioner configured for a short certificate duration (2 minutes) to demonstrate certificate rotation.

```sh
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-server/server.go $(step ca token localhost)
✔ Key ID: YYNxZ0rq0WsT2MlqLCWvgme3jszkmt99KjoGEJJwAKs (mike@smallstep.com)
Please enter the password to decrypt the provisioner key:
Listening on :8443 ...
```

--------------------------------

### Install PCSC Support on Debian

Source: https://github.com/smallstep/certificates/blob/master/CONTRIBUTING.md

Installs the PCSC development package on Debian-based systems, a prerequisite for building step-ca with CGO.

```shell
sudo apt-get install libpcsclite-dev
```

--------------------------------

### Install PCSC Support on CentOS

Source: https://github.com/smallstep/certificates/blob/master/CONTRIBUTING.md

Installs the PCSC development package on CentOS systems, a prerequisite for building step-ca with CGO.

```shell
sudo yum install 'dnf-command(config-manager)'
sudo yum config-manager --set-enabled PowerTools
sudo yum install pcsc-lite-devel
```

--------------------------------

### Get All Intermediate Certificates

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/authority.md

Retrieves a list of all configured intermediate certificates. Use this to get the chain of trust leading to the root certificates.

```go
func (a *Authority) GetIntermediateCertificates() []*x509.Certificate
```

--------------------------------

### GET /provisioners

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Lists available provisioners with optional pagination. This endpoint does not require any authentication.

```APIDOC
## GET /provisioners

### Description
Lists available provisioners.

### Method
GET

### Endpoint
/provisioners

### Authentication
None

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Default: 20 - Maximum provisioners to return.
- **cursor** (string) - Optional - Pagination cursor.

### Response
#### Success Response (200 OK)
- **provisioners** (array) - An array of provisioner objects.
  - **id** (string) - The unique identifier for the provisioner.
  - **type** (string) - The type of the provisioner (e.g., "jwk").
  - **name** (string) - The name of the provisioner.
  - **key** (object) - The JWK key details for the provisioner.
    - **use** (string) - Key usage (e.g., "sig").
    - **kty** (string) - Key type (e.g., "RSA").
    - **kid** (string) - Key ID.
    - **n** (string) - RSA modulus.
    - **e** (string) - RSA public exponent.
- **nextCursor** (string) - The cursor for the next page of results, if available.

### Response Example
```json
{
  "provisioners": [
    {
      "id": "keyid",
      "type": "jwk",
      "name": "my-provisioner",
      "key": {
        "use": "sig",
        "kty": "RSA",
        "kid": "keyid",
        "n": "...",
        "e": "AQAB"
      }
    }
  ],
  "nextCursor": "cursor-string"
}
```
```

--------------------------------

### POST /ssh/config

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Gets SSH client/server configuration templates. No authentication required.

```APIDOC
## POST /ssh/config

### Description
Gets SSH client/server configuration templates.

### Method
POST

### Endpoint
/ssh/config

### Authentication
None

### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| type | string | "user" for client config, "host" for server config |

### Request Body
```json
{
  "userID": "user",
  "hostID": "hostname"
}
```

### Response
```json
{
  "config": "# SSH configuration",
  "scripts": ["# setup script"]
}
```

### Status Codes
- 200 OK
```

--------------------------------

### Database Configuration Example (BadgerDB)

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/configuration.md

Configures the BadgerDB embedded database backend. Specifies the type and the data source path.

```json
{
  "db": {
    "type": "badger",
    "dataSource": "/var/lib/step-ca/db"
  }
}
```

--------------------------------

### BadgerDB Configuration Example

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/database.md

Configuration for BadgerDB, an embedded key-value store. Suitable for small to medium deployments due to its single-instance nature.

```json
{
  "type": "badger",
  "dataSource": "/var/lib/step-ca/db"
}
```

--------------------------------

### PostgreSQL Configuration Example

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/database.md

Configuration for PostgreSQL, a relational database suitable for production deployments requiring clustering and HA support.

```json
{
  "type": "postgresql",
  "dataSource": "postgresql://user:password@localhost:5432/stepca?sslmode=require"
}
```

--------------------------------

### Not Found (404) - Provisioner Not Found Error Response

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/errors.md

Example response for a not found error when a specified provisioner does not exist or has not been initialized.

```json
{
  "status": 404,
  "message": "not found: provisioner not found"
}
```

--------------------------------

### MySQL Configuration Example

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/database.md

Configuration for MySQL, a relational database recommended for production environments needing robust features like transactions and HA.

```json
{
  "type": "mysql",
  "dataSource": "user:password@tcp(localhost:3306)/stepca?parseTime=true"
}
```

--------------------------------

### Get Provisioners with Pagination

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/authority.md

Retrieves a paginated list of provisioners. Use the cursor and limit parameters to efficiently fetch provisioners, especially in large deployments.

```go
func (a *Authority) GetProvisioners(cursor string, limit int) (provisioner.List, string, error)
```

--------------------------------

### Lego Go Client for ACME Certificate Obtaining

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/acme.md

Example of using the lego Go library to create an ACME client and obtain a certificate.

```go
import "github.com/go-acme/lego/v4/lego"

client, err := lego.NewClient(&lego.Config{
    User: &MyUser{},
    CADirURL: "https://ca.example.com/acme/acme/directory",
})

cert, err := client.Certificate.Obtain(ctx, &certificate.ObtainRequest{
    Domains: []string{"example.com"},
    Bundle: true,
})
```

--------------------------------

### SSH Configuration Response

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Response containing SSH configuration templates and setup scripts.

```json
{
  "config": "# SSH configuration",
  "scripts": ["# setup script"]
}
```

--------------------------------

### BoltDB Configuration Example

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/database.md

Configuration for BoltDB, another embedded key-value store. Similar to BadgerDB in its embedded nature.

```json
{
  "type": "bolt",
  "dataSource": "/var/lib/step-ca/db"
}
```

--------------------------------

### Start mTLS Client

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Runs the mTLS client, which requests a certificate from the Step CA upon startup. It then connects to the mTLS server and displays server responses.

```sh
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-client/client.go $(step ca token Mike)
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
Please enter the password to decrypt the provisioner key:
Server responded: Hello Mike at 2018-11-07 21:54:00.140022 +0000 UTC!!!
Server responded: Hello Mike at 2018-11-07 21:54:01.140827 +0000 UTC!!!
Server responded: Hello Mike at 2018-11-07 21:54:02.141578 +0000 UTC!!!
...
```

--------------------------------

### Launch Kubernetes CA

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Starts an online Certificate Authority using a Kubernetes configuration. Requires a password for the intermediate CA key.

```bash
$ step-ca ./pki/kubernetes/config/ca.federated.json
Please enter the password to decrypt intermediate_ca_key: password
2019/01/22 13:39:44 Serving HTTPS on :2443 ...
```

--------------------------------

### Development Setup for Step-CA

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/README.md

This JSON configuration is suitable for development and testing environments, using self-signed certificates and a local BadgerDB database.

```json
{
  "root": "certs/root_ca.crt",
  "crt": "certs/intermediate.crt",
  "key": "secrets/intermediate.key",
  "address": ":9000",
  "dnsNames": ["localhost"],
  "db": {"type": "badger", "dataSource": "./db"},
  "authority": {
    "provisioners": [
      {"type": "jwk", "name": "dev", "key": {...}}
    ]
  }
}
```

--------------------------------

### Launch CA with Custom Claims Configuration

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Starts a Certificate Authority using a custom configuration file that enables custom certificate validity periods via custom claims.

```sh
certificates $ step-ca examples/pki/config/ca.json
2019/03/11 13:37:03 Serving HTTPS on :9000 ...
```

--------------------------------

### Launch Cloud CA

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Starts an online Certificate Authority using a cloud configuration. Requires a password for the intermediate CA key.

```bash
$ step-ca ./pki/cloud/config/ca.federated.json
Please enter the password to decrypt intermediate_ca_key: password
2019/01/22 13:38:52 Serving HTTPS on :1443 ...
```

--------------------------------

### POST /ssh/bastion

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Gets bastion/jump host configuration. Requires Bearer token authentication and a JSON request body.

```APIDOC
## POST /ssh/bastion

### Description
Gets bastion/jump host configuration.

### Method
POST

### Endpoint
/ssh/bastion

### Authentication
Bearer token

### Request Body
- **user** (string) - The username for the bastion host.
- **hostname** (string) - The target hostname.

### Request Example
```json
{
  "user": "username",
  "hostname": "target.example.com"
}
```

### Response
#### Success Response (200 OK)
- **hostname** (string) - The hostname of the bastion/jump host.
- **user** (string) - The username for the bastion/jump host.

### Response Example
```json
{
  "hostname": "bastion.example.com",
  "user": "bastion-user"
}
```
```

--------------------------------

### Basic Client Usage in Go

Source: https://github.com/smallstep/certificates/blob/master/README.md

Demonstrates how to use the step-ca Go wrapper to create and sign certificates. Ensure you have the necessary imports.

```go
package main

import (
	"crypto/x509"
	"encoding/pem"
	"fmt"
	"io/ioutil"
	"log"
	"os"
	"time"

	"github.com/smallstep/certificates/api"
	"github.com/smallstep/certificates/api/render"
	"github.com/smallstep/certificates/authority"
	"github.com/smallstep/certificates/ca"
	"github.com/smallstep/certificates/crypto"
	"github.com/smallstep/certificates/db"
	"github.com/smallstep/certificates/db/badger"
	"github.com/smallstep/certificates/db/boltdb"
	"github.com/smallstep/certificates/db/mysql"
	"github.com/smallstep/certificates/db/postgres"
	"github.com/smallstep/certificates/kms/softca"
	"github.com/smallstep/certificates/ocsp"
	"github.com/smallstep/certificates/scep"
	"github.com/smallstep/certificates/ssh"
	"github.com/smallstep/certificates/webhook"
)

func main() {
	// Load the CA configuration and database.
	// For this example, we'll use a temporary BadgerDB.
	cfg := ca.DefaultConfig()
	cfg.Root.Name = "Smallstep CA"
	cfg.Root.DNSNames = []string{"localhost"}
	cfg.Root.KeyOps = []string{"sign", "verify"}

	// Initialize the database.
	db, err := badger.New("db.badger")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	// Initialize the KMS.
	kms, err := softca.New(cfg.Root.Key, cfg.Root.Password)
	if err != nil {
		log.Fatal(err)
	}

	// Initialize the Certificate Authority.
	authority, err := authority.New(cfg, db, kms)
	if err != nil {
		log.Fatal(err)
	}

	// Create a new certificate request.
	// This is a simplified example; in a real scenario, you'd generate a CSR.
	// For demonstration, we'll create a self-signed certificate.
	cert, key, err := authority.GenerateSelfSigned(authority.WithProfile("default"))
	if err != nil {
		log.Fatal(err)
	}

	// Print the certificate and key.
	certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: cert.Raw})
	keyPEM, err := crypto.MarshalPrivateKeyToPEM(key)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("---" + "CERTIFICATE" + "---")
	fmt.Println(string(certPEM))
	fmt.Println("---" + "PRIVATE KEY" + "---")
	fmt.Println(string(keyPEM))
}

```

--------------------------------

### ACME Get Nonce Response Headers

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/acme.md

Example response headers for the ACME nonce endpoint, containing the required 'Replay-Nonce'.

```http
Replay-Nonce: xyz123
```

--------------------------------

### Get TLS Options

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/authority.md

Use `GetTLSOptions` to retrieve the TLS configuration options associated with the Authority. This is useful for configuring network listeners or clients.

```go
tlsOpts := a.GetTLSOptions()
// Use tlsOpts for TLS configuration
```

--------------------------------

### Issuing a Certificate using Step-CA CLI and cURL

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/README.md

This example shows how to issue an X.509 certificate by first creating a Certificate Signing Request (CSR), obtaining a token from a provisioner, and then submitting the CSR to the Step-CA API using cURL.

```bash
# Create CSR
openssl req -new -key private.key -out request.csr

# Get token from provisioner
TOKEN=$(step ca token --provisioner=admin user@example.com)

# Submit to CA
curl -X POST https://ca.example.com/sign \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"csr\": \"$(cat request.csr | base64)\",
    \"ott\": \"$TOKEN\"
  }"
```

--------------------------------

### Run Demo Server with SDK

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Launches a demo server using the step certificates SDK. It obtains certificates, renews them, and fetches trusted roots. Requires a password for the provisioner key.

```bash
go run server/main.go $(step ca token \
  --ca-url https://localhost:1443 \
  --root ./pki/cloud/certs/root_ca.crt \
  127.0.0.1)
✔ Key ID: EE1ZiqkMaxsUdpz8SCSkRBzwK9TWUoidQnMnJ8Eryn8 (sebastian@smallstep.com)
✔ Please enter the password to decrypt the provisioner key: password
Server is using federated root certificates
Accepting certs anchored in CN=Smallstep Public Cloud Root CA
Accepting certs anchored in CN=Smallstep Kubernetes Root CA
Listening on :8443 ...
```

--------------------------------

### Start mTLS Server

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Launches the mTLS server, requiring a provisioner password. It uses a Step CA token for authentication and listens on port 8443.

```sh
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-mtls-server/server.go $(step ca token localhost)
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
Please enter the password to decrypt the provisioner key:
Listening on :8443 ...
```

--------------------------------

### Init Method

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/provisioner.md

Initializes a provisioner instance with the provided configuration. This method must be called before the provisioner can be used for authorization.

```go
func (p Interface) Init(config Config) error
```

--------------------------------

### Run Demo Client with SDK

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Executes a demo client using the step certificates SDK for mutual authentication. It handles certificate bootstrapping, renewal, and fetching trusted roots. Requires a password for the provisioner key.

```bash
$ go run client/main.go $(step ca token sdk_client \
  --ca-url https://localhost:2443 \
  --root ./pki/kubernetes/certs/root_ca.crt)
✔ Key ID: S5gYgpeqcIAgc1Zr4myZXpgJ_Ao4ryS6F6wqg9o8RYo (sebastian@smallstep.com)
✔ Please enter the password to decrypt the provisioner key: password
Server responded: Hello sdk_client (cert issued by 'Smallstep Kubernetes Root CA') at 2019-01-23 00:51:38.576648 +0000 UTC
```

--------------------------------

### Get SSH Configuration Template

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/api.md

Returns SSH client or server configuration templates. No authentication is required. Can specify 'user' or 'host' type via URL parameter.

```go
func SSHConfig(w http.ResponseWriter, r *http.Request)
```

```json
{
  "userID": "username",
  "hostID": "hostname"
}
```

--------------------------------

### Create and Initialize CA Server

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/ca.md

Use the `New` function to create a CA server instance with a configuration and optional settings. The server should be closed when no longer needed.

```go
cfg := loadConfigFromFile("ca.json")
ca, err := ca.New(cfg, 
    ca.WithConfigFile("ca.json"),
    ca.WithPassword([]byte("password")),
)
if err != nil {
    log.Fatal(err)
}
defer ca.Close()
if err := ca.Run(); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Initialize Authority with Configuration

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/authority.md

Use `authority.New` to create and initialize a new Authority instance with a given configuration and optional settings. Ensure the configuration includes paths to root and intermediate certificates and keys, along with network address and DNS names.

```go
cfg := &config.Config{
    Root: "path/to/root_ca.crt",
    IntermediateCert: "path/to/intermediate.crt",
    IntermediateKey: "path/to/intermediate.key",
    Address: ":9000",
    DNSNames: []string{"ca.example.com"},
}
auth, err := authority.New(cfg)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Testing API Handlers with httptest

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/api.md

Example of how to test API handlers using Go's built-in httptest package. It creates a new request, a response recorder, calls the handler, and checks the status code.

```go
req := httptest.NewRequest("GET", "/version", nil)
w := httptest.NewRecorder()
Version(w, req)

if w.Code != http.StatusOK {
    t.Fatalf("expected 200, got %d", w.Code)
}
```

--------------------------------

### Get All Root Certificates

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/authority.md

Retrieves a list of all configured root certificates. This is useful for obtaining a complete set of trusted root CAs.

```go
func (a *Authority) GetRoots() ([]*x509.Certificate, error)
```

--------------------------------

### Create Database Connection

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/database.md

Establishes a connection to the database using the provided configuration. Ensure the configuration type and data source are correctly set.

```go
cfg := &db.Config{
    Type:       "badger",
    DataSource: "/var/lib/step-ca/db",
}

database, err := db.New(cfg)
if err != nil {
    log.Fatal(err)
}
defer database.Close()
```

--------------------------------

### Init

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/provisioner.md

Initializes the provisioner with the provided configuration. This method must be called before using the provisioner.

```APIDOC
## Init

### Description
Initializes the provisioner with configuration.

### Method
Interface Method

### Parameters
#### Request Body
- **config** (Config) - Required - Provisioner configuration

### Returns
- **error**: Nil on success, or an error if initialization fails
```

--------------------------------

### Initialize CA Client with Bootstrap Token

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Initializes a CA client by bootstrapping with a provisioning token. This is a simpler method if the token contains the necessary CA information.

```go
client, err := ca.Bootstrap(token)
```

--------------------------------

### Get and Verify Root Certificate

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Downloads the root certificate from the CA and verifies its fingerprint. An insecure HTTP client may be used for this initial step, but the response is secured by fingerprint comparison.

```go
root, err := client.Root("84a033e84196f73bd593fad7a63e509e57fd982f02084359c4e8c5c864efc27d")
```

--------------------------------

### Get Bastion/Jump Host Configuration

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Fetches the configuration for a bastion or jump host. Requires Bearer token authentication and a JSON request body specifying the target user and hostname.

```json
{
  "user": "username",
  "hostname": "target.example.com"
}
```

```json
{
  "hostname": "bastion.example.com",
  "user": "bastion-user"
}
```

--------------------------------

### Build Standard step-ca

Source: https://github.com/smallstep/certificates/blob/master/CONTRIBUTING.md

Builds the standard step-ca binary from source. Requires Go and make.

```shell
make bootstrap && make
```

--------------------------------

### GET /federation

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns federated root certificates. This endpoint does not require any authentication.

```APIDOC
## GET /federation

### Description
Returns federated root certificates.

### Method
GET

### Endpoint
/federation

### Authentication
None

### Response
#### Success Response (200 OK)
- Response body is an array of root certificate PEM strings.

### Response Example
(Array of root certificate PEM strings)
```

--------------------------------

### Rate Limiting Response

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Example of an HTTP response when rate limits are exceeded.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

--------------------------------

### GET /ssh/hosts

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Lists SSH hosts that can be accessed. Requires Bearer token authentication.

```APIDOC
## GET /ssh/hosts

### Description
Lists SSH hosts that can be accessed.

### Method
GET

### Endpoint
/ssh/hosts

### Authentication
Bearer token

### Response
#### Success Response (200 OK)
- **hosts** (array) - A list of SSH hosts.
  - **name** (string) - The name of the host.
  - **principals** (array) - A list of principals for the host.
  - **user** (string) - The user to connect as.
  - **port** (string) - The port to connect to.

### Response Example
```json
{
  "hosts": [
    {
      "name": "web1",
      "principals": ["web1.example.com"],
      "user": "admin",
      "port": "22"
    }
  ]
}
```
```

--------------------------------

### List Provisioners with Pagination

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/api.md

Lists configured provisioners with support for pagination using limit and cursor query parameters. No authentication is required.

```bash
curl "https://ca.example.com/provisioners?limit=10&cursor=xyz"
```

--------------------------------

### GET /ssh/federation

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns federated SSH CA public keys. No authentication required.

```APIDOC
## GET /ssh/federation

### Description
Returns federated SSH CA public keys.

### Method
GET

### Endpoint
/ssh/federation

### Authentication
None

### Response
Same as /ssh/roots

### Status Codes
- 200 OK
```

--------------------------------

### Fetch Provisioners with Options

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Retrieves a list of provisioners from the CA. Supports filtering by limit, pagination cursor, or a combination of both.

```go
// Without options it will return the first 20 provisioners.
provisioners, err := client.Provisioners()
// We can also set a limit up to 100.
provisioners, err := client.Provisioners(ca.WithProvisionerLimit(100))
// With a pagination cursor.
provisioners, err := client.Provisioners(ca.WithProvisionerCursor("1f18c1ecffe54770e9107ce7b39b39735"))
// Or combine both.
provisioners, err := client.Provisioners(
    ca.WithProvisionerCursor("1f18c1ecffe54770e9107ce7b39b39735"),
    ca.WithProvisionerLimit(100),
)
```

--------------------------------

### GET /crl

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns the Certificate Revocation List (CRL). This endpoint does not require any authentication.

```APIDOC
## GET /crl

### Description
Returns the Certificate Revocation List.

### Method
GET

### Endpoint
/crl

### Authentication
None

### Response
#### Success Response (200 OK)
- Response body is a DER-encoded CRL (application/pkix-crl).

### Response Example
(DER-encoded CRL)
```

--------------------------------

### Make Signed Certificate Request with cURL

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/errors.md

Example using cURL to send a POST request for signing a certificate. It includes client certificate authentication and specifies the request body.

```bash
curl -X POST https://ca.example.com/sign \
  --cert client.crt \
  --key client.key \
  -H "Content-Type: application/json" \
  -d @request.json
  
# Check response status
# 201 = success
# 4xx = client error (see message field)
# 5xx = server error
```

--------------------------------

### Get Order

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/acme.md

Retrieves the current status and details of a previously created certificate order.

```APIDOC
## POST /.well-known/acme-config/order/{id}

### Description
Retrieves the current status and details of a previously created certificate order.

### Method
POST

### Endpoint
/.well-known/acme-config/order/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order.

#### Request Body
- `{}` (empty object)

### Response
#### Success Response (200 OK)
Returns the same structure as the Create Order response, detailing the current status, authorizations, and finalize URL.

### Response Example
```json
{
  "status": "pending",
  "expires": "2024-01-08T12:00:00Z",
  "identifiers": [
    {
      "type": "dns",
      "value": "example.com"
    }
  ],
  "authorizations": [
    "https://ca.example.com/.well-known/acme-config/authz/xyz"
  ],
  "finalize": "https://ca.example.com/.well-known/acme-config/finalize/xyz"
}
```
```

--------------------------------

### Run Bootstrap Client with Client Certificate

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Runs the bootstrap client, generating a client certificate with the Common Name 'Mike' and connecting to the bootstrap server. Sets STEPPATH and STEP_CA_URL environment variables.

```sh
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-client/client.go $(step ca token Mike)
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
Please enter the password to decrypt the provisioner key:
Server responded: Hello Mike at 2018-11-03 01:52:52.678215 +0000 UTC!!!
Server responded: Hello Mike at 2018-11-03 01:52:53.681563 +0000 UTC!!!
Server responded: Hello Mike at 2018-11-03 01:52:54.682787 +0000 UTC!!!
...
```

--------------------------------

### GET /intermediates.pem

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns intermediate certificates in PEM format. This endpoint does not require any authentication.

```APIDOC
## GET /intermediates.pem

### Description
Returns intermediate certificates in PEM format.

### Method
GET

### Endpoint
/intermediates.pem

### Authentication
None

### Response
#### Success Response (200 OK)
- Response body contains plain text concatenated PEM certificates.

### Response Example
(Plain text concatenated PEM certificates)
```

--------------------------------

### GET /intermediates

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns intermediate certificates in JSON format. This endpoint does not require any authentication.

```APIDOC
## GET /intermediates

### Description
Returns intermediate certificates in JSON format.

### Method
GET

### Endpoint
/intermediates

### Authentication
None

### Response
#### Success Response (200 OK)
- **certificates** (array of strings) - An array of intermediate certificates in PEM format.

### Response Example
```json
{
  "certificates": [
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  ]
}
```
```

--------------------------------

### GET /roots.pem

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns all root certificates in PEM format. This endpoint does not require any authentication.

```APIDOC
## GET /roots.pem

### Description
Returns all root certificates in PEM format.

### Method
GET

### Endpoint
/roots.pem

### Authentication
None

### Response
#### Success Response (200 OK)
- Response body contains plain text concatenated PEM certificates.

### Response Example
(Plain text concatenated PEM certificates)
```

--------------------------------

### Bootstrap TLS Server (Optional Client Certificate)

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Creates an http.Server that optionally requires a client certificate. It uses ca.VerifyClientCertIfGiven() to only verify if a certificate is provided. Ensure a cancelable context is used.

```go
ctx, cancel := context.WithCancel(context.Background())
defers cancel()
// Create an http.Server that does not require a client certificate
srv, err := ca.BootstrapServerWithMTLS(ctx, token, &http.Server{
    Addr: ":8443",
    Handler: handler,
}, ca.VerifyClientCertIfGiven())
if err != nil {
    panic(err)
}
srv.ListenAndServeTLS("", "")
```

--------------------------------

### GET /roots

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns all root certificates in JSON format. This endpoint does not require any authentication.

```APIDOC
## GET /roots

### Description
Returns all root certificates in JSON format.

### Method
GET

### Endpoint
/roots

### Authentication
None

### Response
#### Success Response (200 OK)
- **certificates** (array of strings) - An array of root certificates in PEM format.

### Response Example
```json
{
  "certificates": [
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  ]
}
```
```

--------------------------------

### Get Nonce

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/acme.md

Obtains a unique nonce from the ACME server, which is required for all subsequent POST requests.

```APIDOC
## GET /.well-known/acme-config/new-nonce

### Description
Obtains a unique nonce from the ACME server, which is required for all subsequent POST requests.

### Method
GET

### Endpoint
/.well-known/acme-config/new-nonce

### Response
#### Success Response (200)
- **Replay-Nonce** (string) - The nonce value provided in the response header.

### Response Headers
```
Replay-Nonce: xyz123
```
```

--------------------------------

### GET /root/{sha}

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns a root certificate by its SHA-256 fingerprint. This endpoint does not require any authentication.

```APIDOC
## GET /root/{sha}

### Description
Returns a root certificate by its SHA-256 fingerprint.

### Method
GET

### Endpoint
/root/{sha}

### Authentication
None

### Parameters
#### Path Parameters
- **sha** (string) - Required - SHA-256 fingerprint (hex-encoded).

### Response
#### Success Response (200 OK)
- **ca** (string) - The root certificate in PEM format.

#### Error Response (404 Not Found)
Indicates the certificate with the specified SHA was not found.

### Response Example
```json
{
  "ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}
```
```

--------------------------------

### GET /health

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Health check endpoint for load balancers and monitoring. This endpoint does not require any authentication.

```APIDOC
## GET /health

### Description
Health check endpoint for load balancers and monitoring.

### Method
GET

### Endpoint
/health

### Authentication
None

### Response
#### Success Response (200 OK)
- **status** (string) - Indicates the health status, typically "ok".

#### Error Response (503 Service Unavailable)
- **status** (string) - Indicates the health status, typically "unhealthy".

### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### GET /ssh/roots

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns SSH CA public keys for user and host verification. No authentication required.

```APIDOC
## GET /ssh/roots

### Description
Returns SSH CA public keys for user and host verification.

### Method
GET

### Endpoint
/ssh/roots

### Authentication
None

### Response
```json
{
  "userPublicKeys": [
    "ssh-rsa AAAAB3NzaC1yc2E..."
  ],
  "hostPublicKeys": [
    "ssh-rsa AAAAB3NzaC1yc2E..."
  ],
  "federatedUserPublicKeys": [],
  "federatedHostPublicKeys": []
}
```

### Status Codes
- 200 OK
```

--------------------------------

### GET /provisioners/{kid}/encrypted-key

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns an encrypted key for a JWK provisioner. This endpoint does not require any authentication.

```APIDOC
## GET /provisioners/{kid}/encrypted-key

### Description
Returns an encrypted key for a JWK provisioner.

### Method
GET

### Endpoint
/provisioners/{kid}/encrypted-key

### Authentication
None

### Parameters
#### Path Parameters
- **kid** (string) - Required - Provisioner key ID.

### Response
#### Success Response (200 OK)
- Response body is an encrypted key string.

#### Error Response (404 Not Found)
Indicates the provisioner with the specified key ID was not found.

### Response Example
(Encrypted key string)
```

--------------------------------

### Generate Client Certificate with step CLI

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Generates a client certificate and key using the step CLI for use with the Kubernetes CA. Requires a password for the provisioner key.

```bash
$ step ca certificate kube_client kube_client.crt kube_client.key \
  --ca-url https://localhost:2443 \
  --root pki/kubernetes/certs/root_ca.crt
✔ Key ID: S5gYgpeqcIAgc1Zr4myZXpgJ_Ao4ryS6F6wqg9o8RYo (sebastian@smallstep.com)
✔ Please enter the password to decrypt the provisioner key:
✔ CA: https://localhost:2443/1.0/sign
✔ Certificate: kube_client.crt
✔ Private Key: kube_client.key
```

--------------------------------

### Bootstrap TLS Server (Requires Client Certificate)

Source: https://github.com/smallstep/certificates/blob/master/examples/README.md

Creates an http.Server that requires a client certificate for authentication. Ensure a cancelable context is used to manage goroutines and timers.

```go
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// Create an http.Server that requires a client certificate
srv, err := ca.BootstrapServer(ctx, token, &http.Server{
    Addr: ":8443",
    Handler: handler,
})
if err != nil {
    panic(err)
}
srv.ListenAndServeTLS("", "")
```

--------------------------------

### Get Authorization

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/acme.md

Retrieves the details of an authorization, including the challenges that must be completed to prove domain control.

```APIDOC
## POST /.well-known/acme-config/authz/{id}

### Description
Retrieves the details of an authorization, including the challenges that must be completed to prove domain control.

### Method
POST

### Endpoint
/.well-known/acme-config/authz/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the authorization.

#### Request Body
- `{}` (empty object)

### Response
#### Success Response (200 OK)
- **identifier** (object) - The identifier (e.g., domain name) for which authorization is sought.
  - **type** (string) - Type of identifier (e.g., "dns").
  - **value** (string) - The identifier value.
- **status** (string) - The current status of the authorization (e.g., "pending").
- **expires** (string) - The expiration date and time of the authorization.
- **challenges** (array of objects) - A list of challenges to prove domain control.
  - **type** (string) - The type of challenge (e.g., "http-01", "dns-01").
  - **status** (string) - The status of the challenge (e.g., "pending").
  - **url** (string) - The URL to use when responding to the challenge.
  - **token** (string) - The token required for the challenge response.

### Response Example
```json
{
  "identifier": {
    "type": "dns",
    "value": "example.com"
  },
  "status": "pending",
  "expires": "2024-01-08T12:00:00Z",
  "challenges": [
    {
      "type": "http-01",
      "status": "pending",
      "url": "https://ca.example.com/.well-known/acme-config/challenge/xyz",
      "token": "challenge-token"
    },
    {
      "type": "dns-01",
      "status": "pending",
      "url": "https://ca.example.com/.well-known/acme-config/challenge/abc",
      "token": "challenge-token"
    }
  ]
}
```
```

--------------------------------

### GET /version

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Returns the CA version and whether client authentication is required. This endpoint does not require any authentication.

```APIDOC
## GET /version

### Description
Returns the CA version and whether client authentication is required.

### Method
GET

### Endpoint
/version

### Authentication
None

### Response
#### Success Response (200 OK)
- **version** (string) - The current version of the CA.
- **requireClientAuthentication** (boolean) - Indicates if client authentication is required for other endpoints.

### Response Example
```json
{
  "version": "0.24.4",
  "requireClientAuthentication": false
}
```
```

--------------------------------

### ACME Get Order Endpoint

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/acme.md

Retrieves the current status of an existing ACME order using its ID.

```HTTP
POST /.well-known/acme-config/order/{id}
```

--------------------------------

### Get Intermediate Certificates (JSON)

Source: https://github.com/smallstep/certificates/blob/master/_autodocs/endpoints.md

Retrieves intermediate certificates in JSON format. This endpoint is publicly accessible.

```json
{
  "certificates": [
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  ]
}
```