It was originally sorted in alphabetical order, but it has been broken
over time. Let's fix it.

https://github.com/ruby/openssl/commit/974c67f38f

https://github.com/ruby/openssl/commit/85d6b7f192

Update the references to the file "LICENCE" with "COPYING".

The file LICENCE doesn't exist in ruby/ruby nor ruby/openssl. This has
been always the case since OpenSSL for Ruby 2 was merged to the ruby
tree as a standard library in 2003.

In OpenSSL for Ruby 2's CVS repository[1], the LICENCE file contained
an old version of the Ruby License, identical to the COPYING file that
was in Ruby's tree at that time (r4128[2]).

[1] http://cvs.savannah.gnu.org/viewvc/rubypki/ossl2/LICENCE?revision=1.1.1.1&view=markup
[2] https://github.com/ruby/ruby/blob/231247c010acba191b78ed2d1310c935e63ad919/COPYING

https://github.com/ruby/openssl/commit/5bccf07d04

Remove the OSSL_DEBUG flag and OpenSSL.mem_check_start which is only
compiled when the flag is given. They are meant purely for development
of Ruby/OpenSSL.

OpenSSL.mem_check_start helped us find memory leak bugs in past, but
it is no longer working with the recent OpenSSL versions. Let's just
remove it now.

https://github.com/ruby/openssl/commit/8c7a6a17e2

* Fix the wrong man reference.
* According to the LIBRESSL_VERSION_NUMBER(3), the value always ends with 00f.

```
$ man -M /home/jaruga/.local/libressl-6650dce/share/man/ 3 LIBRESSL_VERSION_NUMBER
...
DESCRIPTION
     OPENSSL_VERSION_NUMBER and LIBRESSL_VERSION_NUMBER are numeric release version
     identifiers.  The first two digits contain the major release number, the third and
     fourth digits the minor release number, and the fifth and sixth digits the fix re‐
     lease number.  For OpenSSL, the seventh and eight digits contain the patch release
     number and the final digit is 0 for development, 1 to e for betas 1 to 14, or f
     for release.  For LibreSSL, OPENSSL_VERSION_NUMBER is always 0x020000000, and
     LIBRESSL_VERSION_NUMBER always ends with 00f.
```

https://github.com/ruby/openssl/commit/296c859d18

* Updated the `OpenSSL::OPENSSL_VERSION_NUMBER` comment explaining the format.
* Added the `OpenSSL::LIBRESSL_VERSION_NUMBER` to print LibreSSL version number,
  in the case that Ruby OpenSSL binding is compiled with LibreSSL. Note
  `test/openssl/utils.rb#libressl?` is not using this value in it for now.
* Update `rake debug` to print the values in a readable way, adding
  `OpenSSL::OPENSSL_VERSION_NUMBER` and `OpenSSL::LIBRESSL_VERSION_NUMBER`.

https://github.com/ruby/openssl/commit/d19e6360ed

Error entries in the OpenSSL error queue may contain additional
contextual information associated with the error, which can be helpful
when debugging.

This "additional data" is currently only printed to stderr when
OpenSSL.debug is enabled. Let's include this in the exception messages
raised with ossl_raise(), too.

	$ ruby -Ilib -ropenssl -e'OpenSSL.debug=true; OpenSSL::SSL::SSLContext.new.ecdh_curves="P-256:not-a-curve"'
	-e:1: warning: error on stack: error:0A080106:SSL routines:gid_cb:passed invalid argument (group 'not-a-curve' cannot be set)
	-e:1:in `ecdh_curves=': passed invalid argument (group 'not-a-curve' cannot be set) (OpenSSL::SSL::SSLError)
		from -e:1:in `<main>'

https://github.com/ruby/openssl/commit/1c5bbdd68e

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".

https://github.com/ruby/openssl/commit/56312038d6

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".

https://github.com/ruby/openssl/commit/06d67640e9

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