Step CA

https://smallstep.com/docs/step-ca/
Admin
Step CA is an online Certificate Authority (CA) for secure, automated X.509 and SSH certificate...
Tokens:121,193
Snippets:845
Trust Score:9.4
Update:4 days ago
Show doc for...
Tokens:
Raw
### step-ca startup output

Source: https://smallstep.com/docs/step-ca/cryptographic-protection

Example output when step-ca starts, showing the server URL and root fingerprint.

```text
2022/09/20 16:28:45 The primary server URL is https://localhost:443
2022/09/20 16:28:45 Root certificates are available at https://localhost:443/roots.pem
2022/09/20 16:28:45 X.509 Root Fingerprint: b061dfca1013c074244b0f376e5be70b6eb0bd7f21d5438aa3af71fe62b0acf5
2022/09/20 16:28:45 Serving HTTPS on :443 ...
```

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

### step-ca startup output with fingerprints and SSH keys

Source: https://smallstep.com/docs/step-ca/cryptographic-protection

Example output when starting step-ca, showing the X.509 root fingerprint and SSH host and user CA keys.

```text
2022/09/20 16:28:45 The primary server URL is https://localhost:443
2022/09/20 16:28:45 Root certificates are available at https://localhost:443/roots.pem
2022/09/20 16:28:45 X.509 Root Fingerprint: b061dfca1013c074244b0f376e5be70b6eb0bd7f21d5438aa3af71fe62b0acf5
2022/09/20 16:28:45 SSH Host CA Key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBIwmL7aDOJId/9UOVJGhVux6Rlvea+q2017aLsfze+/EwGQ5BdZ4k2Qh+5VekebBKZYLNO0LkSf9bZb4o9GSxIs=
2022/09/20 16:28:45 SSH User CA Key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFE0VY9eLxkoHrXoWk5VxeOQTUt53U5xIo89pfsgYHh450cdE4c3mYw5YeOueESyu/lFUHfJoNS6twVR1wuCOdc=
2022/09/20 16:28:45 Serving HTTPS on :443 ...
```

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

### Start step-ca

Source: https://smallstep.com/docs/step-ca/webhooks

Starts the step-ca server using the specified context.

```bash
step-ca --context webhooks
```

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

### Enable and start step-ca

Source: https://smallstep.com/docs/step-ca/certificate-authority-server-production

Configures the step-ca service to start automatically on boot and starts it immediately.

```bash
sudo systemctl enable --now step-ca
```

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

### Initialize PKI and start step-ca

Source: https://smallstep.com/docs/step-ca/renewal

Initializes a new PKI environment and starts the step-ca server using a password file for authentication.

```bash
$ echo "p4ssword" > password.txt
$ step ca init --name "Speedy" --provisioner admin \
               --dns localhost --address ":443" \
               --password-file password.txt \
               --provisioner-password-file password.txt
$ step-ca $(step path)/config/ca.json --password-file password.txt
```

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

### Install step-ca on Debian/Ubuntu

Source: https://smallstep.com/docs/step-ca/installation

Add the Smallstep repository and install the step-cli and step-ca packages as root.

```bash
apt-get update && apt-get install -y --no-install-recommends curl gpg ca-certificates
curl -fsSL https://packages.smallstep.com/keys/apt/repo-signing-key.gpg -o /etc/apt/keyrings/smallstep.asc
cat << EOF > /etc/apt/sources.list.d/smallstep.sources
Types: deb
URIs: https://packages.smallstep.com/stable/debian
Suites: debs
Components: main
Signed-By: /etc/apt/keyrings/smallstep.asc
EOF
apt-get update && apt-get -y install step-cli step-ca
```

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

### Install step-ca on RHEL/Fedora

Source: https://smallstep.com/docs/step-ca/installation

Configure the Smallstep repository and install the step-cli and step-ca packages using dnf as root.

```bash
cat <<EOT > /etc/yum.repos.d/smallstep.repo
[smallstep]
name=Smallstep
baseurl=https://packages.smallstep.com/stable/fedora/
enabled=1
repo_gpgcheck=0
gpgcheck=1
gpgkey=https://packages.smallstep.com/keys/smallstep-0x889B19391F774443.gpg
EOT
dnf makecache && dnf install -y step-cli step-ca
```

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

### Example step-ca configuration (ca.json)

Source: https://smallstep.com/docs/step-ca/configuration

A complete example configuration file for step-ca, showing root, intermediate, SSH, database, authority, provisioners, and TLS settings.

```json
{
  "root": "examples/pki/secrets/root_ca.crt",
  "federatedRoots": ["examples/pki/secrets/federated_root_ca.crt"],
  "crt": "examples/pki/secrets/intermediate_ca.crt",
  "key": "examples/pki/secrets/intermediate_ca_key",
  "address": ":9000",
  "dnsNames": [
    "localhost"
  ],
  "logger": {
    "format": "text"
  },
  "ssh": {
    "hostKey": "/examples/pki/secrets/secrets.host.key",
    "userKey": "/examples/pki/secrets/secrets.user.key"
  },
  "db": {
    "type": "badgerv2",
    "dataSource": "/Users/carl/.step/authorities/config-example/db"
  }, 
  "crl": {
    "enabled": false
  }, 
  "authority": {
    "disableIssuedAtCheck": false,
    "claims": {
      "minTLSCertDuration": "5m",
      "maxTLSCertDuration": "24h",
      "defaultTLSCertDuration": "24h",
      "disableRenewal": false,
      "allowRenewalAfterExpiry": false,
      "minHostSSHCertDuration": "5m",
      "maxHostSSHCertDuration": "1680h",
      "defaultHostSSHCertDuration": "720h",
      "minUserSSHCertDuration": "5m",
      "maxUserSSHCertDuration": "24h",
      "defaultUserSSHCertDuration": "16h"
    },
    "policy": {
      "x509": {
        "allow": {
          "dns": ["*.local"]
        },
        "allowWildcardNames": false
      },
      "ssh": {
        "user": {
          "allow": {
            "email": ["@local"]
          }
        },
        "host": {
          "allow": {
            "dns": ["*.local"]
          }
        }
      }
    },
    "provisioners": [
      {
        "type": "jwk",
        "name": "mike@smallstep.com",
        "key": {
          "use": "sig",
          "kty": "EC",
          "kid": "YYNxZ0rq0WsT2MlqLCWvgme3jszkmt99KjoGEJJwAKs",
          "crv": "P-256",
          "alg": "ES256",
          "x": "LsI8nHBflc-mrCbRqhl8d3hSl5sYuSM1AbXBmRfznyg",
          "y": "F99LoOvi7z-ZkumsgoHIhodP8q9brXe4bhF3szK-c_w"
        },
        "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjEwMDAwMCwicDJzIjoiVERQS2dzcEItTUR4ZDJxTGo0VlpwdyJ9.2_j0cZgTm2eFkZ-hrtr1hBIvLxN0w3TZhbX0Jrrq7vBMaywhgFcGTA.mCasZCbZJ-JT7vjA.bW052WDKSf_ueEXq1dyxLq0n3qXWRO-LXr7OzBLdUKWKSBGQrzqS5KJWqdUCPoMIHTqpwYvm-iD6uFlcxKBYxnsAG_hoq_V3icvvwNQQSd_q7Thxr2_KtPIDJWNuX1t5qXp11hkgb-8d5HO93CmN7xNDG89pzSUepT6RYXOZ483mP5fre9qzkfnrjx3oPROCnf3SnIVUvqk7fwfXuniNsg3NrNqncHYUQNReiq3e9I1R60w0ZQTvIReY7-zfiq7iPgVqmu5I7XGgFK4iBv0L7UOEora65b4hRWeLxg5t7OCfUqrS9yxAk8FdjFb9sEfjopWViPRepB0dYPH8dVI.fb6-7XWqp0j6CR9Li0NI-Q",
        "claims": {
          "minTLSCertDuration": "1m0s",
          "defaultTLSCertDuration": "2m0s"
        },
        "options": {
          "x509": {
            "templateFile": "templates/certs/x509/default.tpl"
          },
          "ssh": {
            "templateFile": "templates/certs/ssh/default.tpl"
          }
        }
      },
      {
        "type": "OIDC",
        "name": "Google",
        "clientID": "1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com",
        "clientSecret": "udTrOT3gzrO7W9fDPgZQLfYJ",
        "configurationEndpoint": "https://accounts.google.com/.well-known/openid-configuration",
        "admins": ["you@smallstep.com"],
        "domains": ["smallstep.com"],
        "listenAddress": ":10000",
        "claims": {
          "maxTLSCertDuration": "8h",
          "defaultTLSCertDuration": "2h",
          "enableSSHCA": true,
          "disableRenewal": true
        },
        "options": {
          "x509": {
            "templateFile": "templates/certs/x509/default.tpl"
          },
          "ssh": {
            "templateFile": "templates/certs/ssh/default.tpl"
          }
        }
      },
      {
        "type": "SSHPOP",
        "name": "sshpop-smallstep",
        "claims": {
          "enableSSHCA": true
        }
      },
      {
        "type": "ACME",
        "name": "my-acme-provisioner"
      }
    ]
  },
  "tls": {
    "cipherSuites": [
      "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
      "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
    ],
    "minVersion": 1.2,
    "maxVersion": 1.3,
    "renegotiation": false
  },
  "password": "p@55w0rd"
}
```

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

### Install step CLI on Linux

Source: https://smallstep.com/docs/step-ca/installation

Download and install the step CLI binary from the latest release tarball for amd64 architecture.

```bash
curl -LO https://dl.smallstep.com/cli/docs-ca-install/latest/step_linux_amd64.tar.gz
tar -xf step_linux_amd64.tar.gz
sudo cp step_linux_amd64/bin/step /usr/bin
```

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

### Test step and step-ca installation

Source: https://smallstep.com/docs/step-ca/installation

Verify the installation by checking the version of the step CLI and step-ca binaries.

```bash
$ step version
Smallstep CLI/0.10.0 (darwin/amd64)
Release Date: 2019-04-30 19:01 UTC

$ step-ca version
Smallstep CA/0.10.0 (darwin/amd64)
Release Date: 2019-04-30 19:02 UTC
```

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

### Install step-ca on Wolfi

Source: https://smallstep.com/docs/step-ca/installation

Install the step-ca package using the apk package manager.

```bash
apk add step-ca
```

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

### Run webhook server

Source: https://smallstep.com/docs/step-ca/webhooks

Starts the webhook server using Go.

```bash
go run main.go
```

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

### Install step-certificates via Helm

Source: https://smallstep.com/docs/step-ca/installation

Add the smallstep Helm repository and install the step-certificates chart on Kubernetes.

```bash
helm repo add smallstep https://smallstep.github.io/helm-charts/
helm repo update
helm install step-certificates smallstep/step-certificates
```

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

### Install step-ca on Windows via Winget

Source: https://smallstep.com/docs/step-ca/installation

Install the Smallstep.step-ca package using the Windows Package Manager. You may need to restart your terminal after installation.

```powershell
winget install Smallstep.step-ca
```

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

### Install step-ca binary on Linux

Source: https://smallstep.com/docs/step-ca/installation

Download and install the step-ca binary from the latest release tarball for amd64 architecture.

```bash
curl -L https://dl.smallstep.com/certificates/docs-ca-install/latest/step-ca_linux_amd64.tar.gz
tar -xf step-ca_linux_amd64.tar.gz
sudo cp step-ca_linux_amd64/step-ca /usr/bin
```

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

### Clone example webhook repository

Source: https://smallstep.com/docs/step-ca/webhooks

Clones the official smallstep webhook example repository.

```bash
git clone https://github.com/smallstep/webhooks.git
cd webhooks
```

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

### X5C Provisioner Configuration Example

Source: https://smallstep.com/docs/step-ca/provisioners

Example configuration for an X5C provisioner, showing required fields (type, name, roots) and optional fields (claims, options). The type must be 'X5C' and roots are base64-encoded PEM blocks.

```json
{
  "type": "X5C",
  "name": "x5c",
  "roots": ["base64-encoded-root-cert"]
}
```

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

### Install step-ca on Alpine Linux

Source: https://smallstep.com/docs/step-ca/installation

Install the step-cli and step-certificates packages using the apk package manager.

```bash
apk add step-cli step-certificates
```

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

### Install step-ca on Windows via Scoop

Source: https://smallstep.com/docs/step-ca/installation

Install step-ca and the step CLI using the Scoop package manager.

```powershell
scoop bucket add smallstep https://github.com/smallstep/scoop-bucket.git
scoop install smallstep/step
scoop install smallstep/step-ca
```

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

### Install step-ca on Arch Linux

Source: https://smallstep.com/docs/step-ca/installation

Install the step-cli and step-ca packages using the pacman package manager.

```bash
pacman -S step-cli step-ca
```

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

### Start step-ca and view root fingerprint

Source: https://smallstep.com/docs/step-ca/registration-authority-ra-mode

Start step-ca with the ca.json configuration. It will automatically download the root certificate from Google CAS and print the root fingerprint upon startup.

```bash
$ step-ca /home/jane/.step/config/ca.json
2020/09/22 13:17:15 Using root fingerprint '3ef16343cf0952eedbe2b843066bb798fa7a7bceb16aa285e8b0399f661b28b7'
2020/09/22 13:17:15 Serving HTTPS on :9000 ...
```

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

### asn1Set function example

Source: https://smallstep.com/docs/step-ca/templates

Shows how to create an ASN.1 SET of values.

```text
asn1Set (asn1Enc "foo") (asn1Enc "int:123") ...

```

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

### Initialize Certificate Authority with step ca init

Source: https://smallstep.com/docs/step-ca/getting-started

Run this command to configure your CA. You will be prompted for PKI name, DNS/IP addresses, listening address, provisioner name, and a password.

```bash
$ step ca init

✔ What would you like to name your new PKI? (e.g. Smallstep): Example Inc.
✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,1.1.1.1,etc.]): localhost
✔ What address will your new CA listen at? (e.g. :443): 127.0.0.1:8443
✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): bob@example.com
✔ What do you want your password to be? [leave empty and we will generate one]: abc123

Generating root certificate...
all done!

Generating intermediate certificate...
all done!

✔ Root certificate: /Users/bob/.step/certs/root_ca.crt
✔ Root private key: /Users/bob/.step/secrets/root_ca_key
✔ Root fingerprint: 702a094e239c9eec6f0dcd0a5f65e595bf7ed6614012825c5fe3d1ae1b2fd6ee
✔ Intermediate certificate: /Users/bob/.step/certs/intermediate_ca.crt
✔ Intermediate private key: /Users/bob/.step/secrets/intermediate_ca_key
✔ Default configuration: /Users/bob/.step/config/defaults.json
✔ Certificate Authority configuration: /Users/bob/.step/config/ca.json

Your PKI is ready to go.
```

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

### asn1Marshal function examples

Source: https://smallstep.com/docs/step-ca/templates

Examples of asn1Marshal with and without a data type parameter.

```text
asn1Marshal .Token.iss
asn1Marshal .AuthorizationCrt.NotAfter "utc"

```

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

### Start step-ca RA server

Source: https://smallstep.com/docs/step-ca/registration-authority-ra-mode

Starts the step-ca server in RA mode using the configuration file. The output shows the server starting with the vault-test context and serving HTTPS on port 4443.

```bash
$ step-ca $(step path)/config/ca.json
badger 2022/04/25 16:12:14 INFO: All 1 tables opened in 1ms
badger 2022/04/25 16:12:14 INFO: Replaying file id: 0 at offset: 9073
badger 2022/04/25 16:12:14 INFO: Replay took: 129.694µs
2022/04/25 16:12:14 Starting Smallstep CA/0.21.0 (linux/amd64)
2022/04/25 16:12:14 Documentation: https://u.step.sm/docs/ca
2022/04/25 16:12:14 Community Discord: https://u.step.sm/discord
2022/04/25 16:12:14 Current context: vault-test
2022/04/25 16:12:14 Config file: /home/awesome/.step/config/ca.json
2022/04/25 16:12:14 The primary server URL is https://localhost:4443
2022/04/25 16:12:14 Root certificates are available at https://localhost:4443/roots.pem
2022/04/25 16:12:14 X.509 Root Fingerprint: 2a0d4fe2b633301f02161bb667cf3d75939e32fee64642d73b16f76b7cdd1ea3
2022/04/25 16:12:14 Serving HTTPS on :4443 ...
```

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

### Enabling and Starting the step Service

Source: https://smallstep.com/docs/step-ca/renewal

Command to enable and start the step renewal service.

```bash
sudo systemctl enable --now step
```

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

### Run step-ca with a configuration file

Source: https://smallstep.com/docs/step-ca/configuration

Use this command to start step-ca with the configuration file created by 'step ca init'. The path is obtained via 'step path'.

```shell
$ step-ca $(step path)/config/ca.json
```

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

### asn1Enc function examples

Source: https://smallstep.com/docs/step-ca/templates

Examples of asn1Enc with different data type prefixes and a variable.

```text
asn1Enc "int:123"
asn1Enc "oid:1.2.3.4"
asn1Enc "foo"
asn1Enc .Subject.CommonName

```

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

### Create Systemd Unit File

Source: https://smallstep.com/docs/step-ca/certificate-authority-server-production

Initialize the systemd service file for step-ca.

```bash
$ sudo touch /etc/systemd/system/step-ca.service
```

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

### SCEP provisioner JSON configuration

Source: https://smallstep.com/docs/step-ca/provisioners

Example SCEP provisioner configuration in $(step path)/config/ca.json. Includes forceCN, challenge, minimumPublicKeyLength, includeRoot, and encryptionAlgorithmIdentifier.

```json
{
    "type": "SCEP",
    "name": "my_scep_provisioner",
    "forceCN": true,
    "challenge": "secret1234",
    "minimumPublicKeyLength": 2048,
    "includeRoot": true,
    "encryptionAlgorithmIdentifier": 2,
}
```

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

### Configure provisioner template

Source: https://smallstep.com/docs/step-ca/webhooks

Creates a template file and updates the provisioner to incorporate webhook data.

```bash
cat <<EOF > external_ou.tpl
{
  "subject": {
    "organizationalUnit": {{ toJson .Webhooks.people.role }}
  }
}
EOF
step ca provisioner update my_provisioner --x509-template external_ou.tpl
```

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

### SCEP provisioner configuration options

Source: https://smallstep.com/docs/step-ca/provisioners

Lists SCEP provisioner options including forceCN, challenge, minimumPublicKeyLength, includeRoot, excludeIntermediate, encryptionAlgorithmIdentifier, decrypterCertificate, decrypterKeyPEM, decrypterKeyURI, and decrypterKeyPassword. Defaults and behaviors are noted.

```markdown
  * **forceCN** *: force one of the SANs to become the Common Name, if a common name is not provided in the CSR. Defaults to false.
  * **challenge** *: is the secret shared between the provisioner and SCEP clients. By default no secret is used. Ignored when a `SCEPCHALLENGE` webhook is configured.
  * **minimumPublicKeyLength** *: the minimum length of RSA public keys submitted by a client. Defaults to 2048.
  * **includeRoot** *: the root CA certificate will be returned in responses to `GetCACert` requests in addition to the intermediate CA certificate. This option was added to support a specific use case for the macOS SCEP client (see certificates#746 for more details). Defaults to false.
  * **excludeIntermediate** *: excludes the intermediate CA certificate from being returned in responses to `GetCACert` requests. Defaults to false.
  * **encryptionAlgorithmIdentifier** *: sets the encryption algorithm used for encrypting the request content. Defaults to 0: `DES-CBC` for legacy compatibility.
  * **decrypterCertificate** *: a base64 PEM encoded RSA public key certificate to which clients can encrypt requests. When not provided, the CA certificate is used for this purpose.
  * **decrypterKeyPEM** *: a base64 PEM encoded RSA private key, corresponding to the `decrypterCertificate`. Used to decrypt requests from clients. Ignored if `decrypterKeyURI` is provided.
  * **decrypterKeyURI** *: a KMS URI for an RSA private key, corresponding to the `decrypterCertificate`. Used to decrypt requests from clients. Takes precedence over `decrypterKeyPEM`.
  * **decrypterKeyPassword** *: password for the RSA private key.
```

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

### Install step-ca on macOS via Homebrew

Source: https://smallstep.com/docs/step-ca/installation

Use Homebrew to install both the step CLI and step-ca binary on macOS.

```bash
brew install step
```

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

### Run Go server

Source: https://smallstep.com/docs/step-ca/getting-started

Execute the Go server as a background process.

```bash
$ go run srv.go &
```

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

### Issue a certificate with specific start and end times

Source: https://smallstep.com/docs/step-ca/basic-certificate-authority-operations

Issues a certificate valid starting 5 minutes from now until 10 days from now.

```bash
$ step ca certificate localhost localhost.crt localhost.key --not-before=5m --not-after=240h
```

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

### Run the Certificate Authority server

Source: https://smallstep.com/docs/step-ca/getting-started

Start the CA server by passing the path to the generated ca.json configuration file. You will be prompted for the intermediate key password.

```bash
$ step-ca $(step path)/config/ca.json

Please enter the password to decrypt /Users/bob/.step/secrets/intermediate_ca_key: abc123

2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8443 ...
```

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

### Bootstrap step client and issue test certificate

Source: https://smallstep.com/docs/step-ca/registration-authority-ra-mode

Bootstraps the step client with the RA's CA URL and fingerprint, then issues a test certificate for example.com. The output shows the saved root certificate and the issued certificate details.

```bash
$ step ca bootstrap --ca-url https://localhost:4443 \
	 --fingerprint 2a0d4fe2b633301f02161bb667cf3d75939e32fee64642d73b16f76b7cdd1ea3
The root certificate has been saved in /home/awesome/.step/certs/root_ca.crt.
The authority configuration has been saved in /home/awesome/.step/config/defaults.json.

$ step ca certificate example.com example.crt example.key
✔ Provisioner: carl@smallstep.com (JWK) [kid: oRxlIgpwI00GZUPZDMF-cASlh-sbmbdHS0pQOpNXszU]
Please enter the password to decrypt the provisioner key:
✔ CA: https://localhost:4443
✔ Certificate: example.crt
✔ Private Key: example.key
```

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

### Install root CA certificate

Source: https://smallstep.com/docs/step-ca/getting-started

Install the root CA certificate into the system's default trust store to enable system-wide trust.

```bash
$ step certificate install $(step path)/certs/root_ca.crt
Certificate /home/alice/.step/certs/root_ca.crt has been installed.
X.509v3 Root CA Certificate (ECDSA P-256) [Serial: 2282...6360]
  Subject:     Example Inc. Root CA
  Issuer:      Example Inc. Root CA
  Valid from:  2021-05-11T21:40:19Z
          to:  2031-05-09T21:40:19Z
```

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

### asn1Marshal usage examples

Source: https://smallstep.com/docs/step-ca/templates/index.html

Examples of asn1Marshal encoding Go values into ASN.1, with optional data type parameter. Imitates Go's asn1.MarshalWithParams.

```text
asn1Marshal .Token.iss
asn1Marshal .AuthorizationCrt.NotAfter "utc"
```
Tokens:
Raw