step crypto jwk create

Name

step crypto jwk create -- create a JWK (JSON Web Key)

Usage

step crypto jwk create <public-jwk-file> <private-jwk-file>
[--kty=<type>] [--alg=<algorithm>] [--use=<use>]
[--size=<size>] [--crv=<curve>] [--kid=<kid>]
[--from-pem=<pem-file>] [--password-file=<file>]

Description

step crypto jwk create generates a new JWK (JSON Web Key) or constructs a JWK from an existing key. The generated JWK conforms to RFC7517 and can be used to sign and encrypt data using JWT, JWS, and JWE.

Files containing private keys are encrypted by default. You'll be prompted for a password. Keys are written with file mode 0600 (i.e., readable and writable only by the current user).

All flags are optional. Defaults are suitable for most use cases.

Positional arguments

public-jwk-file Path to which the public JWK should be written

private-jwk-file Path to which the (JWE encrypted) private JWK should be written

Options

--kty=type, --type=type The type of key to create. Corresponds to the "kty" JWK parameter. If unset, default is EC.

type is a case-sensitive string and must be one of:

--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.

--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:

--alg=algorithm, --algorithm=algorithm The algorithm intended for use with this key. Corresponds to the "alg" JWK parameter. algorithm is case-sensitive. If unset, the default depends on the key use, key type, and curve (for EC and OKP keys). Defaults are:

If the key "use" is "sig" (signing) algorithm must be one of:

If the key "use" is "enc" (encryption) algorithm must be one of:

--use=use The intended use of the public key. Corresponds to the "use" JWK parameter. The "use" parameter indicates whether the public key is used for encrypting data or verifying the signature on data.

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

Other values may be used but the generated JWKs will not work for signing or encryption with this tool.

--kid=kid The kid (key ID) for this JWK. Corresponds to the "kid" JWK parameter. Used to identify an individual key in a JWK Set, for example. kid is a case-sensitive string. If unset, the JWK Thumbprint [RFC7638] is used as kid. See step help crypto jwk thumbprint for more information on JWK Thumbprints.

--from-pem=pem-file Create a JWK representing the key encoded in an existing pem-file instead of creating a new key.

--password-file=file The path to the file containing the password to encrypt or decrypt the private key.

--no-password Do not ask for a password to encrypt a private key. Sensitive key material will be written to disk unencrypted. This is not recommended. Requires --insecure flag.

--subtle

--insecure

-f, --force Force the overwrite of files without asking.

Exit codes

This command returns 0 on success and >0 if any error occurs.

Security considerations

All security considerations from step help crypto are relevant here.

Preventing hostile disclosure of non-public key material

It is critical that any private and symmetric key material be protected from unauthorized disclosure or modification. This includes the private key for asymmetric key types (RSA, EC, and OKP) and the shared secret for symmetric key types (oct). One means of protection is encryption. Keys can also be stored in hardware or software "security enclaves" such as HSMs and TPMs or operating system keychain management tools.

Key provenance and bindings

Key provenance should always be scrutinized. You should not trust a key that was obtained in an untrustworthy manner (e.g., non-TLS HTTP).

Usually applications use keys to make authorization decisions based on attributes "bound" to the key such as the key owner's name or role. In these scenarios the strength of the system's security depends on the strength of these "bindings". There are a variety of mechanisms for securely binding attributes to keys, including:

Cryptographic mechanisms require establishing a "root of trust" that can sign the bindings (the certificates or JWTs) asserting that the bound attributes are correct.

Standards

[RFC7517] Jones, M., "JSON Web Key (JWK)", https://tools.ietf.org/html/rfc7517

[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", https://tools.ietf.org/html/rfc7518

[RFC7638] M. Jones, N. Sakimura., "JSON Web Key (JWK) Thumbprint", https://tools.ietf.org/html/rfc7638

[RFC8037] I. Liusvaara., "CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)", https://tools.ietf.org/html/rfc8037

Examples

Create a new JWK using default options:

Create an RSA JWK:

Create a symmetric key (oct key type):

Create a key for use with the Ed25519 cryptosystem:

Create a key from an existing PEM file:

Create an 4096 bit RSA encryption key:

Create a 192 bit symmetric encryption key for use with AES Key Wrap: