Skip to content

doc: update documentation to be clearer about how to use OpenSSL 3.x API #915

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+18 −1
Open

doc: update documentation to be clearer about how to use OpenSSL 3.x API #915

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion ext/openssl/ossl_pkey.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -460,11 +460,25 @@ pkey_generate(int argc, VALUE *argv, VALUE self, int genparam)
* may be called once or multiple times, or may not even be called.
*
* 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.
Comment on lines 462 to +473
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

*
* == Example
* pkey = OpenSSL::PKey.generate_parameters("DSA", "dsa_paramgen_bits" => 2048)
* p pkey.p.num_bits #=> 2048
*
* pkey = OpenSSL::PKey.generate_parameters("EC", "ec_paramgen_curve"=> "prime256v1")
* p key.group.curve_name #=> "prime256v1"
*
*/
static VALUE
ossl_pkey_s_generate_parameters(int argc, VALUE *argv, VALUE self)
Expand Down
3 changes: 3 additions & 0 deletions ext/openssl/ossl_pkey_ec.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* use OpenSSL::PKey.generate_key("EC", "ec_paramgen_curve" => "prime256v1")
* use <tt>OpenSSL::PKey::EC.generate("prime256v1")</tt>.

*
* === Example
* ec = OpenSSL::PKey::EC.new("prime256v1")
* p ec.private_key # => nil
Expand Down
Loading