step crypto jwt sign – create a signed JWT data structure
step crypto jwt sign [- |
step crypto jwt sign command generates a signed JSON Web Token (JWT) by computing a digital signature or message authentication code for a JSON payload. By default, the payload to sign is read from STDIN and the JWT will be written to STDOUT. The suggested pronunciation of JWT is the same as the English word “jot”.
A JWT is a compact data structure used to represent some JSON encoded “claims” that are passed as the payload of a JWS or JWE structure, enabling the claims to be digitally signed and/or encrypted. The “claims” (or “claim set”) are represented as an ordinary JSON object. JWTs are represented using a compact format that's URL safe and can be used in space-constrained environments. JWTs can be passed in HTTP Authorization headers and as URI query parameters.
A “claim” is a piece of information asserted about a subject, represented as a
key/value pair. Logically a verified JWT should be interpreted as “
claim-value” for each claim.
Some optional arguments introduce subtle security considerations if omitted.
These considerations should be carefully analyzed. Therefore, omitting
arguments requires the use of the –subtle flag as a misuse prevention
A JWT signed using JWS has three parts:
1. A base64 encoded JSON object representing the JOSE (JSON Object Signing and Encryption) header that describes the cryptographic operations applied to the JWT Claims Set 2. A base64 encoded JSON object representing the JWT Claims Set 3. A base64 encoded digital signature of message authentication code
For examples, see step help crypto jwt.
- The signature or MAC algorithm to use. Algorithms are case-sensitive strings defined in RFC7518. The selected algorithm must be compatible with the key type. This flag is optional. If not specified, the “alg” member of the JWK is used. If the JWK has no “alg” member then a default is selected depending on the JWK key type. If the JWK has an “alg” member and the “alg” flag is passed the two options must match unless the ‘–subtle’ flag is also passed.
algorithmis a case-sensitive string and must be one of:
HS256 : HMAC using SHA-256 (default for “oct” key type)
HS384 : HMAC using SHA-384
HS512 : HMAC using SHA-512
RS256 : RSASSA-PKCS1-v1_5 using SHA-256 (default for “RSA” key type)
RS384 : RSASSA-PKCS1-v1_5 using SHA-384
RS512 : RSASSA-PKCS1-v1_5 using SHA-512
ES256 : ECDSA using P-256 and SHA-256 (default for “EC” key type)
ES384 : ECDSA using P-384 and SHA-384
ES512 : ECDSA using P-521 and SHA-512
PS256 : RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384 : RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512 : RSASSA-PSS using SHA-512 and MGF1 with SHA-512
EdDSA : EdDSA signature algorithm
- The issuer of this JWT. The processing of this claim is generally application specific. Typically, the issuer must match the name of some trusted entity (e.g., an identity provider like “https://accounts.google.com") and identify which key(s) to use for JWT verification and/or decryption (e.g., the keys at “https://www.googleapis.com/oauth2/v3/certs").
issueris a case-sensitive string.
- The intended recipient(s) of the JWT, encoded as the “aud” claim in the JWT. Recipient(s) must identify themselves with one or more of the values in the “aud” claim. The “aud” claim can be a string (indicating a single recipient) or an array (indicating multiple potential recipients). This flag can be used multiple times to generate a JWK with multiple intended recipients.
audienceis a case-sensitive string.
- The subject of this JWT. The “claims” are normally interpreted as statements about this subject. The subject must either be locally unique in the context of the issuer or globally unique. The processing of this claim is generally application specific.
subjectis a case-sensitive string.
- The expiration time on or after which the JWT must not be accepted.
expirationmust be a numeric value representing a Unix timestamp.
- The time before which the JWT must not be accepted.
not-beforemust be a numeric value representing a Unix timestamp. If not provided, the current time is used.
- The time at which the JWT was issued, used to determine the age of the JWT. ISSUED_AT must be a numeric value representing a Unix timestamp. If not provided, the current time is used.
- A unique identifier for the JWT. The identifier must be assigned in a manner
that ensures that there is a negligible probability that the same value will
be accidentally assigned to multiple JWTs. The JTI claim can be used to
prevent a JWT from being replayed (i.e., recipient(s) can use
jtito make a JWT one-time-use). The
jtiargument is a case-sensitive string. If the –jti flag is used without an argument a
jtiwill be generated randomly with sufficient entropy to satisfy the collision-resistance criteria.
pathto the key with which to sign the JWT. JWTs can be signed using a private JWK (or a JWK encrypted as a JWE payload) or a PEM encoded private key (or a private key encrypted using the modes described on RFC 1423 or with PBES2+PBKDF2 described in RFC 2898).
- The JWK Set containing the key to use to sign the JWT. The
jwksargument should be the name of a file. The file contents should be a JWK Set or a JWE with a JWK Set payload. The –jwks flag requires the use of the –kid flag to specify which key to use.
- The ID of the key used to sign the JWT. The
kidargument is a case-sensitive string. When used with ‘–jwk’ the
kidvalue must match the “kid” member of the JWK. When used with –jwks (a JWK Set) the
kidvalue must match the “kid” member of one of the JWKs in the JWK Set.
- The path to the
filecontaining the password to decrypt the key.
- Certificate (
chain) in PEM format to store in the ‘x5c’ header of a JWT.
pathin PEM format to use for the ‘x5t’ header of a JWS or JWT