step crypto -- useful cryptographic plumbing
step crypto <command> [arguments]
The step crypto command group provides a selection of useful cryptographic primitives that balances completeness and safety (cryptographic strength, ease of use, and misuse prevention). Subcommands include flags and arguments to select algorithms and fine-tune behaviors, but we've selected safe defaults for you wherever possible.
Insecure or subtle cryptographic primitives and options are gated with flags to prevent accidental misuse. Such primitives and options will not work unless you pass the corresponding flags to indicate that you understand the risks (--insecure and --subtle, respectively). Our rationale for these decisions is usually documented in the SECURITY CONSIDERATIONS section of the help for each subcommand.
The strength of cryptographic mechanisms depends on the strength of all links in the security chain. This includes the quality and strength of algorithms, random number generation, distribution mechanisms, etc. It also includes protection against hostile observation and tampering as well as the security of the overall system including the operating system and personnel, etc. Where possible, we've selected secure defaults. Whenever a subtle or insecure cryptographic operation is attempted affirmative confirmation via prompt or command line flag is required, indicating that you understand and accept the risks. That said, many of these factors are beyond the scope of this tool.
This tool enforces a minimum key size of 256 bits for symmetric keys, which is generally considered quantum-safe and accepted as sufficient for the foreseeable future.
This tool enforces the NIST recommended minimum key size of 2048 bits for RSA keys, which RSA claims is equivalent in strength to 112 bit symmetric keys and is likely to be sufficient until 2030. An RSA key length of at least 3072 bits, which RSA claims is equivalent to 128 bit symmetric keys, should be used if security is required beyond 2030.
Elliptic curve cryptography is generally believed to be secure with shorter keys than RSA requires. NIST guidelines state that ECC keys should be twice the length of the equivalent strength symmetric key. The rough equivalencies for the elliptic curves supported by this tool are:
|key type||curve||RSA equivalent||symmetric key equivalent|
|EC||P-256||~3000 bits||~128 bits|
|EC||P-384||~4096 bits||~192 bits|
|EC||P-521||~15000 bits||~256 bits|
|OKP||Ed25519||~3000 bits||~140 bits|
Elliptic curve cryptography has the additional advantages of much smaller key sizes for equivalent security levels, and much faster cryptographic operations compared to RSA. The strength of these keys is generally considered sufficient for the predictable and foreseeable future.
Note that for cryptographic protocols that have perfect forward secrecy and only use asymmetric keys for symmetric key negotiation your system will remain secure against future threats as long as the keys are large enough that they cannot be cracked today. In other words, sizing your keys to protect against potential future threats is largely irrelevant.
In general you should not use an asymmetric keypair for both signing and encryption. Using a single key for both operations can introduce attack vectors that would not otherwise exist. Attacks aside, signing keys and encryption keys generally have different life cycles. Signing keys are generally destroyed once they're no longer useful for singing new data. Encryption keys, on the other hand, must be retained as long as data exists that was encrypted for the key. So using a signing key for encryption may force you to retain a signing key for longer than it's needed, leaving it susceptible to misuse.
Raw public or private keys don't have any associated data, therefore this tool cannot enforce key use on raw keys and this responsibility is up to you. For keys in an "envelope" the envelope typically includes key use restrictions (e.g., the "use" parameter in JWKs and the "Key Usage" attribute of X.509 certificates). This tool generally requires key use to be specified when creating an enveloped key, and enforces key use restrictions when an enveloped key is being used.
There is some concern that certain standard elliptic curves are very hard to implement correctly. These concerns are not purely theoretical. Implementation issues have been uncovered and real attacks have been demonstrated.
While we take these concerns seriously, these curves are widely used in practice, largely because they are perceived to be stronger than RSA and have been implemented in more places than the "safe curves". Therefore, we've opted not to gate non-safe curves. We've further elected to make P-256 the default curve for EC keys.
Still, it is important to be aware of the security risks associated with their risk. You should consider using "safe curves" if possible. We may change our mind as support for safe curves improves.
Safe and non-safe curves implemented by this tool are:
For more information see https://safecurves.cr.yp.to/
Quantum-safe cryptography refers to keys and algorithms that are secure against an attack by a quantum computer. As of 2018 most public key algorithms are not quantum safe. In particular, none of the public key algorithms implemented by this tool are quantum safe. However, no quantum computer exists that is powerful enough to break current algorithms. Using cryptographic protocols with forward secrecy is the best way to protect against future quantum attacks.
A cryptosystem or protocol has forward secrecy (or perfect forward secrecy) if, for each session or interaction, a random key is generated such that an attacker with access to all private keys would still not know the generated key. This can be accomplished using Diffie-Hellman key exchange, for instance.
Forward secrecy can protect against an attacker who stores intercepted communication and waits for your private key to be compromised, at which point they could decrypt the stored communication. It also offers good protection against quantum attacks since symmetric key cryptosystems like AES are already considered quantum resistant with sufficiently large key sizes. The current best quantum attack against symmetric key systems requires work proportional to the square of the size of the key space. In other words, a symmetric key is half as strong against a quantum attack vs. a conventional attack, so your key needs to be twice as long for equivalent quantum-safe security. A 256 bit symmetric key in the context of a quantum attack is equivalent in strength to a 128 bit key in the context of a conventional attack.
|change-pass||change password of an encrypted private key (PEM or JWK format)|
|keypair||generate a public / private keypair in PEM format|
|jwk||create JWKs (JSON Web Keys) and manage JWK Key Sets|
|jwt||sign and verify data using JSON Web Tokens (JWT)|
|jwe||encrypt and decrypt data and keys using JSON Web Encryption (JWE)|
|jws||sign and verify data using JSON Web Signature (JWS)|
|jose||collection of JOSE utilities|
|hash||generate and check hashes of files and directories|
|kdf||key derivation functions for password hashing and verification|
|nacl||easy-to-use high-speed tools for encryption and signing|
|otp||generate and verify one-time passwords|
|winpe||extract certificates and verify Windows Portable Executable files|