abstract class OpenSSL::SSL::Context

Overview

An SSL::Context represents a generic secure socket protocol configuration.

For both server and client applications exist more specialized subclassses SSL::Context::Server and SSL::Context::Client which need to be instantiated appropriately.

Direct Known Subclasses

Defined in:

openssl/ssl/context.cr
openssl/ssl/defaults.cr

Constant Summary

CIPHER_SUITES_INTERMEDIATE = "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

The list of secure ciphersuites on intermediate compatibility level as per Mozilla recommendations.

The oldest clients supported by this configuration are:

  • Firefox 27
  • Android 4.4.2
  • Chrome 31
  • Edge
  • IE 11 on Windows 7
  • Java 8u31
  • OpenSSL 1.0.1
  • Opera 20
  • Safari 9

This list represents version 5.7 of the intermediate configuration available at https://ssl-config.mozilla.org/guidelines/5.7.json.

See https://wiki.mozilla.org/Security/Server_Side_TLS for details.

DEPRECATED Deprecated with no replacement. Prefer setting a security level, global system configuration, or build your own from https://ssl-config.mozilla.org

CIPHER_SUITES_MODERN = "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

The list of secure ciphersuites on modern compatibility level as per Mozilla recommendations.

The oldest clients supported by this configuration are:

  • Firefox 63
  • Android 10.0
  • Chrome 70
  • Edge 75
  • Java 11
  • OpenSSL 1.1.1
  • Opera 57
  • Safari 12.1

This list represents version 5.7 of the modern configuration available at https://ssl-config.mozilla.org/guidelines/5.7.json.

See https://wiki.mozilla.org/Security/Server_Side_TLS for details.

DEPRECATED Deprecated with no replacement. Prefer setting a security level, global system configuration, or build your own from https://ssl-config.mozilla.org

CIPHER_SUITES_OLD = "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

The list of secure ciphersuites on old compatibility level as per Mozilla recommendations.

The oldest clients supported by this configuration are:

  • Firefox 1
  • Android 2.3
  • Chrome 1
  • Edge 12
  • IE8 on Windows XP
  • Java 6
  • OpenSSL 0.9.8
  • Opera 5
  • Safari 1

This list represents version 5.7 of the old configuration available at https://ssl-config.mozilla.org/guidelines/5.7.json.

See https://wiki.mozilla.org/Security/Server_Side_TLS for details.

DEPRECATED Deprecated with no replacement. Prefer setting a security level, global system configuration, or build your own from https://ssl-config.mozilla.org

CIPHERS_INTERMEDIATE = "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:!RC4:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS"

The list of secure ciphers on intermediate compatibility level as per Mozilla recommendations.

The oldest clients supported by this configuration are:

  • Firefox 27
  • Android 4.4.2
  • Chrome 31
  • Edge
  • IE 11 on Windows 7
  • Java 8u31
  • OpenSSL 1.0.1
  • Opera 20
  • Safari 9

This list represents version 5.7 of the intermediate configuration available at https://ssl-config.mozilla.org/guidelines/5.7.json.

See https://wiki.mozilla.org/Security/Server_Side_TLS for details.

DEPRECATED Deprecated with no replacement. Prefer setting a security level, global system configuration, or build your own from https://ssl-config.mozilla.org

CIPHERS_MODERN = "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:!RC4:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS"

The list of secure ciphers on modern compatibility level as per Mozilla recommendations.

The oldest clients supported by this configuration are:

  • Firefox 63
  • Android 10.0
  • Chrome 70
  • Edge 75
  • Java 11
  • OpenSSL 1.1.1
  • Opera 57
  • Safari 12.1

This list represents version 5.7 of the modern configuration available at https://ssl-config.mozilla.org/guidelines/5.7.json.

See https://wiki.mozilla.org/Security/Server_Side_TLS for details.

DEPRECATED Deprecated with no replacement. Prefer setting a security level, global system configuration, or build your own from https://ssl-config.mozilla.org

CIPHERS_OLD = "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!RC4:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS"

The list of secure ciphers on old compatibility level as per Mozilla recommendations.

The oldest clients supported by this configuration are:

  • Firefox 1
  • Android 2.3
  • Chrome 1
  • Edge 12
  • IE8 on Windows XP
  • Java 6
  • OpenSSL 0.9.8
  • Opera 5
  • Safari 1

This list represents version 5.7 of the old configuration available at https://ssl-config.mozilla.org/guidelines/5.7.json.

See https://wiki.mozilla.org/Security/Server_Side_TLS for details.

DEPRECATED Deprecated with no replacement. Prefer setting a security level, global system configuration, or build your own from https://ssl-config.mozilla.org

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

Constructor methods inherited from class Reference

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

Class methods inherited from class Reference

pre_initialize(address : Pointer) pre_initialize

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Instance Method Detail

def add_modes(mode : OpenSSL::SSL::Modes) #

Adds modes to the TLS context.


[View source]
def add_options(options : OpenSSL::SSL::Options) #

Adds options to the TLS context.

Example:

context.add_options(
  OpenSSL::SSL::Options::ALL |       # various workarounds
  OpenSSL::SSL::Options::NO_SSL_V2 | # disable overly deprecated SSLv2
  OpenSSL::SSL::Options::NO_SSL_V3   # disable deprecated SSLv3
)

[View source]
def add_x509_verify_flags(flags : OpenSSL::SSL::X509VerifyFlags) #

Sets the given OpenSSL::SSL::X509VerifyFlags in this context, additionally to the already set ones.


[View source]
def alpn_protocol=(protocol : String) #

Specifies an ALPN protocol to negotiate with the remote endpoint. This is required to negotiate HTTP/2 with browsers, since browser vendors decided not to implement HTTP/2 over insecure connections.

Example:

context.alpn_protocol = "h2"

[View source]
def ca_certificates=(file_path : String) #

Sets the path to a file containing all CA certificates, in PEM format, used to validate the peers certificate.


[View source]
def ca_certificates_path=(dir_path : String) #

Sets the path to a directory containing all CA certificates used to validate the peers certificate. The certificates should be in PEM format and the c_rehash(1) utility must have been run in the directory.


[View source]
def certificate_chain=(file_path : String) #

Specify the path to the certificate chain file to use. In server mode this is presented to the client, in client mode this used as client certificate.


[View source]
def cipher_suites=(cipher_suites : String) #

Specify a list of TLS ciphersuites to use or discard for TLSv1.3.

See #security_level= for some sensible system configuration.

NOTE The ciphersuites available to an application are determined by the linked version of the system SSL library. A comprehensive list of ciphersuites can be found in the OpenSSL Cipher documentation.


[View source]
def ciphers=(ciphers : String) #

Specify a list of TLS ciphers to use or discard for TLSv1.2 and below.

See #security_level= for some sensible system configuration.

This method does not impact TLSv1.3 ciphersuites. Use #cipher_suites= to configure those.

NOTE The ciphers available to an application are determined by the linked version of the system SSL library. A comprehensive list of ciphers can be found in the OpenSSL Cipher documentation.


[View source]
def default_verify_param=(name : String) #

Sets this context verify param to the default one of the given name.

Depending on the OpenSSL version, the available defaults are default, pkcs7, smime_sign, ssl_client and ssl_server.


[View source]
def finalize #

[View source]
def modes : LibSSL::Modes #

Returns the current modes set on the TLS context.


[View source]
def options : LibSSL::Options #

Returns the current options set on the TLS context.


[View source]
def private_key=(file_path : String) #

Specify the path to the private key to use. The key must in PEM format. The key must correspond to the entity certificate set by #certificate_chain=.


[View source]
def remove_modes(mode : OpenSSL::SSL::Modes) #

Removes modes from the TLS context.


[View source]
def remove_options(options : OpenSSL::SSL::Options) #

Removes options from the TLS context.

Example:

context.remove_options(OpenSSL::SSL::Options::NO_SSL_V3)

[View source]
def security_level : Int32 #

Returns the security level used by this TLS context.


[View source]
def security_level=(value : Int32) #

Sets the security level used by this TLS context. The default system security level might disable some ciphers.

  • https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_security_level.html
  • https://wiki.debian.org/ContinuousIntegration/TriagingTips/openssl-1.1.1

[View source]
def set_default_verify_paths #

Sets the default paths for #ca_certificates= and #ca_certificates_path=.


[View source]
def set_intermediate_ciphers #

Sets the current ciphers and ciphers suites to intermediate compatibility level as per Mozilla recommendations. See #security_level= for some sensible system configuration.

WARNING Does nothing as of Crystal 1.13.

WARNING Didn't work as expected as of OpenSSL 1.1 (didn't configure TLSv1.2 and below).

DEPRECATED Deprecated with no replacement. Prefer #security_level, global system configuration or build your own from https://wiki.mozilla.org/Security/Server_Side_TLS


[View source]
def set_modern_ciphers #

Sets the current ciphers and ciphers suites to modern compatibility level as per Mozilla recommendations. See #security_level= for some sensible system configuration.

WARNING Does nothing as of Crystal 1.13.

WARNING Didn't work as expected as of OpenSSL 1.1 (didn't configure TLSv1.2 and below).

DEPRECATED Deprecated with no replacement. Prefer #security_level, global system configuration or build your own from https://wiki.mozilla.org/Security/Server_Side_TLS


[View source]
def set_old_ciphers #

Sets the current ciphers and ciphers suites to old compatibility level as per Mozilla recommendations. See #security_level= for some sensible system configuration.

WARNING Does nothing as of Crystal 1.13.

WARNING Didn't work as expected as of OpenSSL 1.1 (didn't configure TLSv1.2 and below).

DEPRECATED Deprecated with no replacement. Prefer #security_level, global system configuration or build your own from https://wiki.mozilla.org/Security/Server_Side_TLS


[View source]
def set_tmp_ecdh_key(curve = LibCrypto::NID_X9_62_prime256v1) : Nil #

Adds a temporary ECDH key curve to the TLS context. This is required to enable the EECDH cipher suites. By default the prime256 curve will be used.


[View source]
def to_unsafe : LibSSL::SSLContext #

[View source]
def verify_mode : LibSSL::VerifyMode #

Returns the current verify mode. See the SSL_CTX_set_verify(3) manpage for more details.


[View source]
def verify_mode=(mode : OpenSSL::SSL::VerifyMode) #

Sets the verify mode. See the SSL_CTX_set_verify(3) manpage for more details.


[View source]