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.
Path to which the public JWK should be written
Path to which the (JWE encrypted) private JWK should be written
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:
EC: Create an elliptic curve keypair
oct: Create a symmetric key (octet stream)
OKP: Create an octet key pair (for "Ed25519" curve)
RSA: Create an RSA keypair
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.
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
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:
HS256: HMAC using SHA-256
HS384: HMAC using SHA-384
HS512: HMAC using SHA-512
RS256: RSASSA-PKCS1-v1_5 using SHA-256
RS384: RSASSA-PKCS1-v1_5 using SHA-384
RS512: RSASSA-PKCS1-v1_5 using SHA-512
ES256: ECDSA using P-256 and SHA-256
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
If the key "use" is "enc" (encryption) algorithm must be one of:
RSA-OAEP: RSAES OAEP using default parameters
RSA-OAEP-256: RSAES OAEP using SHA-256 and MGF1 with SHA-256
A128KW: AES Key Wrap with default initial value using 128-bit key
A192KW: AES Key Wrap with default initial value using 192-bit key
A256KW: AES Key Wrap with default initial value using 256-bit key
dir: Direct use of a shared symmetric key as the content encryption key (CEK)
ECDH-ES+A128KW: ECDH-ES using Concat KDF and CEK wrapped with "A128KW"
ECDH-ES+A192KW: ECDH-ES using Concat KDF and CEK wrapped with "A192KW"
ECDH-ES+A256KW: ECDH-ES using Concat KDF and CEK wrapped with "A256KW"
A128GCMKW: Key wrapping with AES GCM using 128-bit key
A192GCMKW: Key wrapping with AES GCM using 192-bit key
A256GCMKW: Key wrapping with AES GCM using 256-bit key
PBES2-HS256+A128KW: PBES2 with HMAC SHA-256 and "A128KW" wrapping
PBES2-HS384+A192KW: PBES2 with HMAC SHA-256 and "A192KW" wrapping
PBES2-HS512+A256KW: PBES2 with HMAC SHA-256 and "A256KW" wrapping
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:
sig: The public key is used for verifying signatures.
enc: The public key is used for encrypting data.
Other values may be used but the generated JWKs will not work for signing or
encryption with this tool.
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.
Create a JWK representing the key encoded in an
existing pem-file instead of creating a new key.
The path to the file containing the password to encrypt or decrypt the private key.
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.
Force the overwrite of files without asking.
This command returns 0 on success and >0 if any error occurs.
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:
Cryptographically binding attributes to the public key using x509
certificates (e.g., as defined in PKIX / RFC2580)
Cryptographically binding attributes to the public key using JWTs
Storing the public key or (hashed) shared secret along with the bound
attributes in a secure database
Cryptographic mechanisms require establishing a "root of trust" that can sign
the bindings (the certificates or JWTs) asserting that the bound attributes are