diff --git a/README.md b/README.md index a23135ee4..b57758b2a 100644 --- a/README.md +++ b/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 diff --git a/openssl.gemspec b/openssl.gemspec index 674dc20de..c194b5049 100644 --- a/openssl.gemspec +++ b/openssl.gemspec @@ -3,8 +3,8 @@ Gem::Specification.new do |spec| spec.version = "3.1.0" spec.authors = ["Martin Bosslet", "SHIBATA Hiroshi", "Zachary Scott", "Kazuki Yamaguchi"] spec.email = ["ruby-core@ruby-lang.org"] - spec.summary = %q{OpenSSL provides SSL, TLS and general purpose cryptography.} - spec.description = %q{It wraps the OpenSSL library.} + spec.summary = %q{SSL/TLS and general-purpose cryptography for Ruby} + spec.description = %q{OpenSSL for Ruby provides access to SSL/TLS and general-purpose cryptography based on the OpenSSL library.} spec.homepage = "https://github.com/ruby/openssl" spec.license = "Ruby"