Skip to content

Commit 9df8af8

Browse files
step-cistep-ci
committed
step-cli v0.30.0 reference update
1 parent 95a9492 commit 9df8af8

11 files changed

Lines changed: 511 additions & 250 deletions

File tree

‎manifest.json‎

Lines changed: 234 additions & 234 deletions
Large diffs are not rendered by default.

‎step-cli/reference/README.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,9 @@ print the version
6565

6666
## Version
6767

68-
Smallstep CLI/0.29.0 (linux/amd64)
68+
Smallstep CLI/0.30.0 (linux/amd64)
6969

7070
## Copyright
7171

72-
(c) 2018-2025 Smallstep Labs, Inc.
72+
(c) 2018-2026 Smallstep Labs, Inc.
7373

‎step-cli/reference/ca/certificate/README.mdx‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,35 @@ The path to the `file` containing the password to encrypt or decrypt the private
152152
Complete the flow while remaining inside the terminal.
153153

154154
**--kms**=`uri`
155-
The `uri` to configure a Cloud KMS or an HSM.
155+
The `uri` to configure a (cloud) KMS or an HSM.
156+
`uri` is formatted as **kmstype:[key=value;...]?[key=value&...]**. The **;**-separated
157+
parameters identify the KMS, and **&**-separated parameters contain credentials and additional configuration for those credentials.
158+
159+
Supported KMS types:
160+
161+
- **YubiKey PIV**: Use **yubikey:** URIs. Parameters: **serial**, **pin-value**, **pin-source**, **management-key**, **management-key-source**.
162+
163+
- **PKCS #11**: Use **pkcs11:** URIs. Parameters: **module-path**, **token**, **id**, **object**, **pin-value**, **pin-source**.
164+
165+
- **TPM 2.0**: Use **tpmkms:** URIs. Parameters: **name**, **device**, **attestation-ca-url**.
166+
167+
- **Google Cloud KMS**: Use **cloudkms:** URIs. Parameters: **credentials-file**.
168+
169+
- **AWS KMS**: Use **awskms:** URIs. Parameters: **region**, **profile**, **credentials-file**.
170+
171+
- **Azure Key Vault**: Use **azurekms:** URIs. Parameters: **tenant-id**, **client-id**, **client-secret**, **client-certificate-file**.
172+
173+
Examples:
174+
175+
```shell
176+
yubikey:pin-value=123456
177+
pkcs11:module-path=/usr/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=pass
178+
tpmkms:name=my-key;device=/dev/tpmrm0
179+
awskms:region=us-east-1
180+
azurekms:client-id=fooo;client-secret=bar;tenant-id=9de53416-4431-4181-7a8b-23af3EXAMPLE
181+
```
182+
183+
For more information, see https://smallstep.com/docs/step-ca/cryptographic-protection/.
156184

157185
**--x5c-cert**=`chain`
158186
Certificate (`chain`) in PEM format to store in the 'x5c' header of a JWT.
@@ -263,6 +291,13 @@ Request a new certificate with an X5C provisioner:
263291
$ step ca certificate foo.internal foo.crt foo.key --x5c-cert x5c.cert --x5c-key x5c.key
264292
```
265293

294+
Request a new certificate with an X5C provisioner using a certificate and private key stored on a YubiKey:
295+
```shell
296+
$ step ca certificate joe@example.com joe.crt joe.key \
297+
--x5c-cert yubikey:slot-id=9a \
298+
--x5c-key 'yubikey:slot-id=9a?pin=value=123456'
299+
```
300+
266301
**Certificate Templates** - With a provisioner configured with a custom
267302
template we can use the **--set** flag to pass user variables:
268303
```shell

‎step-cli/reference/ca/rekey/README.mdx‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,35 @@ each with optional fraction and a unit suffix, such as "300ms", "1.5h", or "2h45
107107
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
108108

109109
**--kms**=`uri`
110-
The `uri` to configure a Cloud KMS or an HSM.
110+
The `uri` to configure a (cloud) KMS or an HSM.
111+
`uri` is formatted as **kmstype:[key=value;...]?[key=value&...]**. The **;**-separated
112+
parameters identify the KMS, and **&**-separated parameters contain credentials and additional configuration for those credentials.
113+
114+
Supported KMS types:
115+
116+
- **YubiKey PIV**: Use **yubikey:** URIs. Parameters: **serial**, **pin-value**, **pin-source**, **management-key**, **management-key-source**.
117+
118+
- **PKCS #11**: Use **pkcs11:** URIs. Parameters: **module-path**, **token**, **id**, **object**, **pin-value**, **pin-source**.
119+
120+
- **TPM 2.0**: Use **tpmkms:** URIs. Parameters: **name**, **device**, **attestation-ca-url**.
121+
122+
- **Google Cloud KMS**: Use **cloudkms:** URIs. Parameters: **credentials-file**.
123+
124+
- **AWS KMS**: Use **awskms:** URIs. Parameters: **region**, **profile**, **credentials-file**.
125+
126+
- **Azure Key Vault**: Use **azurekms:** URIs. Parameters: **tenant-id**, **client-id**, **client-secret**, **client-certificate-file**.
127+
128+
Examples:
129+
130+
```shell
131+
yubikey:pin-value=123456
132+
pkcs11:module-path=/usr/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=pass
133+
tpmkms:name=my-key;device=/dev/tpmrm0
134+
awskms:region=us-east-1
135+
azurekms:client-id=fooo;client-secret=bar;tenant-id=9de53416-4431-4181-7a8b-23af3EXAMPLE
136+
```
137+
138+
For more information, see https://smallstep.com/docs/step-ca/cryptographic-protection/.
111139

112140
**--kty**=`kty`
113141
The `kty` to build the certificate upon.
@@ -179,12 +207,22 @@ Rekey a certificate forcing the overwrite of the previous certificate and key
179207
$ step ca rekey --force internal.crt internal.key
180208
```
181209

182-
Rekey a certificate which key is in a KMS, with another from the same KMS:
210+
Rekey a certificate using a KMS, with another from the same KMS:
211+
```shell
212+
$ step ca rekey --private-key 'yubikey:slot-id=9a?pin-value=123456' \
213+
yubikey.crt 'yubikey:slot-id=82?pin-value=123456'
214+
```
215+
216+
Rekey a certificate using a KMS with the `--kms` flag:
183217
```shell
184218
$ step ca rekey \
185219
--kms 'pkcs11:module-path=/usr/local/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=password' \
186-
--private-key 'pkcs11:id=4002'
187-
pkcs11.crt 'pkcs11:id=4001'
220+
--private-key 'pkcs11:id=4002' pkcs11.crt 'pkcs11:id=4001'
221+
```
222+
223+
```shell
224+
$ step ca rekey --key yubikey:pin-value=123456 --private-key yubikey:slot-id=9a \
225+
yubikey.crt 'yubikey:slot-id=82
188226
```
189227
190228
Rekey a certificate providing the `--ca-url` and `--root` flags:

‎step-cli/reference/ca/renew/README.mdx‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,35 @@ but can accept a different configuration file using **--ca-config** flag.
7777
The path to the `file` containing the password to encrypt or decrypt the private key.
7878

7979
**--kms**=`uri`
80-
The `uri` to configure a Cloud KMS or an HSM.
80+
The `uri` to configure a (cloud) KMS or an HSM.
81+
`uri` is formatted as **kmstype:[key=value;...]?[key=value&...]**. The **;**-separated
82+
parameters identify the KMS, and **&**-separated parameters contain credentials and additional configuration for those credentials.
83+
84+
Supported KMS types:
85+
86+
- **YubiKey PIV**: Use **yubikey:** URIs. Parameters: **serial**, **pin-value**, **pin-source**, **management-key**, **management-key-source**.
87+
88+
- **PKCS #11**: Use **pkcs11:** URIs. Parameters: **module-path**, **token**, **id**, **object**, **pin-value**, **pin-source**.
89+
90+
- **TPM 2.0**: Use **tpmkms:** URIs. Parameters: **name**, **device**, **attestation-ca-url**.
91+
92+
- **Google Cloud KMS**: Use **cloudkms:** URIs. Parameters: **credentials-file**.
93+
94+
- **AWS KMS**: Use **awskms:** URIs. Parameters: **region**, **profile**, **credentials-file**.
95+
96+
- **Azure Key Vault**: Use **azurekms:** URIs. Parameters: **tenant-id**, **client-id**, **client-secret**, **client-certificate-file**.
97+
98+
Examples:
99+
100+
```shell
101+
yubikey:pin-value=123456
102+
pkcs11:module-path=/usr/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=pass
103+
tpmkms:name=my-key;device=/dev/tpmrm0
104+
awskms:region=us-east-1
105+
azurekms:client-id=fooo;client-secret=bar;tenant-id=9de53416-4431-4181-7a8b-23af3EXAMPLE
106+
```
107+
108+
For more information, see https://smallstep.com/docs/step-ca/cryptographic-protection/.
81109

82110
**--out**=`file`, **--output-file**=`file`
83111
The new certificate `file` path. Defaults to overwriting the `crt-file` positional argument
@@ -154,6 +182,11 @@ $ step ca renew --mtls=false --force internal.crt internal.key
154182

155183
Renew a certificate which key is in a KMS:
156184
```shell
185+
$ step ca renew yubikey.crt 'yubikey:slot-id=9a?pin-value=123456'
186+
```
187+
188+
Renew a certificate which key is in a KMS, using the `--kms` flag:
189+
```shell
157190
$ step ca renew \
158191
--kms 'pkcs11:module-path=/usr/local/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=password' \
159192
pkcs11.crt 'pkcs11:id=4001'

‎step-cli/reference/ca/sign/README.mdx‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,35 @@ The path to the `file` containing the password to encrypt or decrypt the private
8585
Complete the flow while remaining inside the terminal.
8686

8787
**--kms**=`uri`
88-
The `uri` to configure a Cloud KMS or an HSM.
88+
The `uri` to configure a (cloud) KMS or an HSM.
89+
`uri` is formatted as **kmstype:[key=value;...]?[key=value&...]**. The **;**-separated
90+
parameters identify the KMS, and **&**-separated parameters contain credentials and additional configuration for those credentials.
91+
92+
Supported KMS types:
93+
94+
- **YubiKey PIV**: Use **yubikey:** URIs. Parameters: **serial**, **pin-value**, **pin-source**, **management-key**, **management-key-source**.
95+
96+
- **PKCS #11**: Use **pkcs11:** URIs. Parameters: **module-path**, **token**, **id**, **object**, **pin-value**, **pin-source**.
97+
98+
- **TPM 2.0**: Use **tpmkms:** URIs. Parameters: **name**, **device**, **attestation-ca-url**.
99+
100+
- **Google Cloud KMS**: Use **cloudkms:** URIs. Parameters: **credentials-file**.
101+
102+
- **AWS KMS**: Use **awskms:** URIs. Parameters: **region**, **profile**, **credentials-file**.
103+
104+
- **Azure Key Vault**: Use **azurekms:** URIs. Parameters: **tenant-id**, **client-id**, **client-secret**, **client-certificate-file**.
105+
106+
Examples:
107+
108+
```shell
109+
yubikey:pin-value=123456
110+
pkcs11:module-path=/usr/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=pass
111+
tpmkms:name=my-key;device=/dev/tpmrm0
112+
awskms:region=us-east-1
113+
azurekms:client-id=fooo;client-secret=bar;tenant-id=9de53416-4431-4181-7a8b-23af3EXAMPLE
114+
```
115+
116+
For more information, see https://smallstep.com/docs/step-ca/cryptographic-protection/.
89117

90118
**--x5c-cert**=`chain`
91119
Certificate (`chain`) in PEM format to store in the 'x5c' header of a JWT.

‎step-cli/reference/ca/token/README.mdx‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,35 @@ The path to the `file` containing the password to decrypt the one-time token
107107
generating key.
108108

109109
**--kms**=`uri`
110-
The `uri` to configure a Cloud KMS or an HSM.
110+
The `uri` to configure a (cloud) KMS or an HSM.
111+
`uri` is formatted as **kmstype:[key=value;...]?[key=value&...]**. The **;**-separated
112+
parameters identify the KMS, and **&**-separated parameters contain credentials and additional configuration for those credentials.
113+
114+
Supported KMS types:
115+
116+
- **YubiKey PIV**: Use **yubikey:** URIs. Parameters: **serial**, **pin-value**, **pin-source**, **management-key**, **management-key-source**.
117+
118+
- **PKCS #11**: Use **pkcs11:** URIs. Parameters: **module-path**, **token**, **id**, **object**, **pin-value**, **pin-source**.
119+
120+
- **TPM 2.0**: Use **tpmkms:** URIs. Parameters: **name**, **device**, **attestation-ca-url**.
121+
122+
- **Google Cloud KMS**: Use **cloudkms:** URIs. Parameters: **credentials-file**.
123+
124+
- **AWS KMS**: Use **awskms:** URIs. Parameters: **region**, **profile**, **credentials-file**.
125+
126+
- **Azure Key Vault**: Use **azurekms:** URIs. Parameters: **tenant-id**, **client-id**, **client-secret**, **client-certificate-file**.
127+
128+
Examples:
129+
130+
```shell
131+
yubikey:pin-value=123456
132+
pkcs11:module-path=/usr/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=pass
133+
tpmkms:name=my-key;device=/dev/tpmrm0
134+
awskms:region=us-east-1
135+
azurekms:client-id=fooo;client-secret=bar;tenant-id=9de53416-4431-4181-7a8b-23af3EXAMPLE
136+
```
137+
138+
For more information, see https://smallstep.com/docs/step-ca/cryptographic-protection/.
111139

112140
**--x5c-cert**=`chain`
113141
Certificate (`chain`) in PEM format to store in the 'x5c' header of a JWT.
@@ -309,8 +337,9 @@ Generate an X5C provisioner token using a certificate in a YubiKey. Note that a
309337
YubiKey does not support storing a certificate bundle. To make it work, you must
310338
add the intermediate and the root in the provisioner configuration:
311339
```shell
312-
$ step ca token --kms yubikey:pin-value=123456 \
313-
--x5c-cert yubikey:slot-id=82 --x5c-key yubikey:slot-id=82 \
340+
$ step ca token \
341+
--x5c-cert yubikey:slot-id=82 \
342+
--x5c-key 'yubikey:slot-id=82?pin=value=123456' \
314343
internal.example.com
315344
```
316345

‎step-cli/reference/certificate/create/README.mdx‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,35 @@ The path to the `file` containing the password to
140140
decrypt the CA private key.
141141

142142
**--kms**=`uri`
143-
The `uri` to configure a Cloud KMS or an HSM.
143+
The `uri` to configure a (cloud) KMS or an HSM.
144+
`uri` is formatted as **kmstype:[key=value;...]?[key=value&...]**. The **;**-separated
145+
parameters identify the KMS, and **&**-separated parameters contain credentials and additional configuration for those credentials.
146+
147+
Supported KMS types:
148+
149+
- **YubiKey PIV**: Use **yubikey:** URIs. Parameters: **serial**, **pin-value**, **pin-source**, **management-key**, **management-key-source**.
150+
151+
- **PKCS #11**: Use **pkcs11:** URIs. Parameters: **module-path**, **token**, **id**, **object**, **pin-value**, **pin-source**.
152+
153+
- **TPM 2.0**: Use **tpmkms:** URIs. Parameters: **name**, **device**, **attestation-ca-url**.
154+
155+
- **Google Cloud KMS**: Use **cloudkms:** URIs. Parameters: **credentials-file**.
156+
157+
- **AWS KMS**: Use **awskms:** URIs. Parameters: **region**, **profile**, **credentials-file**.
158+
159+
- **Azure Key Vault**: Use **azurekms:** URIs. Parameters: **tenant-id**, **client-id**, **client-secret**, **client-certificate-file**.
160+
161+
Examples:
162+
163+
```shell
164+
yubikey:pin-value=123456
165+
pkcs11:module-path=/usr/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=pass
166+
tpmkms:name=my-key;device=/dev/tpmrm0
167+
awskms:region=us-east-1
168+
azurekms:client-id=fooo;client-secret=bar;tenant-id=9de53416-4431-4181-7a8b-23af3EXAMPLE
169+
```
170+
171+
For more information, see https://smallstep.com/docs/step-ca/cryptographic-protection/.
144172

145173
**--key**=`file`
146174
The `file` of the private key to use instead of creating a new one (PEM file).
@@ -426,8 +454,18 @@ $ step certificate create --csr --template csr.tpl --san coyote@acme.corp \
426454
"Wile E. Coyote" coyote.csr coyote.key
427455
```
428456
457+
Create a CSR using `step-kms-plugin`:
458+
```shell
459+
$ step certificate create --csr --key 'yubikey:slot-id=9a?pin=value=123456' coyote@acme.corp coyote.csr
460+
```
461+
429462
Create a root certificate using `step-kms-plugin`:
430463
```shell
464+
$ step certificate create --profile root-ca --key 'yubikey:slot-id=9a?pin=value=123456' 'KMS Root' root_ca.crt
465+
```
466+
467+
Create a root certificate using `step-kms-plugin` and the `--kms` flag:
468+
```shell
431469
$ step kms create \
432470
--kms 'pkcs11:module-path=/usr/local/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=password' \
433471
'pkcs11:id=4000;object=root-key'

‎step-cli/reference/certificate/needs-renewal/README.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ $ step certificate needs-renewal ./certificate.crt --bundle
8484
```
8585

8686
Check if the leaf certificate provided by smallstep.com has passed 66 percent
87-
of its vlaidity period:
87+
of its validity period:
8888
```shell
8989
$ step certificate needs-renewal https://smallstep.com
9090
```

‎step-cli/reference/certificate/sign/README.mdx‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,35 @@ The path to a private key for signing the CSR.
4141

4242

4343
**--kms**=`uri`
44-
The `uri` to configure a Cloud KMS or an HSM.
44+
The `uri` to configure a (cloud) KMS or an HSM.
45+
`uri` is formatted as **kmstype:[key=value;...]?[key=value&...]**. The **;**-separated
46+
parameters identify the KMS, and **&**-separated parameters contain credentials and additional configuration for those credentials.
47+
48+
Supported KMS types:
49+
50+
- **YubiKey PIV**: Use **yubikey:** URIs. Parameters: **serial**, **pin-value**, **pin-source**, **management-key**, **management-key-source**.
51+
52+
- **PKCS #11**: Use **pkcs11:** URIs. Parameters: **module-path**, **token**, **id**, **object**, **pin-value**, **pin-source**.
53+
54+
- **TPM 2.0**: Use **tpmkms:** URIs. Parameters: **name**, **device**, **attestation-ca-url**.
55+
56+
- **Google Cloud KMS**: Use **cloudkms:** URIs. Parameters: **credentials-file**.
57+
58+
- **AWS KMS**: Use **awskms:** URIs. Parameters: **region**, **profile**, **credentials-file**.
59+
60+
- **Azure Key Vault**: Use **azurekms:** URIs. Parameters: **tenant-id**, **client-id**, **client-secret**, **client-certificate-file**.
61+
62+
Examples:
63+
64+
```shell
65+
yubikey:pin-value=123456
66+
pkcs11:module-path=/usr/lib/softhsm/libsofthsm2.so;token=smallstep?pin-value=pass
67+
tpmkms:name=my-key;device=/dev/tpmrm0
68+
awskms:region=us-east-1
69+
azurekms:client-id=fooo;client-secret=bar;tenant-id=9de53416-4431-4181-7a8b-23af3EXAMPLE
70+
```
71+
72+
For more information, see https://smallstep.com/docs/step-ca/cryptographic-protection/.
4573

4674
**--profile**=`profile`
4775
The certificate profile sets various certificate details such as
@@ -196,4 +224,8 @@ $ step certificate sign \
196224
leaf.csr issuer.crt 'pkcs11:id=4001'
197225
```
198226
227+
Sign a CSR using a certificate and a key stored in a KMS:
228+
```shell
229+
$ step certificate sign leaf.csr yubikey-slot-id=9a 'yubikey-slot-id=9a?pin-value=123456'
230+
```
199231

0 commit comments

Comments
 (0)