OpenSSL::SSL::Context - Crystal 1.21.0

# abstract class OpenSSL::SSL::Context

- OpenSSL::SSL::Context
- Reference
- Object

##
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

- OpenSSL::SSL::Context::Client
- OpenSSL::SSL::Context::Server

##
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

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

  Adds modes to the TLS context.

- #add_options(options : OpenSSL::SSL::Options)

  Adds options to the TLS context.

- #add_x509_verify_flags(flags : OpenSSL::SSL::X509VerifyFlags)

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

- #alpn_protocol=(protocol : String)

  Specifies an ALPN protocol to negotiate with the remote endpoint.

- #ca_certificates=(file_path : String)

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

- #ca_certificates_path=(dir_path : String)

  Sets the path to a directory containing all CA certificates used to validate the peers certificate.

- #certificate_chain=(file_path : String)

  Specify the path to the certificate chain file to use.

- #cipher_suites=(cipher_suites : String)

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

- #ciphers=(ciphers : String)

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

- #default_verify_param=(name : String)

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

- #finalize
- #modes : LibSSL::Modes

  Returns the current modes set on the TLS context.

- #options : LibSSL::Options

  Returns the current options set on the TLS context.

- #private_key=(file_path : String)

  Specify the path to the private key to use.

- #remove_modes(mode : OpenSSL::SSL::Modes)

  Removes modes from the TLS context.

- #remove_options(options : OpenSSL::SSL::Options)

  Removes options from the TLS context.

- #security_level : Int32

  Returns the security level used by this TLS context.

- #security_level=(value : Int32)

  Sets the security level used by this TLS context.

- #set_default_verify_paths

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

- #set_intermediate_ciphers

  Sets the current ciphers and ciphers suites to intermediate compatibility level as per Mozilla recommendations.

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

- #set_modern_ciphers

  Sets the current ciphers and ciphers suites to modern compatibility level as per Mozilla recommendations.

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

- #set_old_ciphers

  Sets the current ciphers and ciphers suites to old compatibility level as per Mozilla recommendations.

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

- #set_tmp_ecdh_key(curve = LibCrypto::NID_X9_62_prime256v1) : Nil

  Adds a temporary ECDH key curve to the TLS context.

- #to_unsafe : LibSSL::SSLContext
- #verify_mode : LibSSL::VerifyMode

  Returns the current verify mode.

- #verify_mode=(mode : OpenSSL::SSL::VerifyMode)

  Sets the verify mode.

### 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 : String | IO, root : String)
from_json(string_or_io : String | 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.

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
    )

def add_x509_verify_flags(flags : OpenSSL::SSL::X509VerifyFlags) #

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

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"

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.

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.

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.

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.

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.

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`.

def finalize #
def modes : LibSSL::Modes #

Returns the current modes set on the TLS context.

def options : LibSSL::Options #

Returns the current options set on the TLS context.

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=`.

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

Removes modes from the TLS context.

def remove_options(options : OpenSSL::SSL::Options) #

Removes options from the TLS context.

Example:

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

def security_level : Int32 #

Returns the security level used by this TLS context.

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

def set_default_verify_paths #

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

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

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

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

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.

def to_unsafe : LibSSL::SSLContext #
def verify_mode : LibSSL::VerifyMode #

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

def verify_mode=(mode : OpenSSL::SSL::VerifyMode) #

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