step-cli v0.26.2 reference update

smallstep · Jun 13, 2024 · f8d7866 · f8d7866
1 parent d1ea023
commit f8d7866
Show file tree

Hide file tree

Showing 8 changed files with 429 additions and 244 deletions.
diff --git a/manifest.json b/manifest.json
diff --git a/step-cli/reference/README.mdx b/step-cli/reference/README.mdx
@@ -65,7 +65,7 @@ print the version
 
 ## Version
 
-Smallstep CLI/0.26.1 (linux/amd64)
+Smallstep CLI/0.26.2 (linux/amd64)
 
 ## Copyright
 

diff --git a/step-cli/reference/ca/provisioner/add/README.mdx b/step-cli/reference/ca/provisioner/add/README.mdx
@@ -18,6 +18,8 @@ step ca provisioner add <name> --type=JWK [--public-key=<file>]
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>] [--ssh-template=<file>]
+[--ssh-template-data=<file>]
 
 ACME
 
@@ -27,6 +29,7 @@ step ca provisioner add <name> --type=ACME
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>]
 
 OIDC
 
@@ -37,13 +40,17 @@ step ca provisioner add <name> --type=OIDC
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>] [--ssh-template=<file>]
+[--ssh-template-data=<file>]
 
 X5C
 
 step ca provisioner add <name> --type=X5C --x5c-roots=<file>
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>] [--ssh-template=<file>]
+[--ssh-template-data=<file>]
 
 SSHPOP
 
@@ -59,14 +66,15 @@ step ca provisioner add <name> --type=Nebula --nebula-root=<file>
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
 
-K8SSA
+K8SSA (Kubernetes Service Account)
 
 step ca provisioner add <name> --type=K8SSA [--public-key=<file>]
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>]
 
-IID
+IID (AWS/GCP/Azure)
 
 step ca provisioner add <name> --type=[AWS|Azure|GCP]
 [--aws-account=<id>] [--gcp-service-account=<name>] [--gcp-project=<name>]
@@ -77,6 +85,8 @@ step ca provisioner add <name> --type=[AWS|Azure|GCP]
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>] [--ssh-template=<file>]
+[--ssh-template-data=<file>]
 
 SCEP
 
@@ -88,6 +98,7 @@ step ca provisioner add <name> --type=SCEP [--force-cn] [--challenge=<challenge>
 [--admin-cert=<file>] [--admin-key=<file>] [--admin-subject=<subject>]
 [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>]
 ```
 
 ## Description

diff --git a/step-cli/reference/ca/provisioner/update/README.mdx b/step-cli/reference/ca/provisioner/update/README.mdx
@@ -18,6 +18,8 @@ step ca provisioner update <name> [--public-key=<file>]
 [--admin-cert=<file>] [--admin-key=<file>] [--admin-subject=<subject>]
 [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>] [--ssh-template=<file>]
+[--ssh-template-data=<file>]
 
 ACME
 
@@ -27,6 +29,7 @@ step ca provisioner update <name> [--force-cn] [--require-eab]
 [--attestation-roots=<file>] [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>]
 
 OIDC
 
@@ -36,23 +39,30 @@ step ca provisioner update <name>
 [--domain=<domain>] [--remove-domain=<domain>]
 [--group=<group>] [--remove-group=<group>]
 [--admin=<email>]... [--remove-admin=<email>]...
+[--scope=<scope>] [--remove-scope=<scope>]
+[--auth-param=<auth-param>] [--remove-auth-param=<auth-param>]
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>] [--ssh-template=<file>]
+[--ssh-template-data=<file>]
 
 X5C
 
 step ca provisioner update <name> --x5c-roots=<file>
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>] [--ssh-template=<file>]
+[--ssh-template-data=<file>]
 
 K8SSA (Kubernetes Service Account)
 
 step ca provisioner update <name> [--public-key=<file>]
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>]
 
 IID (AWS/GCP/Azure)
 
@@ -67,6 +77,8 @@ step ca provisioner update <name>
 [--admin-cert=<file>] [--admin-key=<file>]
 [--admin-subject=<subject>] [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>] [--ssh-template=<file>]
+[--ssh-template-data=<file>]
 
 SCEP
 
@@ -78,6 +90,7 @@ step ca provisioner update <name> [--force-cn] [--challenge=<challenge>]
 [--admin-cert=<file>] [--admin-key=<file>] [--admin-subject=<subject>]
 [--admin-provisioner=<name>] [--admin-password-file=<file>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>] [--ca-config=<file>]
+[--x509-template=<file>] [--x509-template-data=<file>]
 ```
 
 ## Description
@@ -142,6 +155,14 @@ Use the '--group' flag multiple times to configure multiple groups.
 **--tenant-id**=`tenant-id`
 The `tenant-id` used to replace the templatized tenantid value in the OpenID Configuration.
 
+**--scope**=`scope`
+The `scope` list used to validate the scopes extension in an OpenID Connect token.
+Use the '--scope' flag multiple times to configure multiple scopes.
+
+**--auth-param**=`auth-param`
+The `auth-param` list used to validate the auth-params extension in an OpenID Connect token.
+Use the '--auth-param' flag multiple times to configure multiple auth-params.
+
 **--x5c-roots**=`file`, **--x5c-root**=`file`
 PEM-formatted root certificate(s) `file` used to validate the signature on X5C
 provisioning tokens.

diff --git a/step-cli/reference/certificate/sign/README.mdx b/step-cli/reference/certificate/sign/README.mdx
@@ -14,8 +14,8 @@ menu:
 
 ```raw
 step certificate sign <csr-file> <crt-file> <key-file>
-[--profile=<profile>] [--template=<file>] 
-[--set=<key=value>] [--set-file=<file>]
+[--profile=<profile>] [--template=<file>]
+[--set=<key=value>] [--set-file=<file>] [--omit-cn-san]
 [--password-file=<file>] [--path-len=<maximum>]
 [--not-before=<time|duration>] [--not-after=<time|duration>]
 [--bundle]
@@ -65,6 +65,13 @@ The `key=value` pair with template data variables. Use the **--set** flag multip
 **--set-file**=`file`
 The JSON `file` with the template data variables.
 
+**--omit-cn-san**
+Do not add CSR Common Name as SAN extension in resulting certificate.
+By default, the CSR Common Name will be added as a SAN extension only if the CSR
+does not contain any SANs. Note that if the Common Name is already captured as a
+SAN extension in the CSR then it will still appear as a SAN extension in the
+certificate.
+
 **--password-file**=`file`
 The path to the `file` containing the password to encrypt or decrypt the private key.
 
@@ -112,6 +119,11 @@ Sign a CSR with custom validity and bundle the new certificate with the issuer:
 $ step certificate sign --bundle --not-before -1m --not-after 16h leaf.csr issuer.crt issuer.key
 ```
 
+Sign a CSR but do not add the Common Name to the SANs extension of the certificate:
+```shell
+$ step certificate sign --omit-cn-san leaf.csr issuer.crt issuer.key
+```
+
 Sign an intermediate ca:
 ```shell
 $ step certificate sign --profile intermediate-ca intermediate.csr issuer.crt issuer.key

diff --git a/step-cli/reference/certificate/verify/README.mdx b/step-cli/reference/certificate/verify/README.mdx
@@ -15,6 +15,9 @@ menu:
 ```raw
 step certificate verify <crt-file> [--host=<host>]
 [--roots=<root-bundle>] [--servername=<servername>]
+[--issuing-ca=<ca-cert-file>] [--verbose]
+[--verify-ocsp]] [--ocsp-endpoint]=url
+[--verify-crl] [--crl-endpoint]=url
 ```
 
 ## Description
@@ -47,9 +50,30 @@ authenticity of the remote server.
 
 - **directory**: Relative or full path to a directory. Every PEM encoded certificate from each file in the directory will be used for path validation.
 
+**--issuing-ca**=`file`
+The certificate issuer CA `file` needed to communicate with OCSP and verify a CRL. By default the issuing CA will be taken from the cert Issuing Certificate URL extension.
+
+**--verify-ocsp**
+Verify the certificate against it's OCSP.
+
+**--ocsp-endpoint**=`value`
+The OCSP endpoint to use. If not provided step will attempt to check it against the certificate's OCSPServer AIA extension endpoints.
+
+**--verify-crl**
+Verify the certificate against it's CRL.
+
+**--crl-endpoint**=`value`
+The CRL endpoint to use. If not provided step will attempt to check it against the certificate's CRLDistributionPoints extension endpoints.
+
+**--verbose**, **-v**
+Print result of certificate verification to stdout on success
+
 **--servername**=`value`
 TLS Server Name Indication that should be sent to request a specific certificate from the server.
 
+**--insecure**
+
+
 ## Exit codes
 
 This command returns 0 on success and >0 if any error occurs.
@@ -87,4 +111,21 @@ Verify a certificate using a custom directory of root certificates for path vali
 $ step certificate verify ./certificate.crt --roots ./root-certificates/
 ```
 
+Verify a certificate including OCSP and CRL using CRL and OCSP defined in the certificate
+
+```shell
+$ step certificate verify ./certificate.crt --verify-crl --verify-ocsp
+```
+
+Verify a certificate including OCSP and specifying an OCSP server
+
+```shell
+$ step certificate verify ./certificate.crt --verify-ocsp --ocsp-endpoint http://acme.com/ocsp
+```
+
+Verify a certificate including CRL and specificing a CRL server and providing the issuing CA certificate
+
+```shell
+$ step certificate verify ./certificate.crt --issuing-ca ./issuing_ca.pem  --verify-crl --crl-endpoint http://acme.com/crl
+```
 
diff --git a/step-cli/reference/ssh/certificate/README.mdx b/step-cli/reference/ssh/certificate/README.mdx
@@ -16,10 +16,11 @@ menu:
 step ssh certificate <key-id> <key-file>
 [--host] [--host-id] [--sign] [--principal=<string>]
 [--password-file=<file>] [--provisioner-password-file=<file>]
-[--add-user] [--not-before=<time|duration>]
+[--add-user] [--not-before=<time|duration>] [--comment=<comment>]
 [--not-after=<time|duration>] [--token=<token>] [--issuer=<name>]
 [--no-password] [--insecure] [--force] [--x5c-cert=<file>]
 [--x5c-key=<file>] [--k8ssa-token-path=<file>] [--no-agent]
+[--kty=<key-type>] [--curve=<curve>] [--size=<size>]
 [--ca-url=<uri>] [--root=<file>] [--context=<name>]
 ```
 
@@ -146,6 +147,40 @@ The path to the `file` containing the password to decrypt the one-time token
 **--sign**
 Sign the public key passed as an argument instead of creating one.
 
+**--kty**=`kty`
+The `kty` to build the certificate upon.
+If unset, default is EC.
+
+`kty` is a case-sensitive string and must be one of:
+
+- **EC**: Create an **elliptic curve** keypair
+
+- **OKP**: Create an octet key pair (for **"Ed25519"** curve)
+
+- **RSA**: Create an **RSA** keypair
+
+**--crv**=`curve`, **--curve**=`curve`
+The elliptic `curve` to use for EC and OKP key types. Corresponds
+to the **"crv"** JWK parameter. Valid curves are defined in JWA [RFC7518]. If
+unset, default is P-256 for EC keys and Ed25519 for OKP keys.
+
+`curve` is a case-sensitive string and must be one of:
+
+- **P-256**: NIST P-256 Curve
+
+- **P-384**: NIST P-384 Curve
+
+- **P-521**: NIST P-521 Curve
+
+- **Ed25519**: Ed25519 Curve
+
+**--size**=`size`
+The `size` (in bits) of the key for RSA and oct key types. RSA keys require a
+minimum key size of 2048 bits. If unset, default is 2048 bits for RSA keys and 128 bits for oct keys.
+
+**--comment**=`value`
+The comment used when adding the certificate to an agent. Defaults to the subject if not provided.
+
 **--kms**=`uri`
 The `uri` to configure a Cloud KMS or an HSM.
 
@@ -249,3 +284,15 @@ Generate a new key pair and a certificate using a given token:
 $ step ssh certificate --token $TOKEN mariano@work id_ecdsa
 ```
 
+Create an EC pair with curve P-521 and certificate:
+
+```shell
+$  step ssh certificate --kty EC --curve "P-521" mariano@work id_ecdsa
+```
+
+Create an Octet Key Pair with curve Ed25519 and certificate:
+
+```shell
+$  step ssh certificate --kty OKP --curve Ed25519 mariano@work id_ed25519
+```
+