Flowdock

An SSLContext is used to set various options regarding certificates, algorithms, verification, session caching, etc. The SSLContext is used to create an SSLSocket.

All attributes must be set before creating an SSLSocket as the SSLContext will be frozen afterward.

Constants

SESSION_CACHE_NO_INTERNAL = LONG2NUM(SSL_SESS_CACHE_NO_INTERNAL)

SESSION_CACHE_NO_INTERNAL_STORE = LONG2NUM(SSL_SESS_CACHE_NO_INTERNAL_STORE)

SESSION_CACHE_NO_INTERNAL_LOOKUP = LONG2NUM(SSL_SESS_CACHE_NO_INTERNAL_LOOKUP)

SESSION_CACHE_NO_AUTO_CLEAR = LONG2NUM(SSL_SESS_CACHE_NO_AUTO_CLEAR)

SESSION_CACHE_BOTH = LONG2NUM(SSL_SESS_CACHE_BOTH)

SESSION_CACHE_SERVER = LONG2NUM(SSL_SESS_CACHE_SERVER)

SESSION_CACHE_CLIENT = LONG2NUM(SSL_SESS_CACHE_CLIENT)

SESSION_CACHE_OFF = LONG2NUM(SSL_SESS_CACHE_OFF)

METHODS = METHODS_MAP.flat_map { |name,| [name, :"#{name}_client", :"#{name}_server"] }.freeze

METHODS_MAP = { SSLv23: 0, SSLv2: OpenSSL::SSL::SSL2_VERSION, SSLv3: OpenSSL::SSL::SSL3_VERSION, TLSv1: OpenSSL::SSL::TLS1_VERSION, TLSv1_1: OpenSSL::SSL::TLS1_1_VERSION, TLSv1_2: OpenSSL::SSL::TLS1_2_VERSION, }.freeze

DEFAULT_CERT_STORE = OpenSSL::X509::Store.new # :nodoc:

DEFAULT_TMP_DH_CALLBACK = lambda { |ctx, is_export, keylen| # :nodoc: warn "using default DH parameters." if $VERBOSE DEFAULT_2048 }

DEFAULT_2048 = OpenSSL::PKey::DH.new <<-_end_of_pem_ -----BEGIN DH PARAMETERS----- MIIBCAKCAQEA7E6kBrYiyvmKAMzQ7i8WvwVk9Y/+f8S7sCTN712KkK3cqd1jhJDY JbrYeNV3kUIKhPxWHhObHKpD1R84UpL+s2b55+iMd6GmL7OYmNIT/FccKhTcveab VBmZT86BZKYyf45hUF9FOuUM9xPzuK3Vd8oJQvfYMCd7LPC0taAEljQLR4Edf8E6 YoaOffgTf5qxiwkjnlVZQc3whgnEt9FpVMvQ9eknyeGB5KHfayAc3+hUAvI3/Cr3 1bNveX5wInh5GDx1FGhKBZ+s1H+aedudCm7sCgRwv8lKWYGiHzObSma8A86KG+MD 7Lo5JquQ3DlBodj3IDyPrxIv96lvRPFtAwIBAg== -----END DH PARAMETERS----- _end_of_pem_

DEFAULT_PARAMS = { # :nodoc: :min_version => OpenSSL::SSL::TLS1_VERSION, :verify_mode => OpenSSL::SSL::VERIFY_PEER, :verify_hostname => true, :options => -> { opts = OpenSSL::SSL::OP_ALL opts &= ~OpenSSL::SSL::OP_DONT_INSERT_EMPTY_FRAGMENTS opts |= OpenSSL::SSL::OP_NO_COMPRESSION opts }.call }

Attributes

[RW] alpn_select_cb

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
[RW] alpn_protocols

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"]
[RW] npn_select_cb

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
[RW] npn_protocols

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"]
[RW] renegotiation_cb

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

The callback is invoked with the active SSLSocket. The callback’s return value is irrelevant, normal return indicates “approval” of the renegotiation and will continue the process. To forbid renegotiation and to cancel the process, an Error may be raised 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:

num_handshakes = 0
ctx.renegotiation_cb = lambda do |ssl|
  num_handshakes += 1
  raise RuntimeError.new("Client renegotiation disabled") if num_handshakes > 1
end
[RW] session_remove_cb

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.

[RW] session_new_cb

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.

[RW] session_get_cb

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.

[RW] session_id_context

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

[RW] tmp_ecdh_callback

A callback invoked when ECDH parameters are required.

The callback is invoked with the Session for the key exchange, an flag indicating the use of an export cipher and the keylength required.

The callback is deprecated. This does not work with recent versions of OpenSSL. Use OpenSSL::SSL::SSLContext#ecdh_curves= instead.

[RW] client_cert_cb

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.

[RW] extra_chain_cert

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.

[RW] cert_store

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

[RW] verify_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=.

[RW] verify_callback

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.

[RW] verify_depth

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

[RW] verify_mode

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.

[RW] ssl_timeout

Maximum session lifetime in seconds.

[RW] timeout

Maximum session lifetime in seconds.

[RW] ca_path

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

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

[RW] ca_file

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

[RW] client_ca

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

[RW] key

Context private key

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

[RW] cert

Context certificate

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

[RW] servername_cb

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.

[RW] tmp_dh_callback

A callback invoked when DH parameters are required.

The callback is invoked with the Session for the key exchange, an 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.

Show files where this class is defined (2 files)
Register or log in to add new notes.