doc: update documentation to be clearer about how to use OpenSSL 3.x API #915
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rhenium
reviewed
Jul 27, 2025
Comment on lines
462
to
+473
| * For the supported options, see the documentation for the 'openssl genpkey' | ||
| * utility command. | ||
| * utility command, visible as the manpage genpkey(1). | ||
| * | ||
| * The algorithm name will generally be RSA, DSA, EC, or DH. | ||
| * EcDSA keys are of type "EC" (not DSA), but have an 'ec_paramgen_curve' value | ||
| * set to values like secp384r1 or prime256v1. | ||
| * Note that the genpkey manpage can be mis-read to suggest it is | ||
| * 'ec_paramgen_curve:curve', but that incorrect, on the command line the colon | ||
| * separates the key from value. | ||
| * | ||
| * RSA keys are of type "RSA", and have a parameter "rsa_keygen_bits" | ||
| * giving the strength. |
There was a problem hiding this comment.
To add to the confusion, these names became outdated with OpenSSL 3: "rsa_keygen_bits" was renamed to "bits" and "ec_paramgen_curve" to "group". This is documented in EVP_PKEY-RSA(7) and EVP_PKEY-EC(7), but openssl-genpkey(1) appears to have fallen out of sync.
I'd prefer not to document about specific algorithms here, as the ctrl names don't appear to be stable. I think we should encourage to read the relevant man pages themselves.
Given that it's outdated, we should still update the references. I'd suggest something like
* See also the man page EVP_PKEY_generate(3). For supported options, refer to
* the corresponding man page for the algorithm, such as EVP_PKEY-RSA(7).
*
* For DSA, DH, EC, and RSA, each subclass provides a +generate+ method as a
* shorthand for key generation.
For the 4 key types, we have OpenSSL::PKey::{RSA,DSA,EC,DH}.generate as a convenient class method. It might be worth mentioning.
| @@ -503,6 +503,9 @@ ossl_ec_key_to_der(VALUE self) | |||
| * | |||
| * See also the OpenSSL documentation for EC_KEY_generate_key() | |||
| * | |||
| * With OpenSSL 3.0, PKEY objects are immutable, so to generate a new keypair, | |||
| * use OpenSSL::PKey.generate_key("EC", "ec_paramgen_curve" => "prime256v1") | |||
There was a problem hiding this comment.
Suggested change
| * use OpenSSL::PKey.generate_key("EC", "ec_paramgen_curve" => "prime256v1") | |
| * use <tt>OpenSSL::PKey::EC.generate("prime256v1")</tt>. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds a few more clues to the documentation, as the straight reference to the genpkey didn't help me update from openssl 1. to openssl 3.