Skip to content
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

Jump to bottom

[DOC] enhance RDoc for exporting pkeys #645

Merged
merged 3 commits into from
Aug 16, 2023
Merged

[DOC] enhance RDoc for exporting pkeys #645

merged 3 commits into from
Aug 16, 2023

Commits on Jul 1, 2023

  1. [DOC] prefer "password" to "passphrase" 

    Let's consistently use the word "password". Although they are considered
synonymous, the mixed usage in the rdoc can cause confusion.

OpenSSL::KDF.scrypt is an exception. This is because RFC 7914 refers to
the input parameter as "passphrase".
    @rhenium
    rhenium committed Jul 1, 2023
    Configuration menu
    Copy the full SHA
    06d6764 View commit details
    Browse the repository at this point in the history

  2. [DOC] prefer PKey#private_to_pem and #public_to_pem in RDoc 

    Suggest the use of OpenSSL::PKey::PKey#private_to_pem and #public_to_pem
in the top-level documentation. For new programs, these are recommended
over OpenSSL::PKey::RSA#export (also aliased as #to_s and #to_pem)
unless there is a specific reason to use it, i.e., unless the PKCS#1
output format specifically is required.

The output format of OpenSSL::PKey::RSA#export depends on whether the
key is a public key or a private key, which is very counter-intuitive.

Additionally, when called with arguments to encrypt a private key, as in
this example, OpenSSL's own, non-standard format is used. The man page
of PEM_write_bio_PrivateKey_traditional(3) in OpenSSL 1.1.1 or later
states that it "should only be used for compatibility with legacy
programs".
    @rhenium
    rhenium committed Jul 1, 2023
    Configuration menu
    Copy the full SHA
    5631203 View commit details
    Browse the repository at this point in the history

  3. [DOC] enhance RDoc for exporting pkeys 

    Describe the behavior of OpenSSL::PKey::{DH,DSA,EC,RSA}#to_pem
and #to_der more clearly. They return a different result depending on
whether the pkey is a public or private key. This was not documented
adequately.

Also, suggest the use of OpenSSL::PKey::PKey#private_to_pem
and #public_to_pem instead, if possible.
    @rhenium
    rhenium committed Jul 1, 2023
    Configuration menu
    Copy the full SHA
    d22769a View commit details
    Browse the repository at this point in the history