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.

All instances use CIPHERS_INTERMEDIATE ciphers by default.

Direct Known Subclasses

Defined in:

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

Constant Summary

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 !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.4 of the intermediate configuration available at https://ssl-config.mozilla.org/guidelines/5.4.json.

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

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.4 of the modern configuration available at https://ssl-config.mozilla.org/guidelines/5.4.json.

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

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.4 of the old configuration available at https://ssl-config.mozilla.org/guidelines/5.4.json.

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

Instance Method Summary

Instance methods inherited from class Reference

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

Constructor methods inherited from class Reference

new new

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?(*values : Object) : Bool
in?(collection) : Bool
in?
, inspect : String
inspect(io : IO) : Nil
inspect
, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, 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)
to_json
to_json
, to_pretty_json(io : IO, indent : String = " ")
to_pretty_json(indent : String = " ")
to_pretty_json
, to_s : String
to_s(io : IO) : Nil
to_s
, to_yaml(io : IO)
to_yaml
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

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::X509VerifyFlags) #

Sets the given OpenSSL::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 ciphers=(ciphers : String) #

Specify a list of TLS ciphers to use or discard.

This affects only TLSv1.2 and below.


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

Returns the current modes set on the TLS context.


[View source]
def 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 set_default_verify_paths #

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


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

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 #

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]