class OpenSSL::SSL::SSLContext

Creates a new SSL context.

If an argument is given, ssl_version= is called with the value. Note that this form is deprecated. New applications should use min_version= and

max_version= as necessary.

Adds a certificate to the context. pkey must be a corresponding private key with certificate.

Multiple certificates with different public key type can be added by repeated calls of this method, and OpenSSL will choose the most appropriate certificate during the handshake.

cert=, key=, and extra_chain_cert= are old accessor methods for setting certificate and internally call this method.

Parameters

certificate

A certificate. An instance of OpenSSL::X509::Certificate.

pkey

The private key for certificate. An instance of OpenSSL::PKey::PKey.

extra_certs

Optional. An array of OpenSSL::X509::Certificate. When sending a certificate chain, the certificates specified by this are sent following certificate, in the order in the array.

Example

rsa_cert = OpenSSL::X509::Certificate.new(...)
rsa_pkey = OpenSSL::PKey.read(...)
ca_intermediate_cert = OpenSSL::X509::Certificate.new(...)
ctx.add_certificate(rsa_cert, rsa_pkey, [ca_intermediate_cert])

ecdsa_cert = ...
ecdsa_pkey = ...
another_ca_cert = ...
ctx.add_certificate(ecdsa_cert, ecdsa_pkey, [another_ca_cert])

An Enumerable of Strings. Each String represents a protocol to be advertised as the list of supported protocols for Application-Layer Protocol Negotiation. Supported in OpenSSL 1.0.2 and higher. Has no effect on the server side. If not set explicitly, the ALPN extension will not be included in the handshake.

Example

ctx.alpn_protocols = ["http/1.1", "spdy/2", "h2"]

An Enumerable of Strings. Each String represents a protocol to be advertised as the list of supported protocols for Application-Layer Protocol Negotiation. Supported in OpenSSL 1.0.2 and higher. Has no effect on the server side. If not set explicitly, the ALPN extension will not be included in the handshake.

Example

ctx.alpn_protocols = ["http/1.1", "spdy/2", "h2"]

A callback invoked on the server side when the server needs to select a protocol from the list sent by the client. Supported in OpenSSL 1.0.2 and higher. The callback must return a protocol of those advertised by the client. If none is acceptable, raising an error in the callback will cause the handshake to fail. Not setting this callback explicitly means not supporting the ALPN extension on the server - any protocols advertised by the client will be ignored.

Example

ctx.alpn_select_cb = lambda do |protocols|
  # inspect the protocols and select one
  protocols.first
end

A callback invoked on the server side when the server needs to select a protocol from the list sent by the client. Supported in OpenSSL 1.0.2 and higher. The callback must return a protocol of those advertised by the client. If none is acceptable, raising an error in the callback will cause the handshake to fail. Not setting this callback explicitly means not supporting the ALPN extension on the server - any protocols advertised by the client will be ignored.

Example

ctx.alpn_select_cb = lambda do |protocols|
  # inspect the protocols and select one
  protocols.first
end

The path to a file containing a PEM-format CA certificate

The path to a file containing a PEM-format CA certificate

The path to a directory containing CA certificates in PEM format.

Files are looked up by subject’s X509 name’s hash value.

The path to a directory containing CA certificates in PEM format.

Files are looked up by subject’s X509 name’s hash value.

Context certificate

The cert, key, and extra_chain_cert attributes are deprecated. It is recommended to use add_certificate instead.

Context certificate

The cert, key, and extra_chain_cert attributes are deprecated. It is recommended to use add_certificate instead.

An OpenSSL::X509::Store used for certificate verification.

An OpenSSL::X509::Store used for certificate verification.

The list of cipher suites configured for this context.

Sets the list of available cipher suites for TLS 1.2 and below for this context.

Note in a server context some ciphers require the appropriate certificates. For example, an RSA cipher suite can only be chosen when an RSA certificate is available.

This method does not affect TLS 1.3 connections. See also #ciphersuites=.

A certificate or Array of certificates that will be sent to the client.

A certificate or Array of certificates that will be sent to the client.

A callback invoked when a client certificate is requested by a server and no certificate has been set.

The callback is invoked with a Session and must return an Array containing an OpenSSL::X509::Certificate and an OpenSSL::PKey. If any other value is returned the handshake is suspended.

A callback invoked when a client certificate is requested by a server and no certificate has been set.

The callback is invoked with a Session and must return an Array containing an OpenSSL::X509::Certificate and an OpenSSL::PKey. If any other value is returned the handshake is suspended.

Sets the list of supported groups for key agreement for this context.

For a TLS client, the list is directly used in the “supported_groups” extension. For a server, the list is used by OpenSSL to determine the set of shared supported groups. OpenSSL will pick the most appropriate one from it.

ecdh_curves= is a deprecated alias for #groups=.

See also the man page SSL_CTX_set1_groups_list(3).

Example

ctx1 = OpenSSL::SSL::SSLContext.new
ctx1.groups = "X25519:P-256:P-224"
svr = OpenSSL::SSL::SSLServer.new(tcp_svr, ctx1)
Thread.new { svr.accept }

ctx2 = OpenSSL::SSL::SSLContext.new
ctx2.groups = "P-256"
cli = OpenSSL::SSL::SSLSocket.new(tcp_sock, ctx2)
cli.connect

p cli.tmp_key.group.curve_name
# => "prime256v1" (is an alias for NIST P-256)

Activate TLS_FALLBACK_SCSV for this context. See RFC 7507.

An Array of extra X509 certificates to be added to the certificate chain.

The cert, key, and extra_chain_cert attributes are deprecated. It is recommended to use add_certificate instead.

An Array of extra X509 certificates to be added to the certificate chain.

The cert, key, and extra_chain_cert attributes are deprecated. It is recommended to use add_certificate instead.

Removes sessions in the internal cache that have expired at time.

Context private key

The cert, key, and extra_chain_cert attributes are deprecated. It is recommended to use add_certificate instead.

Context private key

The cert, key, and extra_chain_cert attributes are deprecated. It is recommended to use add_certificate instead.

Sets the upper bound of the supported SSL/TLS protocol version. See

min_version= for the possible values.

Sets the lower bound on the supported SSL/TLS protocol version. The version may be specified by an integer constant named OpenSSL::SSL::*_VERSION, a Symbol, or nil which means “any version”.

Example

ctx = OpenSSL::SSL::SSLContext.new
ctx.min_version = OpenSSL::SSL::TLS1_1_VERSION
ctx.max_version = OpenSSL::SSL::TLS1_2_VERSION

sock = OpenSSL::SSL::SSLSocket.new(tcp_sock, ctx)
sock.connect # Initiates a connection using either TLS 1.1 or TLS 1.2

An Enumerable of Strings. Each String represents a protocol to be advertised as the list of supported protocols for Next Protocol Negotiation. Supported in OpenSSL 1.0.1 and higher. Has no effect on the client side. If not set explicitly, the NPN extension will not be sent by the server in the handshake.

Example

ctx.npn_protocols = ["http/1.1", "spdy/2"]

An Enumerable of Strings. Each String represents a protocol to be advertised as the list of supported protocols for Next Protocol Negotiation. Supported in OpenSSL 1.0.1 and higher. Has no effect on the client side. If not set explicitly, the NPN extension will not be sent by the server in the handshake.

Example

ctx.npn_protocols = ["http/1.1", "spdy/2"]

A callback invoked on the client side when the client needs to select a protocol from the list sent by the server. Supported in OpenSSL 1.0.1 and higher. The client MUST select a protocol of those advertised by the server. If none is acceptable, raising an error in the callback will cause the handshake to fail. Not setting this callback explicitly means not supporting the NPN extension on the client - any protocols advertised by the server will be ignored.

Example

ctx.npn_select_cb = lambda do |protocols|
  # inspect the protocols and select one
  protocols.first
end

A callback invoked on the client side when the client needs to select a protocol from the list sent by the server. Supported in OpenSSL 1.0.1 and higher. The client MUST select a protocol of those advertised by the server. If none is acceptable, raising an error in the callback will cause the handshake to fail. Not setting this callback explicitly means not supporting the NPN extension on the client - any protocols advertised by the server will be ignored.

Example

ctx.npn_select_cb = lambda do |protocols|
  # inspect the protocols and select one
  protocols.first
end

Gets various OpenSSL options.

Sets various OpenSSL options. The options are a bit field and can be combined with the bitwise OR operator (|). Available options are defined as constants in OpenSSL::SSL that begin with OP_.

For backwards compatibility, passing nil has the same effect as passing OpenSSL::SSL::OP_ALL.

See also man page SSL_CTX_set_options(3).

A callback invoked whenever a new handshake is initiated on an established connection. May be used to disable renegotiation entirely.

The callback is invoked with the active SSLSocket. The callback’s return value is ignored. A normal return indicates “approval” of the renegotiation and will continue the process. To forbid renegotiation and to cancel the process, raise an exception within the callback.

Disable client renegotiation

When running a server, it is often desirable to disable client renegotiation entirely. You may use a callback as follows to implement this feature:

ctx.renegotiation_cb = lambda do |ssl|
  raise RuntimeError, "Client renegotiation disabled"
end

A callback invoked whenever a new handshake is initiated on an established connection. May be used to disable renegotiation entirely.

The callback is invoked with the active SSLSocket. The callback’s return value is ignored. A normal return indicates “approval” of the renegotiation and will continue the process. To forbid renegotiation and to cancel the process, raise an exception within the callback.

Disable client renegotiation

When running a server, it is often desirable to disable client renegotiation entirely. You may use a callback as follows to implement this feature:

ctx.renegotiation_cb = lambda do |ssl|
  raise RuntimeError, "Client renegotiation disabled"
end

Returns the security level for the context.

See also OpenSSL::SSL::SSLContext#security_level=.

Sets the security level for the context. OpenSSL limits parameters according to the level. The “parameters” include: ciphersuites, curves, key sizes, certificate signature algorithms, protocol version and so on. For example, level 1 rejects parameters offering below 80 bits of security, such as ciphersuites using MD5 for the MAC or RSA keys shorter than 1024 bits.

Note that attempts to set such parameters with insufficient security are also blocked. You need to lower the level first.

This feature is not supported in OpenSSL < 1.1.0, and setting the level to other than 0 will raise NotImplementedError. Level 0 means everything is permitted, the same behavior as previous versions of OpenSSL.

See the manpage of SSL_CTX_set_security_level(3) for details.

A callback invoked at connect time to distinguish between multiple server names.

The callback is invoked with an SSLSocket and a server name. The callback must return an SSLContext for the server name or nil.

A callback invoked at connect time to distinguish between multiple server names.

The callback is invoked with an SSLSocket and a server name. The callback must return an SSLContext for the server name or nil.

Adds session to the session cache.

The current session cache mode.

Sets the SSL session cache mode. Bitwise-or together the desired SESSION_CACHE_* constants to set. See SSL_CTX_set_session_cache_mode(3) for details.

Returns the current session cache size. Zero is used to represent an unlimited cache size.

Sets the session cache size. Returns the previously valid session cache size. Zero is used to represent an unlimited session cache size.

Returns a Hash containing the following keys:

:accept

Number of started SSL/TLS handshakes in server mode

:accept_good

Number of established SSL/TLS sessions in server mode

:accept_renegotiate

Number of start renegotiations in server mode

:cache_full

Number of sessions that were removed due to cache overflow

:cache_hits

Number of successfully reused connections

:cache_misses

Number of sessions proposed by clients that were not found in the cache

:cache_num

Number of sessions in the internal session cache

:cb_hits

Number of sessions retrieved from the external cache in server mode

:connect

Number of started SSL/TLS handshakes in client mode

:connect_good

Number of established SSL/TLS sessions in client mode

:connect_renegotiate

Number of start renegotiations in client mode

:timeouts

Number of sessions proposed by clients that were found in the cache but had expired due to timeouts

A callback invoked on a server when a session is proposed by the client but the session could not be found in the server’s internal cache.

The callback is invoked with the SSLSocket and session id. The callback may return a Session from an external cache.

A callback invoked on a server when a session is proposed by the client but the session could not be found in the server’s internal cache.

The callback is invoked with the SSLSocket and session id. The callback may return a Session from an external cache.

Sets the context in which a session can be reused. This allows sessions for multiple applications to be distinguished, for example, by name.

Sets the context in which a session can be reused. This allows sessions for multiple applications to be distinguished, for example, by name.

A callback invoked when a new session was negotiated.

The callback is invoked with an SSLSocket. If false is returned the session will be removed from the internal cache.

A callback invoked when a new session was negotiated.

The callback is invoked with an SSLSocket. If false is returned the session will be removed from the internal cache.

Removes session from the session cache.

A callback invoked when a session is removed from the internal cache.

The callback is invoked with an SSLContext and a Session.

IMPORTANT NOTE: It is currently not possible to use this safely in a multi-threaded application. The callback is called inside a global lock and it can randomly cause deadlock on Ruby thread switching.

A callback invoked when a session is removed from the internal cache.

The callback is invoked with an SSLContext and a Session.

IMPORTANT NOTE: It is currently not possible to use this safely in a multi-threaded application. The callback is called inside a global lock and it can randomly cause deadlock on Ruby thread switching.

Sets the minimum and maximum supported protocol versions. See min_version= and max_version=.

Sets saner defaults optimized for the use with HTTP-like protocols.

If a Hash params is given, the parameters are overridden with it. The keys in params must be assignment methods on SSLContext.

If the verify_mode is not VERIFY_NONE and ca_file, ca_path and cert_store are not set then the system default certificate store is used.

This method is called automatically when a new SSLSocket is created. However, it is not thread-safe and must be called before creating SSLSocket objects in a multi-threaded program.

Sets the SSL/TLS protocol version for the context. This forces connections to use only the specified protocol version. This is deprecated and only provided for backwards compatibility. Use min_version= and max_version= instead.

History

As the name hints, this used to call the SSL_CTX_set_ssl_version() function which sets the SSL method used for connections created from the context. As of Ruby/OpenSSL 2.1, this accessor method is implemented to call min_version= and max_version= instead.

Maximum session lifetime in seconds.

Maximum session lifetime in seconds.

A callback invoked when DH parameters are required for ephemeral DH key exchange.

The callback is invoked with the SSLSocket, a flag indicating the use of an export cipher and the keylength required.

The callback must return an OpenSSL::PKey::DH instance of the correct key length.

<strong>Deprecated in version 3.0.</strong> Use #tmp_dh= instead.

A callback invoked when DH parameters are required for ephemeral DH key exchange.

The callback is invoked with the SSLSocket, a flag indicating the use of an export cipher and the keylength required.

The callback must return an OpenSSL::PKey::DH instance of the correct key length.

<strong>Deprecated in version 3.0.</strong> Use #tmp_dh= instead.

A callback for additional certificate verification. The callback is invoked for each certificate in the chain.

The callback is invoked with two values. preverify_ok indicates indicates if the verification was passed (true) or not (false). store_context is an OpenSSL::X509::StoreContext containing the context used for certificate verification.

If the callback returns false, the chain verification is immediately stopped and a bad_certificate alert is then sent.

A callback for additional certificate verification. The callback is invoked for each certificate in the chain.

The callback is invoked with two values. preverify_ok indicates indicates if the verification was passed (true) or not (false). store_context is an OpenSSL::X509::StoreContext containing the context used for certificate verification.

If the callback returns false, the chain verification is immediately stopped and a bad_certificate alert is then sent.

Number of CA certificates to walk when verifying a certificate chain.

Number of CA certificates to walk when verifying a certificate chain.

Whether to check the server certificate is valid for the hostname.

In order to make this work, verify_mode must be set to VERIFY_PEER and the server hostname must be given by OpenSSL::SSL::SSLSocket#hostname=.

Whether to check the server certificate is valid for the hostname.

In order to make this work, verify_mode must be set to VERIFY_PEER and the server hostname must be given by OpenSSL::SSL::SSLSocket#hostname=.

Session verification mode.

Valid modes are VERIFY_NONE, VERIFY_PEER, VERIFY_CLIENT_ONCE, VERIFY_FAIL_IF_NO_PEER_CERT and defined on OpenSSL::SSL

The default mode is VERIFY_NONE, which does not perform any verification at all.

See SSL_CTX_set_verify(3) for details.

Session verification mode.

Valid modes are VERIFY_NONE, VERIFY_PEER, VERIFY_CLIENT_ONCE, VERIFY_FAIL_IF_NO_PEER_CERT and defined on OpenSSL::SSL

The default mode is VERIFY_NONE, which does not perform any verification at all.

See SSL_CTX_set_verify(3) for details.