From f4bf80623fe72295cfa4a64de38a062d81359643 Mon Sep 17 00:00:00 2001
From: Kazuki Yamaguchi <k@rhe.jp>
Date: Wed, 12 Jul 2023 22:27:54 +0900
Subject: [ruby/openssl] [DOC] remove top-level example for
 OpenSSL::Cipher#pkcs5_keyivgen (https://github.com/ruby/openssl/pull/647)

OpenSSL::Cipher#pkcs5_keyivgen should only be used when it is
absolutely necessary for compatibility with ancient applications.
Having an example can be misleading. We already have another example
for OpenSSL::Cipher in which PBKDF2 is used to derive a key.

As described in the rdoc of OpenSSL::Cipher#pkcs5_keyivgen, it is
compatible with PKCS#5 PBES1 (PKCS#5 v1.5) only when used in combination
of a hash function MD2, MD5, or SHA-1, and a cipher DES-CBC or RC2-CBC.
This example uses MD5 as the hash function and combines it with AES.
This is considered insecure and also using a non-standard technique to
derive longer keys.

https://github.com/ruby/openssl/commit/e379cc0cca
---
 ext/openssl/ossl.c | 39 ---------------------------------------
 1 file changed, 39 deletions(-)

(limited to 'ext/openssl/ossl.c')

diff --git a/ext/openssl/ossl.c b/ext/openssl/ossl.c
index 0ffb817fb5..e67832d466 100644
--- a/ext/openssl/ossl.c
+++ b/ext/openssl/ossl.c
@@ -827,45 +827,6 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
  *   decrypted = cipher.update encrypted
  *   decrypted << cipher.final
  *
- * == PKCS #5 Password-based Encryption
- *
- * PKCS #5 is a password-based encryption standard documented at
- * RFC2898[http://www.ietf.org/rfc/rfc2898.txt].  It allows a short password or
- * passphrase to be used to create a secure encryption key. If possible, PBKDF2
- * as described above should be used if the circumstances allow it.
- *
- * PKCS #5 uses a Cipher, a pass phrase and a salt to generate an encryption
- * key.
- *
- *   pass_phrase = 'my secure pass phrase goes here'
- *   salt = '8 octets'
- *
- * === Encryption
- *
- * First set up the cipher for encryption
- *
- *   encryptor = OpenSSL::Cipher.new 'aes-256-cbc'
- *   encryptor.encrypt
- *   encryptor.pkcs5_keyivgen pass_phrase, salt
- *
- * Then pass the data you want to encrypt through
- *
- *   encrypted = encryptor.update 'top secret document'
- *   encrypted << encryptor.final
- *
- * === Decryption
- *
- * Use a new Cipher instance set up for decryption
- *
- *   decryptor = OpenSSL::Cipher.new 'aes-256-cbc'
- *   decryptor.decrypt
- *   decryptor.pkcs5_keyivgen pass_phrase, salt
- *
- * Then pass the data you want to decrypt through
- *
- *   plain = decryptor.update encrypted
- *   plain << decryptor.final
- *
  * == X509 Certificates
  *
  * === Creating a Certificate
-- 
cgit v1.2.3