openssl 2.2.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f52e266d6038d1d7173a58d9ad72207e7d492da086ef0ecf9484a8b1cac5156
-  data.tar.gz: ca3211e0c3887311a9d0ac997c864e0cdd54fc0c7510d04c2497c9c99b97fd0c
+  metadata.gz: 5040b959a35f5692d6d19e2bf520e1123da8133fff2f878cfc21c2ff0f145d6e
+  data.tar.gz: dfee6ebd76e423511aa0fc4630f8120edce8fe79d4f40ee7105ccad12c2d3340
 SHA512:
-  metadata.gz: b20ff54093b47c1d1da2f90a41ee1787bcd6a3e14c26f86f4c117d5ec6703364c73df226da5bf357ec6440770b639dd92575e468caeaf38fd8815ef52fb9864f
-  data.tar.gz: 6f64e438c1cc74cea40674a4d3d5926ecc3ea4a0701dd02514f990fcbcb8c525a364789f832ac649fe65e557522a9df983e5beca5f3476b3ec29f7a82b15f071
+  metadata.gz: f542ec360be844382829f4bcc46b5cffdfcaf675b02ecdc1cd15a6e80c061476ee4582fdb201ef2dd0f430806d74036233eef3a5c23e5b4028560ad075ed706b
+  data.tar.gz: 0173033ebe6efb76b747cc80835cc9530dd664d038256bbdf963d4940b5f3bfad90be313554f548a911ac0977d4bdc33c088dfd3b6fb8e46db7bcd5d2ec34a8c

data/CONTRIBUTING.md

@@ -12,16 +12,17 @@ If you think you found a bug, file a ticket on GitHub. Please DO NOT report
 security issues here, there is a separate procedure which is described on
 ["Security at ruby-lang.org"](https://www.ruby-lang.org/en/security/).
 
-When reporting a bug, please make sure you include: 
-* Ruby version 
-* OpenSSL gem version
-* OpenSSL library version 
-* A sample file that illustrates the problem or link to the repository or 
+When reporting a bug, please make sure you include:
+
+* Ruby version (`ruby -v`)
+* `openssl` gem version (`gem list openssl` and `OpenSSL::VERSION`)
+* OpenSSL library version (`OpenSSL::OPENSSL_VERSION`)
+* A sample file that illustrates the problem or link to the repository or
   gem that is associated with the bug.
 
 There are a number of unresolved issues and feature requests for openssl that
 need review. Before submitting a new ticket, it is recommended to check
-[known issues] and [bugs.ruby-lang.org], the previous issue tracker.
+[known issues].
 
 ## Submitting patches
 
@@ -34,62 +35,50 @@ Make sure that your branch does:
 * Have good commit messages
 * Follow Ruby's coding style ([DeveloperHowTo])
 * Pass the test suite successfully (see "Testing")
-* Add an entry to [History.md] if necessary
 
 ## Testing
 
 We have a test suite!
 
 Test cases are located under the
-[`test/`](https://github.com/ruby/openssl/tree/master/test) directory.
+[`test/openssl`](https://github.com/ruby/openssl/tree/master/test/openssl)
+directory.
 
 You can run it with the following three commands:
 
 ```
-$ rake install_dependencies # installs rake-compiler, test-unit, ...
-$ rake compile
-$ rake test
+$ bundle install # installs rake-compiler, test-unit, ...
+$ bundle exec rake compile
+$ bundle exec rake test
 ```
 
-### Docker
-
-You can also use Docker Compose to run tests. It can be used to check that your
-changes work correctly with various supported versions of Ruby and OpenSSL.
-
-First, you need to install [Docker](https://www.docker.com/products/docker) and
-[Docker Compose](https://www.docker.com/products/docker-compose) on your
-computer.
+### With different versions of OpenSSL
 
-If you're on MacOS or Windows, we recommended to use the official [Docker
-Toolbox](https://www.docker.com/products/docker-toolbox). On Linux, follow the
-instructions for your package manager. For further information, please check
-the [official documentation](https://docs.docker.com/).
+Ruby OpenSSL supports various versions of OpenSSL library. The test suite needs
+to pass on all supported combinations.
 
-Once you have Docker and Docker Compose, running the following commands will
-build the container and execute the openssl tests. In this example, we will use
-Ruby version 2.3 with OpenSSL version 1.0.2.
+Similarly to when installing `openssl` gem via the `gem` command,
+you can pass a `--with-openssl-dir` argument to `rake compile`
+to specify the OpenSSL library to build against.
 
 ```
-$ docker-compose build
-$ export RUBY_VERSION=ruby-2.3
-$ export OPENSSL_VERSION=openssl-1.0.2
-$ docker-compose run test
-
-# You may want an interactive shell for dubugging
-$ docker-compose run debug
+$ ( curl -OL https://ftp.openssl.org/source/openssl-3.0.1.tar.gz &&
+    tar xf openssl-3.0.1.tar.gz &&
+    cd openssl-3.0.1 &&
+    ./config --prefix=$HOME/.openssl/openssl-3.0.1 --libdir=lib &&
+    make -j4 &&
+    make install )
+
+$ # in Ruby/OpenSSL's source directory
+$ bundle exec rake clean
+$ bundle exec rake compile -- --with-openssl-dir=$HOME/.openssl/openssl-3.0.1
+$ bundle exec rake test
 ```
 
-All possible values for `RUBY_VERSION` and `OPENSSL_VERSION` can be found in
-[`test.yml`](https://github.com/ruby/openssl/tree/master/.github/workflows/test.yml).
-
-**NOTE**: these commands must be run from the openssl repository root, in order
-to use the
-[`docker-compose.yml`](https://github.com/ruby/openssl/blob/master/docker-compose.yml)
-file we have provided.
-
-This Docker image is built using the
-[Dockerfile](https://github.com/ruby/openssl/tree/master/tool/ruby-openssl-docker)
-provided in the repository.
+The GitHub Actions workflow file
+[`test.yml`](https://github.com/ruby/openssl/tree/master/.github/workflows/test.yml)
+contains useful information for building OpenSSL/LibreSSL and testing against
+them.
 
 
 ## Relation with Ruby source tree
@@ -124,7 +113,6 @@ _Thanks for your contributions!_
 
 [GitHub]: https://github.com/ruby/openssl
 [known issues]: https://github.com/ruby/openssl/issues
-[bugs.ruby-lang.org]: https://bugs.ruby-lang.org/issues?utf8=%E2%9C%93&set_filter=1&f%5B%5D=status_id&op%5Bstatus_id%5D=o&f%5B%5D=assigned_to_id&op%5Bassigned_to_id%5D=%3D&v%5Bassigned_to_id%5D%5B%5D=7150&f%5B%5D=&c%5B%5D=project&c%5B%5D=tracker&c%5B%5D=status&c%5B%5D=subject&c%5B%5D=assigned_to&c%5B%5D=updated_on&group_by=&t%5B%5D=
 [DeveloperHowTo]: https://bugs.ruby-lang.org/projects/ruby/wiki/DeveloperHowto
 [HackerOne]: https://hackerone.com/ruby
 [Security]: https://www.ruby-lang.org/en/security/

data/History.md

@@ -1,3 +1,257 @@
+Version 3.2.0
+=============
+
+Compatibility
+-------------
+
+* Ruby >= 2.7
+  - Support for Ruby 2.6 has been removed. Note that Ruby 2.6 reached the
+    end-of-life in 2022-04.
+    [[GitHub #639]](https://github.com/ruby/openssl/pull/639)
+* OpenSSL >= 1.0.2 or LibreSSL >= 3.1
+
+Notable changes
+---------------
+
+* Add a stub gemspec for JRuby, which depends on the `jruby-openssl` gem.
+  [[GitHub #598]](https://github.com/ruby/openssl/pull/598)
+* Add support for the FIPS module in OpenSSL 3.0/3.1.
+  [[GitHub #608]](https://github.com/ruby/openssl/pull/608)
+* Rework `OpenSSL::PKey` routines for loading DER or PEM encoded keys for better
+  compatibility with OpenSSL 3.0/3.1 with the FIPS module.
+  [[GitHub #615]](https://github.com/ruby/openssl/pull/615)
+  [[GitHub #669]](https://github.com/ruby/openssl/pull/669)
+* Add `OpenSSL::Provider` module for loading and unloading OpenSSL 3 providers.
+  [[GitHub #635]](https://github.com/ruby/openssl/pull/635)
+* Add `OpenSSL::PKey.new_raw_private_key`, `.new_raw_public_key`,
+  `OpenSSL::PKey::PKey#raw_private_key`, and `#raw_public_key` for public key
+  algorithms that use "raw private/public key", such as X25519 and Ed25519.
+  [[GitHub #646]](https://github.com/ruby/openssl/pull/646)
+* Improve OpenSSL error messages to include additional information when
+  it is available in OpenSSL's error queue.
+  [[GitHub #648]](https://github.com/ruby/openssl/pull/648)
+* Change `OpenSSL::SSL::SSLContext#ca_file=` and `#ca_path=` to raise
+  `OpenSSL::SSL::SSLError` instead of printing a warning message.
+  [[GitHub #659]](https://github.com/ruby/openssl/pull/659)
+* Allow `OpenSSL::X509::ExtensionFactory#create_extension` to take OIDs in the
+  dotted-decimal notation.
+  [[GitHub #141]](https://github.com/ruby/openssl/pull/141)
+
+
+Version 3.1.0
+=============
+
+Ruby/OpenSSL 3.1 will be maintained for the lifetime of Ruby 3.2.
+
+Merged bug fixes in 2.2.3 and 3.0.2. Among the new features and changes are:
+
+Notable changes
+---------------
+
+* Add `OpenSSL::SSL::SSLContext#ciphersuites=` to allow setting TLS 1.3 cipher
+  suites.
+  [[GitHub #493]](https://github.com/ruby/openssl/pull/493)
+* Add `OpenSSL::SSL::SSLSocket#export_keying_material` for exporting keying
+  material of the session, as defined in RFC 5705.
+  [[GitHub #530]](https://github.com/ruby/openssl/pull/530)
+* Add `OpenSSL::SSL::SSLContext#keylog_cb=` for setting the TLS key logging
+  callback, which is useful for supporting NSS's SSLKEYLOGFILE debugging output.
+  [[GitHub #536]](https://github.com/ruby/openssl/pull/536)
+* Remove the default digest algorithm from `OpenSSL::OCSP::BasicResponse#sign`
+  and `OpenSSL::OCSP::Request#sign`. Omitting the 5th parameter of these
+  methods used to be equivalent of specifying SHA-1. This default value is now
+  removed and we will let the underlying OpenSSL library decide instead.
+  [[GitHub #507]](https://github.com/ruby/openssl/pull/507)
+* Add `OpenSSL::BN#mod_sqrt`.
+  [[GitHub #553]](https://github.com/ruby/openssl/pull/553)
+* Allow calling `OpenSSL::Cipher#update` with an empty string. This was
+  prohibited to workaround an ancient bug in OpenSSL.
+  [[GitHub #568]](https://github.com/ruby/openssl/pull/568)
+* Fix build on platforms without socket support, such as WASI. `OpenSSL::SSL`
+  will not be defined if OpenSSL is compiled with `OPENSSL_NO_SOCK`.
+  [[GitHub #558]](https://github.com/ruby/openssl/pull/558)
+* Improve support for recent LibreSSL versions. This includes HKDF support in
+  LibreSSL 3.6 and Ed25519 support in LibreSSL 3.7.
+
+
+Version 3.0.2
+=============
+
+Merged changes in 2.2.3. Additionally, the following issues are fixed by this
+release.
+
+Bug fixes
+---------
+
+* Fix OpenSSL::PKey::EC#check_key not working correctly on OpenSSL 3.0.
+  [[GitHub #563]](https://github.com/ruby/openssl/issues/563)
+  [[GitHub #580]](https://github.com/ruby/openssl/pull/580)
+
+
+Version 3.0.1
+=============
+
+Merged changes in 2.1.4 and 2.2.2. Additionally, the following issues are fixed
+by this release.
+
+Bug fixes
+---------
+
+* Add missing type check in OpenSSL::PKey::PKey#sign's optional parameters.
+  [[GitHub #531]](https://github.com/ruby/openssl/pull/531)
+* Work around OpenSSL 3.0's HMAC issues with a zero-length key.
+  [[GitHub #538]](https://github.com/ruby/openssl/pull/538)
+* Fix a regression in OpenSSL::PKey::DSA.generate's default of 'q' size.
+  [[GitHub #483]](https://github.com/ruby/openssl/issues/483)
+  [[GitHub #539]](https://github.com/ruby/openssl/pull/539)
+* Restore OpenSSL::PKey.read's ability to decode "openssl ecparam -genkey"
+  output when linked against OpenSSL 3.0.
+  [[GitHub #535]](https://github.com/ruby/openssl/pull/535)
+  [[GitHub #540]](https://github.com/ruby/openssl/pull/540)
+* Restore error checks in OpenSSL::PKey::EC#{to_der,to_pem}.
+  [[GitHub #541]](https://github.com/ruby/openssl/pull/541)
+
+
+Version 3.0.0
+=============
+
+Compatibility notes
+-------------------
+
+* OpenSSL 1.0.1 and Ruby 2.3-2.5 are no longer supported.
+  [[GitHub #396]](https://github.com/ruby/openssl/pull/396)
+  [[GitHub #466]](https://github.com/ruby/openssl/pull/466)
+
+* OpenSSL 3.0 support is added. It is the first major version bump from OpenSSL
+  1.1 and contains incompatible changes that affect Ruby/OpenSSL.
+  Note that OpenSSL 3.0 support is preliminary and not all features are
+  currently available:
+  [[GitHub #369]](https://github.com/ruby/openssl/issues/369)
+
+  - Deprecate the ability to modify `OpenSSL::PKey::PKey` instances. OpenSSL 3.0
+    made EVP_PKEY structure immutable, and hence the following methods are not
+    available when Ruby/OpenSSL is linked against OpenSSL 3.0.
+    [[GitHub #480]](https://github.com/ruby/openssl/pull/480)
+
+    - `OpenSSL::PKey::RSA#set_key`, `#set_factors`, `#set_crt_params`
+    - `OpenSSL::PKey::DSA#set_pqg`, `#set_key`
+    - `OpenSSL::PKey::DH#set_pqg`, `#set_key`, `#generate_key!`
+    - `OpenSSL::PKey::EC#private_key=`, `#public_key=`, `#group=`, `#generate_key!`
+
+  - Deprecate `OpenSSL::Engine`. The ENGINE API has been deprecated in OpenSSL 3.0
+    in favor of the new "provider" concept and will be removed in a future
+    version.
+    [[GitHub #481]](https://github.com/ruby/openssl/pull/481)
+
+* `OpenSSL::SSL::SSLContext#tmp_ecdh_callback` has been removed. It has been
+  deprecated since v2.0.0 because it is incompatible with modern OpenSSL
+  versions.
+  [[GitHub #394]](https://github.com/ruby/openssl/pull/394)
+
+* `OpenSSL::SSL::SSLSocket#read` and `#write` now raise `OpenSSL::SSL::SSLError`
+  if called before a TLS connection is established. Historically, they
+  read/wrote unencrypted data to the underlying socket directly in that case.
+  [[GitHub #9]](https://github.com/ruby/openssl/issues/9)
+  [[GitHub #469]](https://github.com/ruby/openssl/pull/469)
+
+
+Notable changes
+---------------
+
+* Enhance OpenSSL::PKey's common interface.
+  [[GitHub #370]](https://github.com/ruby/openssl/issues/370)
+
+  - Key deserialization: Enhance `OpenSSL::PKey.read` to handle PEM encoding of
+    DH parameters, which used to be only deserialized by `OpenSSL::PKey::DH.new`.
+    [[GitHub #328]](https://github.com/ruby/openssl/issues/328)
+  - Key generation: Add `OpenSSL::PKey.generate_parameters` and
+    `OpenSSL::PKey.generate_key`.
+    [[GitHub #329]](https://github.com/ruby/openssl/issues/329)
+  - Public key signing: Enhance `OpenSSL::PKey::PKey#sign` and `#verify` to use
+    the new EVP_DigestSign() family to enable PureEdDSA support on OpenSSL 1.1.1
+    or later. They also now take optional algorithm-specific parameters for more
+    control.
+    [[GitHub #329]](https://github.com/ruby/openssl/issues/329)
+  - Low-level public key signing and verification: Add
+    `OpenSSL::PKey::PKey#sign_raw`, `#verify_raw`, and `#verify_recover`.
+    [[GitHub #382]](https://github.com/ruby/openssl/issues/382)
+  - Public key encryption: Add `OpenSSL::PKey::PKey#encrypt` and `#decrypt`.
+    [[GitHub #382]](https://github.com/ruby/openssl/issues/382)
+  - Key agreement: Add `OpenSSL::PKey::PKey#derive`.
+    [[GitHub #329]](https://github.com/ruby/openssl/issues/329)
+  - Key comparison: Add `OpenSSL::PKey::PKey#compare?` to conveniently check
+    that two keys have common parameters and a public key.
+    [[GitHub #383]](https://github.com/ruby/openssl/issues/383)
+
+* Add `OpenSSL::BN#set_flags` and `#get_flags`. This can be used in combination
+  with `OpenSSL::BN::CONSTTIME` to force constant-time computation.
+  [[GitHub #417]](https://github.com/ruby/openssl/issues/417)
+
+* Add `OpenSSL::BN#abs` to get the absolute value of the BIGNUM.
+  [[GitHub #430]](https://github.com/ruby/openssl/issues/430)
+
+* Add `OpenSSL::SSL::SSLSocket#getbyte`.
+  [[GitHub #438]](https://github.com/ruby/openssl/issues/438)
+
+* Add `OpenSSL::SSL::SSLContext#tmp_dh=`.
+  [[GitHub #459]](https://github.com/ruby/openssl/pull/459)
+
+* Add `OpenSSL::X509::Certificate.load` to load a PEM-encoded and concatenated
+  list of X.509 certificates at once.
+  [[GitHub #441]](https://github.com/ruby/openssl/pull/441)
+
+* Change `OpenSSL::X509::Certificate.new` to attempt to deserialize the given
+  string first as DER encoding first and then as PEM encoding to ensure the
+  round-trip consistency.
+  [[GitHub #442]](https://github.com/ruby/openssl/pull/442)
+
+* Update various part of the code base to use the modern API. No breaking
+  changes are intended with this. This includes:
+
+  - `OpenSSL::HMAC` uses the EVP API.
+    [[GitHub #371]](https://github.com/ruby/openssl/issues/371)
+  - `OpenSSL::Config` uses native OpenSSL API to parse config files.
+    [[GitHub #342]](https://github.com/ruby/openssl/issues/342)
+
+
+Version 2.2.3
+=============
+
+Bug fixes
+---------
+
+* Fix serveral methods in OpenSSL::PKey::EC::Point attempting to raise an error
+  with an incorrect class, which would end up with a TypeError.
+  [[GitHub #570]](https://github.com/ruby/openssl/pull/570)
+* Fix OpenSSL::PKey::EC::Point#eql? and OpenSSL::PKey::EC::Group#eql?
+  incorrectly treated OpenSSL's internal errors as "not equal".
+  [[GitHub #564]](https://github.com/ruby/openssl/pull/564)
+* Fix build with LibreSSL 3.5 or later.
+
+
+Version 2.2.2
+=============
+
+Merged changes in 2.1.4.
+
+
+Version 2.2.1
+=============
+
+Merged changes in 2.1.3. Additionally, the following issues are fixed by this
+release.
+
+Bug fixes
+---------
+
+* Fix crash in `OpenSSL::Timestamp::{Request,Response,TokenInfo}.new` when
+  invalid arguments are given.
+  [[GitHub #407]](https://github.com/ruby/openssl/pull/407)
+* Fix `OpenSSL::Timestamp::Factory#create_timestamp` with LibreSSL on platforms
+  where `time_t` has a different size from `long`.
+  [[GitHub #454]](https://github.com/ruby/openssl/pull/454)
+
+
 Version 2.2.0
 =============
 
@@ -75,6 +329,52 @@ Notable changes
   [[GitHub #297]](https://github.com/ruby/openssl/pull/297)
 
 
+Version 2.1.4
+=============
+
+Bug fixes
+---------
+
+* Do not use pkg-config if --with-openssl-dir option is specified.
+ [[GitHub #486]](https://github.com/ruby/openssl/pull/486)
+
+
+Version 2.1.3
+=============
+
+Bug fixes
+---------
+
+* Fix deprecation warnings on Ruby 3.0.
+* Add ".include" directive support in `OpenSSL::Config`.
+  [[GitHub #216]](https://github.com/ruby/openssl/pull/216)
+* Fix handling of IPv6 address SANs.
+  [[GitHub #185]](https://github.com/ruby/openssl/pull/185)
+* Hostname verification failure with `OpenSSL::SSL::SSLContext#verify_hostname=`
+  sets a proper error code.
+  [[GitHub #350]](https://github.com/ruby/openssl/pull/350)
+* Fix crash with `OpenSSL::BN.new(nil, 2)`.
+  [[Bug #15760]](https://bugs.ruby-lang.org/issues/15760)
+* `OpenSSL::SSL::SSLSocket#sys{read,write}` prevent internal string buffers from
+  being modified by another thread.
+  [[GitHub #453]](https://github.com/ruby/openssl/pull/453)
+* Fix misuse of input record separator in `OpenSSL::Buffering` where it was
+  for output.
+* Fix wrong integer casting in `OpenSSL::PKey::EC#dsa_verify_asn1`.
+  [[GitHub #460]](https://github.com/ruby/openssl/pull/460)
+* `extconf.rb` explicitly checks that OpenSSL's version number is 1.0.1 or
+  newer but also less than 3.0. Ruby/OpenSSL v2.1.x and v2.2.x will not support
+  OpenSSL 3.0 API.
+  [[GitHub #458]](https://github.com/ruby/openssl/pull/458)
+* Activate `digest` gem correctly. `digest` library could go into an
+  inconsistent state if there are multiple versions of `digest` is installed
+  and `openssl` is `require`d before `digest`.
+  [[GitHub #463]](https://github.com/ruby/openssl/pull/463)
+* Fix GC.compact compatibility.
+  [[GitHub #464]](https://github.com/ruby/openssl/issues/464)
+  [[GitHub #465]](https://github.com/ruby/openssl/pull/465)
+
+
 Version 2.1.2
 =============
 

data/README.md

@@ -2,26 +2,53 @@
 
 [![Actions Status](https://github.com/ruby/openssl/workflows/CI/badge.svg)](https://github.com/ruby/openssl/actions?workflow=CI)
 
+**OpenSSL for Ruby** provides access to SSL/TLS and general-purpose
+cryptography based on the OpenSSL library.
 
-OpenSSL provides SSL, TLS and general purpose cryptography. It wraps the
-OpenSSL library.
+OpenSSL for Ruby is sometimes referred to as **openssl** in all lowercase
+or **Ruby/OpenSSL** for disambiguation.
+
+## Compatibility and maintenance policy
+
+OpenSSL for Ruby is released as a RubyGems gem. At the same time, it is part of
+the standard library of Ruby. This is called a [default gem].
+
+Each stable branch of OpenSSL for Ruby will remain supported as long as it is
+included as a default gem in [supported Ruby branches][Ruby Maintenance Branches].
+
+|Version|Maintenance status             |Ruby compatibility|OpenSSL compatibility                       |
+|-------|-------------------------------|------------------|--------------------------------------------|
+|3.2.x  |normal maintenance (Ruby 3.3)  |Ruby 2.7+         |OpenSSL 1.0.2-3.1 (current) or LibreSSL 3.1+|
+|3.1.x  |normal maintenance (Ruby 3.2)  |Ruby 2.6+         |OpenSSL 1.0.2-3.1 (current) or LibreSSL 3.1+|
+|3.0.x  |normal maintenance (Ruby 3.1)  |Ruby 2.6+         |OpenSSL 1.0.2-3.1 (current) or LibreSSL 3.1+|
+|2.2.x  |security maintenance (Ruby 3.0)|Ruby 2.3+         |OpenSSL 1.0.1-1.1.1 or LibreSSL 2.9+        |
+|2.1.x  |end-of-life (Ruby 2.5-2.7)     |Ruby 2.3+         |OpenSSL 1.0.1-1.1.1 or LibreSSL 2.5+        |
+|2.0.x  |end-of-life (Ruby 2.4)         |Ruby 2.3+         |OpenSSL 0.9.8-1.1.1 or LibreSSL 2.3+        |
+
+[default gem]: https://docs.ruby-lang.org/en/master/standard_library_rdoc.html
+[Ruby Maintenance Branches]: https://www.ruby-lang.org/en/downloads/branches/
 
 ## Installation
 
-The openssl gem is available at [rubygems.org](https://rubygems.org/gems/openssl).
-You can install with:
+> **Note**
+> The openssl gem is included with Ruby by default, but you may wish to upgrade
+> it to a newer version available at
+> [rubygems.org](https://rubygems.org/gems/openssl).
+
+To upgrade it, you can use RubyGems:
 
 ```
 gem install openssl
 ```
 
-You may need to specify the path where OpenSSL is installed.
+In some cases, it may be necessary to specify the path to the installation
+directory of the OpenSSL library.
 
 ```
 gem install openssl -- --with-openssl-dir=/opt/openssl
 ```
 
-Alternatively, you can install the gem with `bundler`:
+Alternatively, you can install the gem with Bundler:
 
 ```ruby
 # Gemfile
@@ -30,7 +57,7 @@ gem 'openssl'
 gem 'openssl', git: 'https://github.com/ruby/openssl'
 ```
 
-After doing `bundle install`, you should have the gem installed in your bundle.
+After running `bundle install`, you should have the gem installed in your bundle.
 
 ## Usage
 
@@ -40,15 +67,6 @@ Once installed, you can require "openssl" in your application.
 require "openssl"
 ```
 
-**NOTE**: If you are using Ruby 2.3 (and not Bundler), you **must** activate
-the gem version of openssl, otherwise the default gem packaged with the Ruby
-installation will be used:
-
-```ruby
-gem "openssl"
-require "openssl"
-```
-
 ## Documentation
 
 See https://ruby.github.io/openssl/.
@@ -57,10 +75,9 @@ See https://ruby.github.io/openssl/.
 
 Please read our [CONTRIBUTING.md] for instructions.
 
+[CONTRIBUTING.md]: https://github.com/ruby/openssl/tree/master/CONTRIBUTING.md
+
 ## Security
 
 Security issues should be reported to ruby-core by following the process
 described on ["Security at ruby-lang.org"](https://www.ruby-lang.org/en/security/).
-
-
-[CONTRIBUTING.md]: https://github.com/ruby/openssl/tree/master/CONTRIBUTING.md