1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[ruby/openssl] [DOC] enhance RDoc for exporting pkeys

Browse Source 
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.

https://github.com/ruby/openssl/commit/d22769af8f
This commit is contained in:
Kazuki Yamaguchi 2023-06-28 12:09:27 +09:00
parent fae6fd07fe
commit 0eaee5c000
5 changed files with 219 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
ext/openssl/ossl_pkey.c
View File

@ -875,6 +875,18 @@ ossl_pkey_private_to_der(int argc, VALUE *argv, VALUE self)
*
* Serializes the private key to PEM-encoded PKCS #8 format. See #private_to_der
* for more details.
*
* An unencrypted PEM-encoded key will look like:
*
* -----BEGIN PRIVATE KEY-----
* [...]
* -----END PRIVATE KEY-----
*
* An encrypted PEM-encoded key will look like:
*
* -----BEGIN ENCRYPTED PRIVATE KEY-----
* [...]
* -----END ENCRYPTED PRIVATE KEY-----
*/
static VALUE
ossl_pkey_private_to_pem(int argc, VALUE *argv, VALUE self)
@ -953,6 +965,12 @@ ossl_pkey_public_to_der(VALUE self)
* pkey.public_to_pem -> string
*
* Serializes the public key to PEM-encoded X.509 SubjectPublicKeyInfo format.
*
* A PEM-encoded key will look like:
*
* -----BEGIN PUBLIC KEY-----
* [...]
* -----END PUBLIC KEY-----
*/
static VALUE
ossl_pkey_public_to_pem(VALUE self)

29
ext/openssl/ossl_pkey_dh.c
View File

@ -216,9 +216,20 @@ ossl_dh_is_private(VALUE self)
* dh.to_pem -> aString
* dh.to_s -> aString
*
* Encodes this DH to its PEM encoding. Note that any existing per-session
* public/private keys will *not* get encoded, just the Diffie-Hellman
* parameters will be encoded.
* Serializes the DH parameters to a PEM-encoding.
*
* Note that any existing per-session public/private keys will *not* get
* encoded, just the Diffie-Hellman parameters will be encoded.
*
* PEM-encoded parameters will look like:
*
* -----BEGIN DH PARAMETERS-----
* [...]
* -----END DH PARAMETERS-----
*
* See also #public_to_pem (X.509 SubjectPublicKeyInfo) and
* #private_to_pem (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) for
* serialization with the private or public key components.
*/
static VALUE
ossl_dh_export(VALUE self)
@ -244,10 +255,14 @@ ossl_dh_export(VALUE self)
* call-seq:
* dh.to_der -> aString
*
* Encodes this DH to its DER encoding. Note that any existing per-session
* public/private keys will *not* get encoded, just the Diffie-Hellman
* parameters will be encoded.
* Serializes the DH parameters to a DER-encoding
*
* Note that any existing per-session public/private keys will *not* get
* encoded, just the Diffie-Hellman parameters will be encoded.
*
* See also #public_to_der (X.509 SubjectPublicKeyInfo) and
* #private_to_der (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) for
* serialization with the private or public key components.
*/
static VALUE
ossl_dh_to_der(VALUE self)

65
ext/openssl/ossl_pkey_dsa.c
View File

@ -211,16 +211,58 @@ ossl_dsa_is_private(VALUE self)
* dsa.to_pem([cipher, password]) -> aString
* dsa.to_s([cipher, password]) -> aString
*
* Encodes this DSA to its PEM encoding.
* Serializes a private or public key to a PEM-encoding.
*
* === Parameters
* * _cipher_ is an OpenSSL::Cipher.
* * _password_ is a string containing your password.
* [When the key contains public components only]
*
* === Examples
* DSA.to_pem -> aString
* DSA.to_pem(cipher, 'mypassword') -> aString
* Serializes it into an X.509 SubjectPublicKeyInfo.
* The parameters _cipher_ and _password_ are ignored.
*
* A PEM-encoded key will look like:
*
* -----BEGIN PUBLIC KEY-----
* [...]
* -----END PUBLIC KEY-----
*
* Consider using #public_to_pem instead. This serializes the key into an
* X.509 SubjectPublicKeyInfo regardless of whether it is a public key
* or a private key.
*
* [When the key contains private components, and no parameters are given]
*
* Serializes it into a traditional \OpenSSL DSAPrivateKey.
*
* A PEM-encoded key will look like:
*
* -----BEGIN DSA PRIVATE KEY-----
* [...]
* -----END DSA PRIVATE KEY-----
*
* [When the key contains private components, and _cipher_ and _password_ are given]
*
* Serializes it into a traditional \OpenSSL DSAPrivateKey and encrypts it in
* OpenSSL's traditional PEM encryption format.
* _cipher_ must be a cipher name understood by OpenSSL::Cipher.new or an
* instance of OpenSSL::Cipher.
*
* An encrypted PEM-encoded key will look like:
*
* -----BEGIN DSA PRIVATE KEY-----
* Proc-Type: 4,ENCRYPTED
* DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
*
* [...]
* -----END DSA PRIVATE KEY-----
*
* Note that this format uses MD5 to derive the encryption key, and hence
* will not be available on FIPS-compliant systems.
*
* <b>This method is kept for compatibility.</b>
* This should only be used when the traditional, non-standard \OpenSSL format
* is required.
*
* Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
* (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
*/
static VALUE
ossl_dsa_export(int argc, VALUE *argv, VALUE self)
@ -238,8 +280,15 @@ ossl_dsa_export(int argc, VALUE *argv, VALUE self)
* call-seq:
* dsa.to_der -> aString
*
* Encodes this DSA to its DER encoding.
* Serializes a private or public key to a DER-encoding.
*
* See #to_pem for details.
*
* <b>This method is kept for compatibility.</b>
* This should only be used when the traditional, non-standard \OpenSSL format
* is required.
*
* Consider using #public_to_der or #private_to_der instead.
*/
static VALUE
ossl_dsa_to_der(VALUE self)

70
ext/openssl/ossl_pkey_ec.c
View File

@ -400,13 +400,61 @@ static VALUE ossl_ec_key_is_private(VALUE self)
/*
* call-seq:
* key.export([cipher, pass_phrase]) => String
* key.to_pem([cipher, pass_phrase]) => String
* key.export([cipher, password]) => String
* key.to_pem([cipher, password]) => String
*
* Outputs the EC key in PEM encoding. If _cipher_ and _pass_phrase_ are given
* they will be used to encrypt the key. _cipher_ must be an OpenSSL::Cipher
* instance. Note that encryption will only be effective for a private key,
* public keys will always be encoded in plain text.
* Serializes a private or public key to a PEM-encoding.
*
* [When the key contains public components only]
*
* Serializes it into an X.509 SubjectPublicKeyInfo.
* The parameters _cipher_ and _password_ are ignored.
*
* A PEM-encoded key will look like:
*
* -----BEGIN PUBLIC KEY-----
* [...]
* -----END PUBLIC KEY-----
*
* Consider using #public_to_pem instead. This serializes the key into an
* X.509 SubjectPublicKeyInfo regardless of whether it is a public key
* or a private key.
*
* [When the key contains private components, and no parameters are given]
*
* Serializes it into a SEC 1/RFC 5915 ECPrivateKey.
*
* A PEM-encoded key will look like:
*
* -----BEGIN EC PRIVATE KEY-----
* [...]
* -----END EC PRIVATE KEY-----
*
* [When the key contains private components, and _cipher_ and _password_ are given]
*
* Serializes it into a SEC 1/RFC 5915 ECPrivateKey
* and encrypts it in OpenSSL's traditional PEM encryption format.
* _cipher_ must be a cipher name understood by OpenSSL::Cipher.new or an
* instance of OpenSSL::Cipher.
*
* An encrypted PEM-encoded key will look like:
*
* -----BEGIN EC PRIVATE KEY-----
* Proc-Type: 4,ENCRYPTED
* DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
*
* [...]
* -----END EC PRIVATE KEY-----
*
* Note that this format uses MD5 to derive the encryption key, and hence
* will not be available on FIPS-compliant systems.
*
* <b>This method is kept for compatibility.</b>
* This should only be used when the SEC 1/RFC 5915 ECPrivateKey format is
* required.
*
* Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
* (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
*/
static VALUE
ossl_ec_key_export(int argc, VALUE *argv, VALUE self)
@ -426,7 +474,15 @@ ossl_ec_key_export(int argc, VALUE *argv, VALUE self)
* call-seq:
* key.to_der => String
*
* See the OpenSSL documentation for i2d_ECPrivateKey_bio()
* Serializes a private or public key to a DER-encoding.
*
* See #to_pem for details.
*
* <b>This method is kept for compatibility.</b>
* This should only be used when the SEC 1/RFC 5915 ECPrivateKey format is
* required.
*
* Consider using #public_to_der or #private_to_der instead.
*/
static VALUE
ossl_ec_key_to_der(VALUE self)

63
ext/openssl/ossl_pkey_rsa.c
View File

@ -221,9 +221,57 @@ can_export_rsaprivatekey(VALUE self)
* rsa.to_pem([cipher, password]) => PEM-format String
* rsa.to_s([cipher, password]) => PEM-format String
*
* Outputs this keypair in PEM encoding. If _cipher_ and _password_ are
* given they will be used to encrypt the key. _cipher_ must be an
* OpenSSL::Cipher instance.
* Serializes a private or public key to a PEM-encoding.
*
* [When the key contains public components only]
*
* Serializes it into an X.509 SubjectPublicKeyInfo.
* The parameters _cipher_ and _password_ are ignored.
*
* A PEM-encoded key will look like:
*
* -----BEGIN PUBLIC KEY-----
* [...]
* -----END PUBLIC KEY-----
*
* Consider using #public_to_pem instead. This serializes the key into an
* X.509 SubjectPublicKeyInfo regardless of whether the key is a public key
* or a private key.
*
* [When the key contains private components, and no parameters are given]
*
* Serializes it into a PKCS #1 RSAPrivateKey.
*
* A PEM-encoded key will look like:
*
* -----BEGIN RSA PRIVATE KEY-----
* [...]
* -----END RSA PRIVATE KEY-----
*
* [When the key contains private components, and _cipher_ and _password_ are given]
*
* Serializes it into a PKCS #1 RSAPrivateKey
* and encrypts it in OpenSSL's traditional PEM encryption format.
* _cipher_ must be a cipher name understood by OpenSSL::Cipher.new or an
* instance of OpenSSL::Cipher.
*
* An encrypted PEM-encoded key will look like:
*
* -----BEGIN RSA PRIVATE KEY-----
* Proc-Type: 4,ENCRYPTED
* DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0
*
* [...]
* -----END RSA PRIVATE KEY-----
*
* Note that this format uses MD5 to derive the encryption key, and hence
* will not be available on FIPS-compliant systems.
*
* <b>This method is kept for compatibility.</b>
* This should only be used when the PKCS #1 RSAPrivateKey format is required.
*
* Consider using #public_to_pem (X.509 SubjectPublicKeyInfo) or #private_to_pem
* (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
*/
static VALUE
ossl_rsa_export(int argc, VALUE *argv, VALUE self)
@ -238,7 +286,14 @@ ossl_rsa_export(int argc, VALUE *argv, VALUE self)
* call-seq:
* rsa.to_der => DER-format String
*
* Outputs this keypair in DER encoding.
* Serializes a private or public key to a DER-encoding.
*
* See #to_pem for details.
*
* <b>This method is kept for compatibility.</b>
* This should only be used when the PKCS #1 RSAPrivateKey format is required.
*
* Consider using #public_to_der or #private_to_der instead.
*/
static VALUE
ossl_rsa_to_der(VALUE self)