[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
This commit is contained in:
Kazuki Yamaguchi 2023-07-12 22:27:54 +09:00
parent 4b6d667c63
commit f4bf80623f

View File

@ -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