class OpenSSL::SSL::SSLContext

Ein SSLContext wird verwendet, um verschiedene Optionen bezüglich Zertifikaten, Algorithmen, Verifizierung, Sitzungscaching usw. festzulegen. Der SSLContext wird zur Erstellung eines SSLSocket verwendet.

Alle Attribute müssen vor der Erstellung eines SSLSocket gesetzt werden, da der SSLContext danach eingefroren wird.

Constants

METHODEN

Die Liste der verfügbaren SSL/TLS-Methoden. Diese Konstante wird nur aus Kompatibilitätsgründen bereitgestellt.

METHODS_MAP

SESSION_CACHE_BOTH

Sowohl Client- als auch Server-Sitzungen werden dem Sitzungscache hinzugefügt

SESSION_CACHE_CLIENT

Client-Sitzungen werden dem Sitzungscache hinzugefügt

SESSION_CACHE_NO_AUTO_CLEAR

Normalerweise wird der Sitzungscache alle 255 Verbindungen auf abgelaufene Sitzungen überprüft. Da dies zu einer nicht kontrollierbaren Verzögerung führen kann, kann das automatische Leeren deaktiviert und flush_sessions explizit aufgerufen werden.

SESSION_CACHE_NO_INTERNAL

Aktiviert sowohl SESSION_CACHE_NO_INTERNAL_LOOKUP als auch SESSION_CACHE_NO_INTERNAL_STORE.

SESSION_CACHE_NO_INTERNAL_LOOKUP

Führt immer externe Lookups von Sitzungen durch, auch wenn sie sich im internen Cache befinden.

Dieses Flag hat keine Auswirkung auf Clients

SESSION_CACHE_NO_INTERNAL_STORE

Speichert niemals automatisch Sitzungen im internen Speicher.

SESSION_CACHE_OFF

Kein Sitzungscaching für Client oder Server

SESSION_CACHE_SERVER

Server-Sitzungen werden dem Sitzungscache hinzugefügt

Attribute

alpn_protocols [RW]

Eine Enumerable von Strings. Jeder String repräsentiert ein Protokoll, das als Liste unterstützter Protokolle für Application-Layer Protocol Negotiation beworben wird. Unterstützt in OpenSSL 1.0.2 und höher. Hat keine Auswirkung auf der Serverseite. Wenn nicht explizit gesetzt, wird die ALPN-Erweiterung nicht im Handshake enthalten sein.

Beispiel

ctx.alpn_protocols = ["http/1.1", "spdy/2", "h2"]

alpn_select_cb [RW]

Eine Callback-Funktion, die auf der Serverseite aufgerufen wird, wenn der Server ein Protokoll aus der vom Client gesendeten Liste auswählen muss. Unterstützt in OpenSSL 1.0.2 und höher. Die Callback-Funktion muss ein Protokoll zurückgeben, das vom Client beworben wurde. Wenn keines akzeptabel ist, führt das Auslösen einer Ausnahme in der Callback-Funktion zum Fehlschlag des Handshakes. Das explizite Setzen dieser Callback-Funktion bedeutet, dass die ALPN-Erweiterung auf dem Server nicht unterstützt wird – alle vom Client beworbenen Protokolle werden ignoriert.

Beispiel

ctx.alpn_select_cb = lambda do |protocols|
  # inspect the protocols and select one
  protocols.first
end

ca_file [RW]

Der Pfad zu einer Datei, die ein PEM-formatiertes CA-Zertifikat enthält

ca_path [RW]

Der Pfad zu einem Verzeichnis, das CA-Zertifikate im PEM-Format enthält.

Dateien werden anhand des Hash-Werts des Subjektsnamens von X509 gesucht.

cert [RW]

Kontext-Zertifikat

Die Attribute cert, key und extra_chain_cert sind veraltet. Es wird empfohlen, stattdessen add_certificate zu verwenden.

cert_store [RW]

Ein OpenSSL::X509::Store zur Zertifikatsverifizierung.

client_ca [RW]

Ein Zertifikat oder eine Array von Zertifikaten, die an den Client gesendet werden.

client_cert_cb [RW]

Eine Callback-Funktion, die aufgerufen wird, wenn ein Client-Zertifikat von einem Server angefordert wird und kein Zertifikat gesetzt wurde.

Die Callback-Funktion wird mit einer Session aufgerufen und muss ein Array zurückgeben, das ein OpenSSL::X509::Certificate und einen OpenSSL::PKey enthält. Wenn ein anderer Wert zurückgegeben wird, wird der Handshake suspendiert.

extra_chain_cert [RW]

Ein Array von zusätzlichen X509-Zertifikaten, die der Zertifikatskette hinzugefügt werden.

Die Attribute cert, key und extra_chain_cert sind veraltet. Es wird empfohlen, stattdessen add_certificate zu verwenden.

key [RW]

Privater Schlüssel des Kontexts

Die Attribute cert, key und extra_chain_cert sind veraltet. Es wird empfohlen, stattdessen add_certificate zu verwenden.

keylog_cb [RW]

Eine Callback-Funktion, die aufgerufen wird, wenn TLS-Schlüsselmaterial generiert oder empfangen wird, um Anwendungen die Speicherung dieses Schlüsselmaterials für Debugging-Zwecke zu ermöglichen.

Die Callback-Funktion wird mit einem SSLSocket und einem String aufgerufen, der das Schlüsselmaterial im von NSS für die SSLKEYLOGFILE-Debugging-Ausgabe verwendeten Format enthält.

Dies ist nur mit OpenSSL >= 1.1.1 kompatibel. Auch wenn LibreSSL SSL_CTX_set_keylog_callback() ab v3.4.2 implementiert, tut es nichts (siehe github.com/libressl-portable/openbsd/commit/648d39f0f035835d0653342d139883b9661e9cb6).

Beispiel

context.keylog_cb = proc do |_sock, line|
  File.open('ssl_keylog_file', "a") do |f|
    f.write("#{line}\n")
  end
end

npn_protocols [RW]

Eine Enumerable von Strings. Jeder String repräsentiert ein Protokoll, das als Liste unterstützter Protokolle für Next Protocol Negotiation beworben wird. Unterstützt in OpenSSL 1.0.1 und höher. Hat keine Auswirkung auf der Clientseite. Wenn nicht explizit gesetzt, wird die NPN-Erweiterung vom Server im Handshake nicht gesendet.

Beispiel

ctx.npn_protocols = ["http/1.1", "spdy/2"]

npn_select_cb [RW]

Eine Callback-Funktion, die auf der Clientseite aufgerufen wird, wenn der Client ein Protokoll aus der vom Server gesendeten Liste auswählen muss. Unterstützt in OpenSSL 1.0.1 und höher. Der Client MUSS ein Protokoll auswählen, das vom Server beworben wurde. Wenn keines akzeptabel ist, führt das Auslösen einer Ausnahme in der Callback-Funktion zum Fehlschlag des Handshakes. Das explizite Setzen dieser Callback-Funktion bedeutet, dass die NPN-Erweiterung auf dem Client nicht unterstützt wird – alle vom Server beworbenen Protokolle werden ignoriert.

Beispiel

ctx.npn_select_cb = lambda do |protocols|
  # inspect the protocols and select one
  protocols.first
end

renegotiation_cb [RW]

Eine Callback-Funktion, die immer aufgerufen wird, wenn ein neuer Handshake auf einer etablierten Verbindung initiiert wird. Kann verwendet werden, um die Neuverhandlung ganz zu deaktivieren.

Die Callback-Funktion wird mit dem aktiven SSLSocket aufgerufen. Der Rückgabewert der Callback-Funktion wird ignoriert. Eine normale Rückgabe signalisiert die „Zustimmung“ zur Neuverhandlung und setzt den Prozess fort. Um die Neuverhandlung zu verbieten und den Prozess abzubrechen, lösen Sie innerhalb der Callback-Funktion eine Ausnahme aus.

Client-Neuverhandlung deaktivieren

Wenn ein Server betrieben wird, ist es oft wünschenswert, die Client-Neuverhandlung vollständig zu deaktivieren. Sie können eine Callback-Funktion wie folgt verwenden, um diese Funktion zu implementieren

ctx.renegotiation_cb = lambda do |ssl|
  raise RuntimeError, "Client renegotiation disabled"
end

servername_cb [RW]

Eine Callback-Funktion, die zum Zeitpunkt der Verbindung aufgerufen wird, um zwischen mehreren Servernamen zu unterscheiden.

Die Callback-Funktion wird mit einem SSLSocket und einem Servernamen aufgerufen. Die Callback-Funktion muss einen SSLContext für den Servernamen oder nil zurückgeben.

session_get_cb [RW]

Eine Callback-Funktion, die auf einem Server aufgerufen wird, wenn eine Sitzung vom Client vorgeschlagen wird, aber die Sitzung nicht im internen Cache des Servers gefunden werden konnte.

Die Callback-Funktion wird mit dem SSLSocket und der Sitzungs-ID aufgerufen. Die Callback-Funktion kann eine Session aus einem externen Cache zurückgeben.

session_id_context [RW]

Legt den Kontext fest, in dem eine Sitzung wiederverwendet werden kann. Dies ermöglicht die Unterscheidung von Sitzungen für mehrere Anwendungen, z. B. anhand des Namens.

session_new_cb [RW]

Eine Callback-Funktion, die aufgerufen wird, wenn eine neue Sitzung ausgehandelt wurde.

Die Callback-Funktion wird mit einem SSLSocket aufgerufen. Wenn false zurückgegeben wird, wird die Sitzung aus dem internen Cache entfernt.

session_remove_cb [RW]

Eine Callback-Funktion, die aufgerufen wird, wenn eine Sitzung aus dem internen Cache entfernt wird.

Die Callback-Funktion wird mit einem SSLContext und einer Session aufgerufen.

WICHTIGER HINWEIS: Die sichere Verwendung in einer Multi-Threaded-Anwendung ist derzeit nicht möglich. Die Callback-Funktion wird innerhalb eines globalen Locks aufgerufen und kann zufällig zu Deadlocks bei der Umschaltung von Ruby-Threads führen.

ssl_timeout [RW]

Maximale Lebensdauer der Sitzung in Sekunden.

timeout [RW]

Maximale Lebensdauer der Sitzung in Sekunden.

tmp_dh_callback [RW]

Eine Callback-Funktion, die aufgerufen wird, wenn DH-Parameter für den ephemeren DH-Schlüsselaustausch benötigt werden.

Die Callback-Funktion wird mit dem SSLSocket, einem Flag, das die Verwendung eines Export-Chiffres angibt, und der erforderlichen Schlüssellänge aufgerufen.

Die Callback-Funktion muss eine OpenSSL::PKey::DH-Instanz der richtigen Schlüssellänge zurückgeben.

Veraltet in Version 3.0. Verwenden Sie stattdessen tmp_dh=.

verify_callback [RW]

Eine Callback-Funktion für zusätzliche Zertifikatsverifizierung. Die Callback-Funktion wird für jedes Zertifikat in der Kette aufgerufen.

Die Callback-Funktion wird mit zwei Werten aufgerufen. preverify_ok gibt an, ob die Verifizierung bestanden wurde (true) oder nicht (false). store_context ist ein OpenSSL::X509::StoreContext, das den für die Zertifikatsverifizierung verwendeten Kontext enthält.

Wenn die Callback-Funktion false zurückgibt, wird die Kettenverifizierung sofort gestoppt und eine „bad_certificate“-Warnung gesendet.

verify_depth [RW]

Anzahl der CA-Zertifikate, die bei der Verifizierung einer Zertifikatskette durchlaufen werden.

verify_hostname [RW]

Ob das Serverzertifikat für den Hostnamen gültig ist, soll überprüft werden.

Damit dies funktioniert, muss verify_mode auf VERIFY_PEER gesetzt sein und der Server-Hostname muss von OpenSSL::SSL::SSLSocket#hostname= angegeben werden.

verify_mode [RW]

Sitzungs-Verifizierungsmodus.

Gültige Modi sind VERIFY_NONE, VERIFY_PEER, VERIFY_CLIENT_ONCE, VERIFY_FAIL_IF_NO_PEER_CERT und sind auf OpenSSL::SSL definiert

Der Standardmodus ist VERIFY_NONE, der keinerlei Verifizierung durchführt.

Details siehe SSL_CTX_set_verify(3).

Öffentliche Klassenmethoden

new → ctx

new(:TLSv1) → ctx

new("SSLv23") → ctx

Source

# File ext/openssl/lib/openssl/ssl.rb, line 94
def initialize(version = nil)
  self.ssl_version = version if version
  self.verify_mode = OpenSSL::SSL::VERIFY_NONE
  self.verify_hostname = false
end

Erstellt einen neuen SSL-Kontext.

Wenn ein Argument angegeben wird, wird ssl_version= mit diesem Wert aufgerufen. Beachten Sie, dass diese Form veraltet ist. Neue Anwendungen sollten stattdessen min_version= und max_version= verwenden.

Öffentliche Instanzmethoden

add_certificate(certificate, pkey [, extra_certs]) → self

Source

static VALUE
ossl_sslctx_add_certificate(int argc, VALUE *argv, VALUE self)
{
    VALUE cert, key, extra_chain_ary;
    SSL_CTX *ctx;
    X509 *x509;
    STACK_OF(X509) *extra_chain = NULL;
    EVP_PKEY *pkey, *pub_pkey;

    GetSSLCTX(self, ctx);
    rb_scan_args(argc, argv, "21", &cert, &key, &extra_chain_ary);
    rb_check_frozen(self);
    x509 = GetX509CertPtr(cert);
    pkey = GetPrivPKeyPtr(key);

    /*
     * The reference counter is bumped, and decremented immediately.
     * X509_get0_pubkey() is only available in OpenSSL >= 1.1.0.
     */
    pub_pkey = X509_get_pubkey(x509);
    EVP_PKEY_free(pub_pkey);
    if (!pub_pkey)
        rb_raise(rb_eArgError, "certificate does not contain public key");
    if (EVP_PKEY_eq(pub_pkey, pkey) != 1)
        rb_raise(rb_eArgError, "public key mismatch");

    if (argc >= 3)
        extra_chain = ossl_x509_ary2sk(extra_chain_ary);

    if (!SSL_CTX_use_certificate(ctx, x509)) {
        sk_X509_pop_free(extra_chain, X509_free);
        ossl_raise(eSSLError, "SSL_CTX_use_certificate");
    }
    if (!SSL_CTX_use_PrivateKey(ctx, pkey)) {
        sk_X509_pop_free(extra_chain, X509_free);
        ossl_raise(eSSLError, "SSL_CTX_use_PrivateKey");
    }
    if (extra_chain && !SSL_CTX_set0_chain(ctx, extra_chain)) {
        sk_X509_pop_free(extra_chain, X509_free);
        ossl_raise(eSSLError, "SSL_CTX_set0_chain");
    }
    return self;
}

Fügt dem Kontext ein Zertifikat hinzu. pkey muss ein passender privater Schlüssel zu certificate sein.

Mehrere Zertifikate mit unterschiedlichen öffentlichen Schlüsseltypen können durch wiederholte Aufrufe dieser Methode hinzugefügt werden, und OpenSSL wählt das am besten geeignete Zertifikat während des Handshakes aus.

cert=, key= und extra_chain_cert= sind alte Zugriffsermethoden zum Setzen von Zertifikaten und rufen intern diese Methode auf.

Parameter

certificate: Ein Zertifikat. Eine Instanz von OpenSSL::X509::Certificate.
pkey: Der private Schlüssel für certificate. Eine Instanz von OpenSSL::PKey::PKey.
extra_certs: Optional. Ein Array von OpenSSL::X509::Certificate. Beim Senden einer Zertifikatskette werden die mit diesem Argument angegebenen Zertifikate nach certificate in der Reihenfolge des Arrays gesendet.

Beispiel

rsa_cert = OpenSSL::X509::Certificate.new(...)
rsa_pkey = OpenSSL::PKey.read(...)
ca_intermediate_cert = OpenSSL::X509::Certificate.new(...)
ctx.add_certificate(rsa_cert, rsa_pkey, [ca_intermediate_cert])

ecdsa_cert = ...
ecdsa_pkey = ...
another_ca_cert = ...
ctx.add_certificate(ecdsa_cert, ecdsa_pkey, [another_ca_cert])

ciphers → [[name, version, bits, alg_bits], ...]

Source

static VALUE
ossl_sslctx_get_ciphers(VALUE self)
{
    SSL_CTX *ctx;
    STACK_OF(SSL_CIPHER) *ciphers;
    const SSL_CIPHER *cipher;
    VALUE ary;
    int i, num;

    GetSSLCTX(self, ctx);
    ciphers = SSL_CTX_get_ciphers(ctx);
    if (!ciphers)
        return rb_ary_new();

    num = sk_SSL_CIPHER_num(ciphers);
    ary = rb_ary_new2(num);
    for(i = 0; i < num; i++){
        cipher = sk_SSL_CIPHER_value(ciphers, i);
        rb_ary_push(ary, ossl_ssl_cipher_to_ary(cipher));
    }
    return ary;
}

Die Liste der für diesen Kontext konfigurierten Cipher-Suiten.

ciphers = "cipher1:cipher2:..."

ciphers = [name, ...]

ciphers = [[name, version, bits, alg_bits], ...]

Source

static VALUE
ossl_sslctx_set_ciphers(VALUE self, VALUE v)
{
    SSL_CTX *ctx;
    VALUE str;

    rb_check_frozen(self);
    // Assigning nil is a no-op for compatibility
    if (NIL_P(v))
        return v;

    str = build_cipher_string(v);

    GetSSLCTX(self, ctx);
    if (!SSL_CTX_set_cipher_list(ctx, StringValueCStr(str)))
        ossl_raise(eSSLError, "SSL_CTX_set_cipher_list");

    return v;
}

Setzt die Liste der verfügbaren Cipher-Suiten für TLS 1.2 und darunter für diesen Kontext.

Beachten Sie, dass im Serverkontext einige Cipher die entsprechenden Zertifikate erfordern. Zum Beispiel kann eine RSA-Cipher-Suite nur gewählt werden, wenn ein RSA-Zertifikat verfügbar ist.

Diese Methode hat keinen Einfluss auf TLS 1.3-Verbindungen. Siehe auch ciphersuites=.

ciphersuites = "cipher1:cipher2:..."

ciphersuites = [name, ...]

Source

static VALUE
ossl_sslctx_set_ciphersuites(VALUE self, VALUE v)
{
    SSL_CTX *ctx;
    VALUE str;

    rb_check_frozen(self);
    // Assigning nil is a no-op for compatibility
    if (NIL_P(v))
        return v;

    str = build_cipher_string(v);

    GetSSLCTX(self, ctx);
    if (!SSL_CTX_set_ciphersuites(ctx, StringValueCStr(str)))
        ossl_raise(eSSLError, "SSL_CTX_set_ciphersuites");

    return v;
}

Setzt die Liste der verfügbaren TLS 1.3-Cipher-Suiten für diesen Kontext.

client_sigalgs = "sigalg1:sigalg2:..."

Source

static VALUE
ossl_sslctx_set_client_sigalgs(VALUE self, VALUE v)
{
    SSL_CTX *ctx;

    rb_check_frozen(self);
    GetSSLCTX(self, ctx);

    if (!SSL_CTX_set1_client_sigalgs_list(ctx, StringValueCStr(v)))
        ossl_raise(eSSLError, "SSL_CTX_set1_client_sigalgs_list");

    return v;
}

Setzt die Liste der „unterstützten Signaturalgorithmen“ für die Client-Authentifizierung für diesen Kontext.

Für einen TLS-Server wird die Liste als Teil der CertificateRequest-Nachricht an den Client gesendet.

Siehe auch sigalgs= für das Äquivalent der Serverauthentifizierung.

groups = groups_list

ecdh_curves = groups_list

Setzt die Liste der unterstützten Gruppen für die Schlüsselvereinbarung für diesen Kontext.

Für einen TLS-Client wird die Liste direkt in der Erweiterung „supported_groups“ verwendet. Für einen Server wird die Liste von OpenSSL verwendet, um die Menge der gemeinsam unterstützten Gruppen zu ermitteln. OpenSSL wählt die am besten geeignete daraus aus.

ecdh_curves= ist ein veralteter Alias für groups=.

Siehe auch die Manpage SSL_CTX_set1_groups_list(3).

Beispiel

ctx1 = OpenSSL::SSL::SSLContext.new
ctx1.groups = "X25519:P-256:P-224"
svr = OpenSSL::SSL::SSLServer.new(tcp_svr, ctx1)
Thread.new { svr.accept }

ctx2 = OpenSSL::SSL::SSLContext.new
ctx2.groups = "P-256"
cli = OpenSSL::SSL::SSLSocket.new(tcp_sock, ctx2)
cli.connect

p cli.tmp_key.group.curve_name
# => "prime256v1" (is an alias for NIST P-256)

Alias für: groups=

enable_fallback_scsv() → nil

Source

static VALUE
ossl_sslctx_enable_fallback_scsv(VALUE self)
{
    SSL_CTX *ctx;

    GetSSLCTX(self, ctx);
    SSL_CTX_set_mode(ctx, SSL_MODE_SEND_FALLBACK_SCSV);

    return Qnil;
}

Aktiviert TLS_FALLBACK_SCSV für diesen Kontext. Siehe RFC 7507.

flush_sessions(time) → self

Source

static VALUE
ossl_sslctx_flush_sessions(int argc, VALUE *argv, VALUE self)
{
    VALUE arg1;
    SSL_CTX *ctx;
    time_t tm = 0;

    rb_scan_args(argc, argv, "01", &arg1);

    GetSSLCTX(self, ctx);

    if (NIL_P(arg1)) {
        tm = time(0);
    } else if (rb_obj_is_instance_of(arg1, rb_cTime)) {
        tm = NUM2LONG(rb_funcall(arg1, rb_intern("to_i"), 0));
    } else {
        ossl_raise(rb_eArgError, "arg must be Time or nil");
    }

    SSL_CTX_flush_sessions(ctx, (long)tm);

    return self;
}

Entfernt Sitzungen aus dem internen Cache, die zum Zeitpunkt time abgelaufen sind.

einfrieren

Alias für: setup

groups = groups_list

ecdh_curves = groups_list

Source

static VALUE
ossl_sslctx_set_groups(VALUE self, VALUE arg)
{
    SSL_CTX *ctx;

    rb_check_frozen(self);
    GetSSLCTX(self, ctx);
    StringValueCStr(arg);

    if (!SSL_CTX_set1_groups_list(ctx, RSTRING_PTR(arg)))
        ossl_raise(eSSLError, "SSL_CTX_set1_groups_list");
    return arg;
}

Setzt die Liste der unterstützten Gruppen für die Schlüsselvereinbarung für diesen Kontext.

ecdh_curves= ist ein veralteter Alias für groups=.

Siehe auch die Manpage SSL_CTX_set1_groups_list(3).

Beispiel

ctx1 = OpenSSL::SSL::SSLContext.new
ctx1.groups = "X25519:P-256:P-224"
svr = OpenSSL::SSL::SSLServer.new(tcp_svr, ctx1)
Thread.new { svr.accept }

ctx2 = OpenSSL::SSL::SSLContext.new
ctx2.groups = "P-256"
cli = OpenSSL::SSL::SSLSocket.new(tcp_sock, ctx2)
cli.connect

p cli.tmp_key.group.curve_name
# => "prime256v1" (is an alias for NIST P-256)

Auch aliased als: ecdh_curves=

max_version = OpenSSL::SSL::TLS1_2_VERSION

max_version = :TLS1_2

max_version = nil

Source

static VALUE
ossl_sslctx_set_max_version(VALUE self, VALUE v)
{
    SSL_CTX *ctx;
    int version;

    rb_check_frozen(self);
    GetSSLCTX(self, ctx);
    version = parse_proto_version(v);

    if (!SSL_CTX_set_max_proto_version(ctx, version))
        ossl_raise(eSSLError, "SSL_CTX_set_max_proto_version");
    return v;
}

Setzt die Obergrenze der unterstützten SSL/TLS-Protokollversion. Siehe min_version= für die möglichen Werte.

min_version = OpenSSL::SSL::TLS1_2_VERSION

min_version = :TLS1_2

min_version = nil

Source

static VALUE
ossl_sslctx_set_min_version(VALUE self, VALUE v)
{
    SSL_CTX *ctx;
    int version;

    rb_check_frozen(self);
    GetSSLCTX(self, ctx);
    version = parse_proto_version(v);

    if (!SSL_CTX_set_min_proto_version(ctx, version))
        ossl_raise(eSSLError, "SSL_CTX_set_min_proto_version");
    return v;
}

Setzt die Untergrenze der unterstützten SSL/TLS-Protokollversion. Die Version kann durch eine Ganzzahlkonstante namens OpenSSL::SSL::*_VERSION, ein Symbol oder nil angegeben werden, was „jede Version“ bedeutet.

Beispiel

ctx = OpenSSL::SSL::SSLContext.new
ctx.min_version = OpenSSL::SSL::TLS1_1_VERSION
ctx.max_version = OpenSSL::SSL::TLS1_2_VERSION

sock = OpenSSL::SSL::SSLSocket.new(tcp_sock, ctx)
sock.connect # Initiates a connection using either TLS 1.1 or TLS 1.2

options → integer

Source

static VALUE
ossl_sslctx_get_options(VALUE self)
{
    SSL_CTX *ctx;
    GetSSLCTX(self, ctx);
    /*
     * Do explicit cast because SSL_CTX_get_options() returned (signed) long in
     * OpenSSL before 1.1.0.
     */
    return ULONG2NUM((unsigned long)SSL_CTX_get_options(ctx));
}

Ruft verschiedene OpenSSL-Optionen ab.

options = integer

Source

static VALUE
ossl_sslctx_set_options(VALUE self, VALUE options)
{
    SSL_CTX *ctx;

    rb_check_frozen(self);
    GetSSLCTX(self, ctx);

    SSL_CTX_clear_options(ctx, SSL_CTX_get_options(ctx));

    if (NIL_P(options)) {
        SSL_CTX_set_options(ctx, SSL_OP_ALL);
    } else {
        SSL_CTX_set_options(ctx, NUM2ULONG(options));
    }

    return self;
}

Setzt verschiedene OpenSSL-Optionen. Die Optionen sind ein Bitfeld und können mit dem bitweisen OR-Operator (|) kombiniert werden. Verfügbare Optionen sind als Konstanten in OpenSSL::SSL definiert, die mit OP_ beginnen.

Aus Kompatibilitätsgründen hat die Übergabe von nil die gleiche Wirkung wie die Übergabe von OpenSSL::SSL::OP_ALL.

Siehe auch die Manpage SSL_CTX_set_options(3).

security_level → Integer

Source

static VALUE
ossl_sslctx_get_security_level(VALUE self)
{
    SSL_CTX *ctx;

    GetSSLCTX(self, ctx);

    return INT2NUM(SSL_CTX_get_security_level(ctx));
}

Gibt die Sicherheitsebene für den Kontext zurück.

Siehe auch OpenSSL::SSL::SSLContext#security_level=.

security_level = integer

Source

static VALUE
ossl_sslctx_set_security_level(VALUE self, VALUE value)
{
    SSL_CTX *ctx;

    rb_check_frozen(self);
    GetSSLCTX(self, ctx);

    SSL_CTX_set_security_level(ctx, NUM2INT(value));

    return value;
}

Setzt die Sicherheitsebene für den Kontext. OpenSSL beschränkt Parameter entsprechend der Ebene. Die „Parameter“ umfassen: Cipher-Suiten, Kurven, Schlüsselgrößen, Zertifikatsignaturalgorithmen, Protokollversion usw. Zum Beispiel lehnt Ebene 1 Parameter ab, die weniger als 80 Bit Sicherheit bieten, wie z. B. Cipher-Suiten mit MD5 für die MAC oder RSA-Schlüssel kürzer als 1024 Bit.

Beachten Sie, dass Versuche, solche Parameter mit unzureichender Sicherheit zu setzen, ebenfalls blockiert werden. Sie müssen zuerst die Ebene senken.

Diese Funktion wird in OpenSSL < 1.1.0 nicht unterstützt, und das Setzen der Ebene auf etwas anderes als 0 löst eine NotImplementedError aus. Ebene 0 bedeutet, dass alles erlaubt ist, das gleiche Verhalten wie in früheren Versionen von OpenSSL.

Siehe die Manpage von SSL_CTX_set_security_level(3) für Details.

session_add(session) → true | false

Source

static VALUE
ossl_sslctx_session_add(VALUE self, VALUE arg)
{
    SSL_CTX *ctx;
    SSL_SESSION *sess;

    GetSSLCTX(self, ctx);
    GetSSLSession(arg, sess);

    return SSL_CTX_add_session(ctx, sess) == 1 ? Qtrue : Qfalse;
}

Fügt session dem Sitzungscache hinzu.

session_cache_mode → Integer

Source

static VALUE
ossl_sslctx_get_session_cache_mode(VALUE self)
{
    SSL_CTX *ctx;

    GetSSLCTX(self, ctx);

    return LONG2NUM(SSL_CTX_get_session_cache_mode(ctx));
}

Der aktuelle Sitzungscache-Modus.

session_cache_mode=(integer) → Integer

Source

static VALUE
ossl_sslctx_set_session_cache_mode(VALUE self, VALUE arg)
{
    SSL_CTX *ctx;

    GetSSLCTX(self, ctx);

    SSL_CTX_set_session_cache_mode(ctx, NUM2LONG(arg));

    return arg;
}

Setzt den Sitzungscache-Modus von SSL. Kombinieren Sie die gewünschten SESSION_CACHE_* Konstanten durch bitweises OR. Siehe SSL_CTX_set_session_cache_mode(3) für Details.

session_cache_size → Integer

Source

static VALUE
ossl_sslctx_get_session_cache_size(VALUE self)
{
    SSL_CTX *ctx;

    GetSSLCTX(self, ctx);

    return LONG2NUM(SSL_CTX_sess_get_cache_size(ctx));
}

Gibt die aktuelle Sitzungscache-Größe zurück. Null repräsentiert eine unbegrenzte Cache-Größe.

session_cache_size=(integer) → Integer

Source

static VALUE
ossl_sslctx_set_session_cache_size(VALUE self, VALUE arg)
{
    SSL_CTX *ctx;

    GetSSLCTX(self, ctx);

    SSL_CTX_sess_set_cache_size(ctx, NUM2LONG(arg));

    return arg;
}

Setzt die Sitzungscache-Größe. Gibt die zuvor gültige Sitzungscache-Größe zurück. Null repräsentiert eine unbegrenzte Sitzungscache-Größe.

session_cache_stats → Hash

Source

static VALUE
ossl_sslctx_get_session_cache_stats(VALUE self)
{
    SSL_CTX *ctx;
    VALUE hash;

    GetSSLCTX(self, ctx);

    hash = rb_hash_new();
    rb_hash_aset(hash, ID2SYM(rb_intern("cache_num")), LONG2NUM(SSL_CTX_sess_number(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("connect")), LONG2NUM(SSL_CTX_sess_connect(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("connect_good")), LONG2NUM(SSL_CTX_sess_connect_good(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("connect_renegotiate")), LONG2NUM(SSL_CTX_sess_connect_renegotiate(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("accept")), LONG2NUM(SSL_CTX_sess_accept(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("accept_good")), LONG2NUM(SSL_CTX_sess_accept_good(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("accept_renegotiate")), LONG2NUM(SSL_CTX_sess_accept_renegotiate(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("cache_hits")), LONG2NUM(SSL_CTX_sess_hits(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("cb_hits")), LONG2NUM(SSL_CTX_sess_cb_hits(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("cache_misses")), LONG2NUM(SSL_CTX_sess_misses(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("cache_full")), LONG2NUM(SSL_CTX_sess_cache_full(ctx)));
    rb_hash_aset(hash, ID2SYM(rb_intern("timeouts")), LONG2NUM(SSL_CTX_sess_timeouts(ctx)));

    return hash;
}

Gibt einen Hash mit den folgenden Schlüsseln zurück

:accept: Anzahl der gestarteten SSL/TLS-Handshakes im Servermodus
:accept_good: Anzahl der etablierten SSL/TLS-Sitzungen im Servermodus
:accept_renegotiate: Anzahl der gestarteten Neuverhandlungen im Servermodus
:cache_full: Anzahl der Sitzungen, die aufgrund von Cache-Überläufen entfernt wurden
:cache_hits: Anzahl der erfolgreich wiederverwendeten Verbindungen
:cache_misses: Anzahl der von Clients vorgeschlagenen Sitzungen, die nicht im Cache gefunden wurden
:cache_num: Anzahl der Sitzungen im internen Sitzungscache
:cb_hits: Anzahl der im Servermodus aus dem externen Cache abgerufenen Sitzungen
:connect: Anzahl der gestarteten SSL/TLS-Handshakes im Clientmodus
:connect_good: Anzahl der etablierten SSL/TLS-Sitzungen im Clientmodus
:connect_renegotiate: Anzahl der gestarteten Neuverhandlungen im Clientmodus
:timeouts: Anzahl der von Clients vorgeschlagenen Sitzungen, die im Cache gefunden, aber aufgrund von Timeouts abgelaufen waren

session_remove(session) → true | false

Source

static VALUE
ossl_sslctx_session_remove(VALUE self, VALUE arg)
{
    SSL_CTX *ctx;
    SSL_SESSION *sess;

    GetSSLCTX(self, ctx);
    GetSSLSession(arg, sess);

    return SSL_CTX_remove_session(ctx, sess) == 1 ? Qtrue : Qfalse;
}

Entfernt session aus dem Sitzungscache.

set_params(params = {}) → params

Source

# File ext/openssl/lib/openssl/ssl.rb, line 112
def set_params(params={})
  params = DEFAULT_PARAMS.merge(params)
  self.options |= params.delete(:options) # set before min_version/max_version
  params.each{|name, value| self.__send__("#{name}=", value) }
  if self.verify_mode != OpenSSL::SSL::VERIFY_NONE
    unless self.ca_file or self.ca_path or self.cert_store
      if not defined?(Ractor) or Ractor.current == Ractor.main
        self.cert_store = DEFAULT_CERT_STORE
      else
        self.cert_store = Ractor.current[:__openssl_default_store__] ||=
          OpenSSL::X509::Store.new.tap { |store|
            store.set_default_paths
          }
      end
    end
  end
  return params
end

Setzt sinnvollere Standardwerte, die für die Verwendung mit HTTP-ähnlichen Protokollen optimiert sind.

Wenn ein Hash params angegeben wird, werden die Parameter damit überschrieben. Die Schlüssel in params müssen Zuweisungsmethoden auf SSLContext sein.

Wenn der verify_mode nicht VERIFY_NONE ist und ca_file, ca_path und cert_store nicht gesetzt sind, wird der systemeigene Zertifikatsspeicher verwendet.

setup → Qtrue # erstes Mal

setup → nil # danach

Source

static VALUE
ossl_sslctx_setup(VALUE self)
{
    SSL_CTX *ctx;
    X509 *cert = NULL, *client_ca = NULL;
    EVP_PKEY *key = NULL;
    char *ca_path = NULL, *ca_file = NULL;
    int verify_mode;
    long i;
    VALUE val;

    if(OBJ_FROZEN(self)) return Qnil;
    GetSSLCTX(self, ctx);

#if !defined(OPENSSL_NO_DH)
    if (!NIL_P(rb_attr_get(self, id_i_tmp_dh_callback))) {
        SSL_CTX_set_tmp_dh_callback(ctx, ossl_tmp_dh_callback);
        SSL_CTX_set_dh_auto(ctx, 0);
    }
#endif

#if !defined(OPENSSL_IS_AWSLC) /* AWS-LC has no support for TLS 1.3 PHA. */
    SSL_CTX_set_post_handshake_auth(ctx, 1);
#endif

    val = rb_attr_get(self, id_i_cert_store);
    if (!NIL_P(val)) {
        X509_STORE *store = GetX509StorePtr(val); /* NO NEED TO DUP */
        SSL_CTX_set_cert_store(ctx, store);
        X509_STORE_up_ref(store);
    }

    val = rb_attr_get(self, id_i_extra_chain_cert);
    if(!NIL_P(val)){
        rb_block_call(val, rb_intern("each"), 0, 0, ossl_sslctx_add_extra_chain_cert_i, self);
    }

    /* private key may be bundled in certificate file. */
    val = rb_attr_get(self, id_i_cert);
    cert = NIL_P(val) ? NULL : GetX509CertPtr(val); /* NO DUP NEEDED */
    val = rb_attr_get(self, id_i_key);
    key = NIL_P(val) ? NULL : GetPrivPKeyPtr(val); /* NO DUP NEEDED */
    if (cert && key) {
        if (!SSL_CTX_use_certificate(ctx, cert)) {
            /* Adds a ref => Safe to FREE */
            ossl_raise(eSSLError, "SSL_CTX_use_certificate");
        }
        if (!SSL_CTX_use_PrivateKey(ctx, key)) {
            /* Adds a ref => Safe to FREE */
            ossl_raise(eSSLError, "SSL_CTX_use_PrivateKey");
        }
        if (!SSL_CTX_check_private_key(ctx)) {
            ossl_raise(eSSLError, "SSL_CTX_check_private_key");
        }
    }

    val = rb_attr_get(self, id_i_client_ca);
    if(!NIL_P(val)){
        if (RB_TYPE_P(val, T_ARRAY)) {
            for(i = 0; i < RARRAY_LEN(val); i++){
                client_ca = GetX509CertPtr(RARRAY_AREF(val, i));
                if (!SSL_CTX_add_client_CA(ctx, client_ca)){
                    /* Copies X509_NAME => FREE it. */
                    ossl_raise(eSSLError, "SSL_CTX_add_client_CA");
                }
            }
        }
        else{
            client_ca = GetX509CertPtr(val); /* NO DUP NEEDED. */
            if (!SSL_CTX_add_client_CA(ctx, client_ca)){
                /* Copies X509_NAME => FREE it. */
                ossl_raise(eSSLError, "SSL_CTX_add_client_CA");
            }
        }
    }

    val = rb_attr_get(self, id_i_ca_file);
    ca_file = NIL_P(val) ? NULL : StringValueCStr(val);
    val = rb_attr_get(self, id_i_ca_path);
    ca_path = NIL_P(val) ? NULL : StringValueCStr(val);
#ifdef HAVE_SSL_CTX_LOAD_VERIFY_FILE
    if (ca_file && !SSL_CTX_load_verify_file(ctx, ca_file))
        ossl_raise(eSSLError, "SSL_CTX_load_verify_file");
    if (ca_path && !SSL_CTX_load_verify_dir(ctx, ca_path))
        ossl_raise(eSSLError, "SSL_CTX_load_verify_dir");
#else
    if (ca_file || ca_path) {
        if (!SSL_CTX_load_verify_locations(ctx, ca_file, ca_path))
            ossl_raise(eSSLError, "SSL_CTX_load_verify_locations");
    }
#endif

    val = rb_attr_get(self, id_i_verify_mode);
    verify_mode = NIL_P(val) ? SSL_VERIFY_NONE : NUM2INT(val);
    SSL_CTX_set_verify(ctx, verify_mode, ossl_ssl_verify_callback);
    if (RTEST(rb_attr_get(self, id_i_client_cert_cb)))
        SSL_CTX_set_client_cert_cb(ctx, ossl_client_cert_cb);

    val = rb_attr_get(self, id_i_timeout);
    if(!NIL_P(val)) SSL_CTX_set_timeout(ctx, NUM2LONG(val));

    val = rb_attr_get(self, id_i_verify_depth);
    if(!NIL_P(val)) SSL_CTX_set_verify_depth(ctx, NUM2INT(val));

#ifdef OSSL_USE_NEXTPROTONEG
    val = rb_attr_get(self, id_i_npn_protocols);
    if (!NIL_P(val)) {
        VALUE encoded = ssl_encode_npn_protocols(val);
        rb_ivar_set(self, id_npn_protocols_encoded, encoded);
        SSL_CTX_set_next_protos_advertised_cb(ctx, ssl_npn_advertise_cb, (void *)self);
        OSSL_Debug("SSL NPN advertise callback added");
    }
    if (RTEST(rb_attr_get(self, id_i_npn_select_cb))) {
        SSL_CTX_set_next_proto_select_cb(ctx, ssl_npn_select_cb, (void *) self);
        OSSL_Debug("SSL NPN select callback added");
    }
#endif

    val = rb_attr_get(self, id_i_alpn_protocols);
    if (!NIL_P(val)) {
        VALUE rprotos = ssl_encode_npn_protocols(val);

        /* returns 0 on success */
        if (SSL_CTX_set_alpn_protos(ctx, (unsigned char *)RSTRING_PTR(rprotos),
                                    RSTRING_LENINT(rprotos)))
            ossl_raise(eSSLError, "SSL_CTX_set_alpn_protos");
        OSSL_Debug("SSL ALPN values added");
    }
    if (RTEST(rb_attr_get(self, id_i_alpn_select_cb))) {
        SSL_CTX_set_alpn_select_cb(ctx, ssl_alpn_select_cb, (void *) self);
        OSSL_Debug("SSL ALPN select callback added");
    }

    rb_obj_freeze(self);

    val = rb_attr_get(self, id_i_session_id_context);
    if (!NIL_P(val)){
        StringValue(val);
        if (!SSL_CTX_set_session_id_context(ctx, (unsigned char *)RSTRING_PTR(val),
                                            RSTRING_LENINT(val))){
            ossl_raise(eSSLError, "SSL_CTX_set_session_id_context");
        }
    }

    if (RTEST(rb_attr_get(self, id_i_session_get_cb))) {
        SSL_CTX_sess_set_get_cb(ctx, ossl_sslctx_session_get_cb);
        OSSL_Debug("SSL SESSION get callback added");
    }
    if (RTEST(rb_attr_get(self, id_i_session_new_cb))) {
        SSL_CTX_sess_set_new_cb(ctx, ossl_sslctx_session_new_cb);
        OSSL_Debug("SSL SESSION new callback added");
    }
    if (RTEST(rb_attr_get(self, id_i_session_remove_cb))) {
        SSL_CTX_sess_set_remove_cb(ctx, ossl_sslctx_session_remove_cb);
        OSSL_Debug("SSL SESSION remove callback added");
    }

    val = rb_attr_get(self, id_i_servername_cb);
    if (!NIL_P(val)) {
        SSL_CTX_set_tlsext_servername_callback(ctx, ssl_servername_cb);
        OSSL_Debug("SSL TLSEXT servername callback added");
    }

#if !OSSL_IS_LIBRESSL
    /*
     * It is only compatible with OpenSSL >= 1.1.1. Even if LibreSSL implements
     * SSL_CTX_set_keylog_callback() from v3.4.2, it does nothing (see
     * https://github.com/libressl-portable/openbsd/commit/648d39f0f035835d0653342d139883b9661e9cb6).
     */
    if (RTEST(rb_attr_get(self, id_i_keylog_cb))) {
        SSL_CTX_set_keylog_callback(ctx, ossl_sslctx_keylog_cb);
        OSSL_Debug("SSL keylog callback added");
    }
#endif

    return Qtrue;
}

Diese Methode wird automatisch aufgerufen, wenn ein neues SSLSocket erstellt wird. Sie ist jedoch nicht thread-sicher und muss aufgerufen werden, bevor SSLSocket-Objekte in einem Multi-Threaded-Programm erstellt werden.

Auch aliased als: freeze

sigalgs = "sigalg1:sigalg2:..."

Source

static VALUE
ossl_sslctx_set_sigalgs(VALUE self, VALUE v)
{
    SSL_CTX *ctx;

    rb_check_frozen(self);
    GetSSLCTX(self, ctx);

    if (!SSL_CTX_set1_sigalgs_list(ctx, StringValueCStr(v)))
        ossl_raise(eSSLError, "SSL_CTX_set1_sigalgs_list");

    return v;
}

Setzt die Liste der „unterstützten Signaturalgorithmen“ für diesen Kontext.

Für einen TLS-Client wird die Liste in der Erweiterung „signature_algorithms“ in der ClientHello-Nachricht verwendet. Für einen Server wird die Liste von OpenSSL verwendet, um die Menge der gemeinsam unterstützten Signaturalgorithmen zu ermitteln. OpenSSL wählt die am besten geeignete daraus aus.

Siehe auch client_sigalgs= für das Äquivalent der Client-Authentifizierung.

ssl_version = :TLSv1

ssl_version = "SSLv23"

Source

# File ext/openssl/lib/openssl/ssl.rb, line 145
def ssl_version=(meth)
  meth = meth.to_s if meth.is_a?(Symbol)
  if /(?<type>_client|_server)\z/ =~ meth
    meth = $`
    if $VERBOSE
      warn "#{caller(1, 1)[0]}: method type #{type.inspect} is ignored"
    end
  end
  version = METHODS_MAP[meth.intern] or
    raise ArgumentError, "unknown SSL method `%s'" % meth
  self.min_version = self.max_version = version
end

Setzt die SSL/TLS-Protokollversion für den Kontext. Dies zwingt Verbindungen, nur die angegebene Protokollversion zu verwenden. Dies ist veraltet und wird nur aus Kompatibilitätsgründen bereitgestellt. Verwenden Sie stattdessen min_version= und max_version=.

Historie

Wie der Name schon sagt, rief dies früher die Funktion SSL_CTX_set_ssl_version() auf, die die SSL-Methode festlegt, die für von dem Kontext erstellte Verbindungen verwendet wird. Ab Ruby/OpenSSL 2.1 wird diese Accessor-Methode so implementiert, dass stattdessen min_version= und max_version= aufgerufen werden.

tmp_dh = pkey

Source

static VALUE
ossl_sslctx_set_tmp_dh(VALUE self, VALUE arg)
{
    SSL_CTX *ctx;
    EVP_PKEY *pkey;

    rb_check_frozen(self);
    GetSSLCTX(self, ctx);
    pkey = GetPKeyPtr(arg);

    if (EVP_PKEY_base_id(pkey) != EVP_PKEY_DH)
        rb_raise(eSSLError, "invalid pkey type %s (expected DH)",
                 OBJ_nid2sn(EVP_PKEY_base_id(pkey)));
#ifdef HAVE_SSL_CTX_SET0_TMP_DH_PKEY
    if (!SSL_CTX_set0_tmp_dh_pkey(ctx, pkey))
        ossl_raise(eSSLError, "SSL_CTX_set0_tmp_dh_pkey");
    EVP_PKEY_up_ref(pkey);
#else
    if (!SSL_CTX_set_tmp_dh(ctx, EVP_PKEY_get0_DH(pkey)))
        ossl_raise(eSSLError, "SSL_CTX_set_tmp_dh");
#endif

    // Turn off the "auto" DH parameters set by ossl_sslctx_s_alloc()
    SSL_CTX_set_dh_auto(ctx, 0);

    return arg;
}

Setzt DH-Parameter, die für den ephemeren DH-Schlüsselaustausch verwendet werden. Dies ist nur für Server relevant.

pkey ist eine Instanz von OpenSSL::PKey::DH. Beachten Sie, dass Schlüsselkomponenten, die im Schlüsselobjekt enthalten sind, falls vorhanden, ignoriert werden. Der Server generiert für jeden Handshake immer ein neues Schlüsselpaar.

Hinzugefügt in Version 3.0. Siehe auch die Manpage SSL_CTX_set0_tmp_dh_pkey(3).

Beispiel

ctx = OpenSSL::SSL::SSLContext.new
ctx.tmp_dh = OpenSSL::DH.generate(2048)
svr = OpenSSL::SSL::SSLServer.new(tcp_svr, ctx)
Thread.new { svr.accept }