W3cubDocs

/Crystal

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 : 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)Source

Adds modes to the TLS context.

def add_options(options : OpenSSL::SSL::Options)Source

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)Source

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

def alpn_protocol=(protocol : String)Source

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)Source

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)Source

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)Source

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)Source

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)Source

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)Source

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 finalizeSource

def modes : LibSSL::ModesSource

Returns the current modes set on the TLS context.

def options : LibSSL::OptionsSource

Returns the current options set on the TLS context.

def private_key=(file_path : String)Source

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)Source

Removes modes from the TLS context.

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

Removes options from the TLS context.

Example:

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

def security_level : Int32Source

Returns the security level used by this TLS context.

def security_level=(value : Int32)Source

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_pathsSource

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

def set_intermediate_ciphersSource

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_ciphersSource

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_ciphersSource

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) : NilSource

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::SSLContextSource

def verify_mode : LibSSL::VerifyModeSource

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

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

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

© 2012–2026 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/1.19.0/OpenSSL/SSL/Context.html