From 56312038d66d3d94514891e69c7d1344a50f5852 Mon Sep 17 00:00:00 2001
From: Kazuki Yamaguchi <k@rhe.jp>
Date: Wed, 28 Jun 2023 12:10:50 +0900
Subject: [PATCH] [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".
---
 ext/openssl/ossl.c | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/ext/openssl/ossl.c b/ext/openssl/ossl.c
index 08e1d57b5..1b98d91e2 100644
--- a/ext/openssl/ossl.c
+++ b/ext/openssl/ossl.c
@@ -669,8 +669,8 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
  *
  *   key = OpenSSL::PKey::RSA.new 2048
  *
- *   open 'private_key.pem', 'w' do |io| io.write key.to_pem end
- *   open 'public_key.pem', 'w' do |io| io.write key.public_key.to_pem end
+ *   File.write 'private_key.pem', key.private_to_pem
+ *   File.write 'public_key.pem', key.public_to_pem
  *
  * === Exporting a Key
  *
@@ -681,11 +681,9 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
  *   cipher = OpenSSL::Cipher.new 'aes-256-cbc'
  *   password = 'my secure password goes here'
  *
- *   key_secure = key.export cipher, password
+ *   key_secure = key.private_to_pem cipher, password
  *
- *   open 'private.secure.pem', 'w' do |io|
- *     io.write key_secure
- *   end
+ *   File.write 'private.secure.pem', key_secure
  *
  * OpenSSL::Cipher.ciphers returns a list of available ciphers.
  *
@@ -945,10 +943,10 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
  *   ca_key = OpenSSL::PKey::RSA.new 2048
  *   password = 'my secure password goes here'
  *
- *   cipher = OpenSSL::Cipher.new 'aes-256-cbc'
+ *   cipher = 'aes-256-cbc'
  *
  *   open 'ca_key.pem', 'w', 0400 do |io|
- *     io.write ca_key.export(cipher, password)
+ *     io.write ca_key.private_to_pem(cipher, password)
  *   end
  *
  * === CA Certificate