repository·master·Indexed 43 days ago
https://github.com/ruby/opensslA bridge between Ruby applications and OpenSSL, LibreSSL, or AWS-LC cryptographic libraries. Provides access to SSL/TLS and general-purpose cryptography, including symmetric encryption via OpenSSL::Cipher, hashing with OpenSSL::Digest, HMAC generation, and public-key cryptography (RSA, DSA, DH, EC) via OpenSSL::PKey.
The openssl gem is included with Ruby by default. If you need to upgrade to a newer version available on RubyGems, use the gem install command. If your OpenSSL library is installed in a non-standard location, you must specify the path using the --with-openssl-dir flag.
# Upgrade the gem
gem install openssl
# Install specifying a custom OpenSSL library path
gem install openssl -- --with-openssl-dir=/opt/opensslYou can manage the openssl gem using Bundler. You can either use the version from RubyGems or point directly to the git master branch.
# Gemfile
gem 'openssl'
# or specify git master
gem 'openssl', git: 'https://github.com/ruby/openssl'OpenSSL::BN class provides a Ruby interface for OpenSSL's Big Number (BN) functions. It includes the Comparable module, allowing you to use standard comparison operators (like <, >, ==) between BN objects. For detailed information on the underlying mathematical operations available, refer to the OpenSSL manual (man bn).An OpenSSL::SSL::SSLContext object holds the configuration for SSL/TLS connections, such as protocol versions, ciphers, and certificate verification settings.
Initialization
You can initialize a context with a specific version (e.g., :TLSv1, `
OpenSSL::PKCS5.pbkdf2_hmac_sha1 method is a convenience wrapper that calls pbkdf2_hmac using `OpenSSL for Ruby is a default gem. Its support lifecycle is tied to supported Ruby branches. Use the following table to determine compatibility between the gem version, the minimum Ruby version required, and the supported OpenSSL/LibreSSL/AWS-LC versions.
|Version|Minimum Ruby|OpenSSL compatibility |Bundled with|Maintenance |
|-------|------------|-----------------------------------------|------------|-------------|
|4.0.x |Ruby 2.7 |OpenSSL 1.1.1-4.x, LibreSSL 3.9+, AWS-LC |Ruby 4.0 |bug fixes |
|3.3.x |Ruby 2.7 |OpenSSL 1.0.2-4.x, LibreSSL 3.1+ |Ruby 3.4 |bug fixes |
|3.2.x |Ruby 2.7 |OpenSSL 1.0.2-4.x, LibreSSL 3.1+ |Ruby 3.3 |bug fixes |
|3.1.x |Ruby 2.6 |OpenSSL 1.0.2-3.x, LibreSSL 3.1+ |Ruby 3.2 |security only|
|3.0.x |Ruby 2.6 |OpenSSL 1.0.2-3.x, LibreSSL 3.1+ |Ruby 3.1 |end-of-life |
|2.2.x |Ruby 2.3 |OpenSSL 1.0.1-1.1.1, LibreSSL 2.9+ |Ruby 3.0 |end-of-life |
|2.1.x |Ruby 2.3 |OpenSSL 1.0.1-1.1.1, LibreSSL 2.5+ |Ruby 2.5-2.7|end-of-life |
|2.0.x |Ruby 2.3 |OpenSSL 0.9.8-1.1.1, LibreSSL 2.3+ |Ruby 2.4 |end-of-life |To access SSL/TLS and general-purpose cryptography features, require the library at the start of your application.
require "openssl"Use OpenSSL::X509::Certificate.load_file(path) to read a certificate directly from a file path.
cert = OpenSSL::X509::Certificate.load_file("/path/to/cert.pem")The OpenSSL::Cipher class provides several predefined subclasses for common symmetric encryption algorithms. These subclasses allow you to initialize a cipher with a specific algorithm and key length by name.
Commonly available algorithm constants include:
OpenSSL::Cipher::AES128, OpenSSL::Cipher::AES192, OpenSSL::Cipher::AES256 (which default to CBC mode)OpenSSL::Cipher::AES128 (and others) can be initialized with a specific mode, e.g., OpenSSL::Cipher::AES128.new('CFB').OpenSSL::Cipher::AES, OpenSSL::Cipher::CAST5, OpenSSL::Cipher::BF, OpenSSL::Cipher::DES, OpenSSL::Cipher::IDEA, OpenSSL::Cipher::RC2, OpenSSL::Cipher::RC4, OpenSSL::Cipher::RC5.# Example: Using a predefined AES-256 CBC cipher
cipher = OpenSSL::Cipher::AES256.new
# Example: Using a general algorithm constant with a specific mode
cipher = OpenSSL::Cipher::AES.new('CFB')Use OpenSSL::HMAC.base64digest to return the authentication code as a Base64-encoded string. The digest parameter can be a String representing the algorithm name or an instance of OpenSSL::Digest.
key = 'key'
data = 'The quick brown fox jumps over the lazy dog'
hmac = OpenSSL::HMAC.base64digest('SHA1', key, data)
#=> "3nybhbi3iqa8ino29wqQcBydtNk="The OpenSSL::X509::ExtensionFactory class allows you to create X.509 extensions. The create_extension method is polymorphic and can accept different input types to generate extensions:
create_extension([oid, value, critical])create_extension("oid = critical, value")create_extension({"oid" => "...", "value" => "...", "critical" => true})If multiple arguments are passed directly to create_extension, it delegates to create_ext.
factory = OpenSSL::X509::ExtensionFactory.new
# Using a hash
ext1 = factory.create_extension({"oid" => "subjectKeyIdentifier", "value" => "...", "critical" => false})
# Using a string
ext2 = factory.create_extension("subjectKeyIdentifier = critical, value")The methods DSA#syssign and DSA#sysverify are deprecated as of version 3.0. They are provided for backwards compatibility and expect a pre-computed message digest as input.
Recommended approach: Use PKey#sign_raw and PKey#verify_raw instead.
# DEPRECATED USAGE
digest = OpenSSL::Digest.digest('SHA1', "Sign me")
sig = dsa.syssign(digest)
valid = dsa.sysverify(digest, sig)
# RECOMMENDED USAGE
sig = dsa.sign_raw(nil, digest)
valid = dsa.verify_raw(nil, sig, digest)