step certificate needs-renewal

Name

step certificate needs-renewal -- Check if a certificate needs to be renewed

Usage

step certificate needs-renewal <cert-file or hostname>
[--expires-in=<percent|duration>] [--bundle] [--verbose]
[--roots=<root-bundle>] [--servername=<servername>]

Description

step certificate needs-renewal returns '0' if the certificate needs to be renewed based on its remaining lifetime. Returns '1' the certificate is within its validity lifetime bounds and does not need to be renewed. By default, a certificate "needs renewal" when it has passed 66% (default threshold) of its allotted lifetime. This threshold can be adjusted using the '--expires-in' flag. Additionally, by default only the leaf certificate will be checked by the command; to check each certificate in the chain use the '--bundle' flag.

Positional arguments

cert-file or hostname The path to a certificate OR a hostname with protocol prefix.

Options

--expires-in=percent|duration Check if the certificate expires within the given time window using percent|duration. If using percent, the input must be followed by a "%" character. If using duration, the input must be a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

--roots=roots Root certificate(s) that will be used to verify the authenticity of the remote server.

roots is a case-sensitive string and may be one of:

--bundle Check all certificates in the order in which they appear in the bundle.

--verbose, -v Print human readable affirmation if certificate requires renewal.

--servername=value TLS Server Name Indication that should be sent to request a specific certificate from the server.

Exit codes

This command returns '0' if the X509 certificate needs renewal, '1' if the X509 certificate does not need renewal, '2' if the X509 certificate file does not exist, and '255' for any other error.

Examples

Check if the leaf certificate in the file certificate.crt has passed 66 percent of its validity period:

Check if any certificate in the bundle has passed 66 percent of its validity period:

Check if the leaf certificate provided by smallstep.com has passed 66 percent of its vlaidity period:

Check if any certificate in the bundle for smallstep.com has has passed 66 percent of its validity period:

Check if certificate.crt expires within 1 hour 15 minutes from now:

Check if certificate for smallstep.com is expired or not:

Check if certificate has passed 75 percent of its validity period:

Check a remote certificate using a custom root certificate:

Check a remote certificate using a custom list of root certificates:

Check a remote certificate using a custom directory of root certificates: