Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more

In Files

  • openssl/lib/openssl/ssl-internal.rb
  • openssl/ossl_ssl.c

Class/Module Index [+]



An SSLContext is used to set various options regarding certificates, algorithms, verification, session caching, etc. The SSLContext is used to create an SSLSocket.

All attributes must be set before creating an SSLSocket as the SSLContext will be frozen afterward.

The following attributes are available but don't show up in rdoc:



The list of available SSL/TLS methods


Both client and server sessions are added to the session cache


Client sessions are added to the session cache


Normally the sesison cache is checked for expired sessions every 255 connections. Since this may lead to a delay that cannot be controlled, the automatic flushing may be disabled and flush_sessions can be called explicitly.




Always perform external lookups of sessions even if they are in the internal cache.

This flag has no effect on clients


Never automatically store sessions in the internal store.


No session caching for client or server


Server sessions are added to the session cache



The path to a file containing a PEM-format CA certificate


The path to a directory containing CA certificates in PEM format.

Files are looked up by subject’s X509 name’s hash value.


Context certificate


An OpenSSL::X509::Store used for certificate verification


A certificate or Array of certificates that will be sent to the client.


A callback invoked when a client certificate is requested by a server and no certificate has been set.

The callback is invoked with a Session and must return an Array containing an OpenSSL::X509::Certificate and an OpenSSL::PKey. If any other value is returned the handshake is suspended.


An Array of extra X509 certificates to be added to the certificate chain.


Context private key


Sets various OpenSSL options.


A callback invoked at connect time to distinguish between multiple server names.

The callback is invoked with an SSLSocket and a server name. The callback must return an SSLContext for the server name or nil.


A callback invoked on a server when a session is proposed by the client but the session could not be found in the server’s internal cache.

The callback is invoked with the SSLSocket and session id. The callback may return a Session from an external cache.


Sets the context in which a session can be reused. This allows sessions for multiple applications to be distinguished, for exapmle, by name.


A callback invoked when a new session was negotiatied.

The callback is invoked with an SSLSocket. If false is returned the session will be removed from the internal cache.


A callback invoked when a session is removed from the internal cache.

The callback is invoked with an SSLContext and a Session.


Maximum session lifetime.


Maximum session lifetime.


A callback invoked when DH parameters are required.

The callback is invoked with the Session for the key exchange, an flag indicating the use of an export cipher and the keylength required.

The callback must return an OpenSSL::PKey::DH instance of the correct key length.


A callback for additional certificate verification. The callback is invoked for each certificate in the chain.

The callback is invoked with two values. preverify_ok indicates indicates if the verification was passed (true) or not (false). store_context is an OpenSSL::X509::StoreContext containing the context used for certificate verification.

If the callback returns false verification is stopped.


Number of CA certificates to walk when verifying a certificate chain.


Session verification mode.


Public Class Methods

new => ctx click to toggle source
new(:TLSv1) => ctx
new("SSLv23_client") => ctx

You can get a list of valid methods with OpenSSL::SSL::SSLContext::METHODS

               static VALUE
ossl_sslctx_initialize(int argc, VALUE *argv, VALUE self)
    VALUE ssl_method;
    int i;

    for(i = 0; i < numberof(ossl_sslctx_attrs); i++){
        char buf[32];
        snprintf(buf, sizeof(buf), "@%s", ossl_sslctx_attrs[i]);
        rb_iv_set(self, buf, Qnil);
    if (rb_scan_args(argc, argv, "01", &ssl_method) == 0){
        return self;
    ossl_sslctx_set_ssl_version(self, ssl_method);

    return self;

Public Instance Methods

ciphers => [[name, version, bits, alg_bits], ...] click to toggle source

The list of ciphers configured for this context.

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

    Data_Get_Struct(self, SSL_CTX, ctx);
        rb_warning("SSL_CTX is not initialized.");
        return Qnil;
    ciphers = ctx->cipher_list;

    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;
ciphers = "cipher1:cipher2:..." click to toggle source
ciphers = [name, ...]
ciphers = [[name, version, bits, alg_bits], ...]

Sets the list of available ciphers for this context. Note in a server context some ciphers require the appropriate certificates. For example, an RSA cipher can only be chosen when an RSA certificate is available.

See also OpenSSL::Cipher and OpenSSL::Cipher.ciphers

               static VALUE
ossl_sslctx_set_ciphers(VALUE self, VALUE v)
    SSL_CTX *ctx;
    VALUE str, elem;
    int i;

    if (NIL_P(v))
        return v;
    else if (TYPE(v) == T_ARRAY) {
        str = rb_str_new(0, 0);
        for (i = 0; i < RARRAY_LEN(v); i++) {
            elem = rb_ary_entry(v, i);
            if (TYPE(elem) == T_ARRAY) elem = rb_ary_entry(elem, 0);
            elem = rb_String(elem);
            rb_str_append(str, elem);
            if (i < RARRAY_LEN(v)-1) rb_str_cat2(str, ":");
    } else {
        str = v;

    Data_Get_Struct(self, SSL_CTX, ctx);
        ossl_raise(eSSLError, "SSL_CTX is not initialized.");
        return Qnil;
    if (!SSL_CTX_set_cipher_list(ctx, RSTRING_PTR(str))) {
        ossl_raise(eSSLError, "SSL_CTX_set_cipher_list:");

    return v;
flush_sessions(time | nil) → self click to toggle source

Removes sessions in the internal cache that have expired at time.

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

    Data_Get_Struct(self, SSL_CTX, 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;
session_add(session) → true | false click to toggle source

Adds session to the session cache

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

    Data_Get_Struct(self, SSL_CTX, ctx);
    SafeGetSSLSession(arg, sess);

    return SSL_CTX_add_session(ctx, sess) == 1 ? Qtrue : Qfalse;
session_cache_mode → Integer click to toggle source

The current session cache mode.

               static VALUE
ossl_sslctx_get_session_cache_mode(VALUE self)
    SSL_CTX *ctx;

    Data_Get_Struct(self, SSL_CTX, ctx);

    return LONG2NUM(SSL_CTX_get_session_cache_mode(ctx));
session_cache_mode=(integer) → Integer click to toggle source

Sets the SSL session cache mode. Bitwise-or together the desired SESSION_CACHE_* constants to set. See SSL_CTX_set_session_cache_mode(3) for details.

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

    Data_Get_Struct(self, SSL_CTX, ctx);

    SSL_CTX_set_session_cache_mode(ctx, NUM2LONG(arg));

    return arg;
session_cache_size → Integer click to toggle source

Returns the current session cache size. Zero is used to represent an unlimited cache size.

               static VALUE
ossl_sslctx_get_session_cache_size(VALUE self)
    SSL_CTX *ctx;

    Data_Get_Struct(self, SSL_CTX, ctx);

    return LONG2NUM(SSL_CTX_sess_get_cache_size(ctx));
session_cache_size=(integer) → Integer click to toggle source

Sets the session cache size. Returns the previously valid session cache size. Zero is used to represent an unlimited session cache size.

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

    Data_Get_Struct(self, SSL_CTX, ctx);

    SSL_CTX_sess_set_cache_size(ctx, NUM2LONG(arg));

    return arg;
session_cache_stats → Hash click to toggle source

Returns a Hash containing the following keys:


Number of started SSL/TLS handshakes in server mode


Number of established SSL/TLS sessions in server mode


Number of start renegotiations in server mode


Number of sessions that were removed due to cache overflow


Number of successfully reused connections


Number of sessions proposed by clients that were not found in the cache


Number of sessions in the internal session cache


Number of sessions retrieved from the external cache in server mode


Number of started SSL/TLS handshakes in client mode


Number of established SSL/TLS sessions in client mode


Number of start renegotiations in client mode


Number of sessions proposed by clients that were found in the cache but had expired due to timeouts

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

    Data_Get_Struct(self, SSL_CTX, 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;
session_remove(session) → true | false click to toggle source

Removes session from the session cache

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

    Data_Get_Struct(self, SSL_CTX, ctx);
    SafeGetSSLSession(arg, sess);

    return SSL_CTX_remove_session(ctx, sess) == 1 ? Qtrue : Qfalse;
set_params(params={}) click to toggle source
               # File openssl/lib/openssl/ssl-internal.rb, line 77
def set_params(params={})
  params = DEFAULT_PARAMS.merge(params)
  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
      self.cert_store = DEFAULT_CERT_STORE
  return params
setup => Qtrue # first time click to toggle source
setup => nil # thereafter

This method is called automatically when a new SSLSocket is created. Normally you do not need to call this method (unless you are writing an extension in C).

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

    if(OBJ_FROZEN(self)) return Qnil;
    Data_Get_Struct(self, SSL_CTX, ctx);

#if !defined(OPENSSL_NO_DH)
    if (RTEST(ossl_sslctx_get_tmp_dh_cb(self))){
        SSL_CTX_set_tmp_dh_callback(ctx, ossl_tmp_dh_callback);
        SSL_CTX_set_tmp_dh_callback(ctx, ossl_default_tmp_dh_callback);
    SSL_CTX_set_ex_data(ctx, ossl_ssl_ex_ptr_idx, (void*)self);

    val = ossl_sslctx_get_cert_store(self);
         * WORKAROUND:
         *   X509_STORE can count references, but
         *   X509_STORE_free() doesn't care it.
         *   So we won't increment it but mark it by ex_data.
        store = GetX509StorePtr(val); /* NO NEED TO DUP */
        SSL_CTX_set_cert_store(ctx, store);
        SSL_CTX_set_ex_data(ctx, ossl_ssl_ex_store_p, (void*)1);

    val = ossl_sslctx_get_extra_cert(self);
        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 = ossl_sslctx_get_cert(self);
    cert = NIL_P(val) ? NULL : GetX509CertPtr(val); /* NO DUP NEEDED */
    val = ossl_sslctx_get_key(self);
    key = NIL_P(val) ? NULL : GetPKeyPtr(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 = ossl_sslctx_get_client_ca(self);
        if(TYPE(val) == T_ARRAY){
            for(i = 0; i < RARRAY_LEN(val); i++){
                client_ca = GetX509CertPtr(RARRAY_PTR(val)[i]);
                if (!SSL_CTX_add_client_CA(ctx, client_ca)){
                    /* Copies X509_NAME => FREE it. */
                    ossl_raise(eSSLError, "SSL_CTX_add_client_CA");
            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 = ossl_sslctx_get_ca_file(self);
    ca_file = NIL_P(val) ? NULL : StringValuePtr(val);
    val = ossl_sslctx_get_ca_path(self);
    ca_path = NIL_P(val) ? NULL : StringValuePtr(val);
    if(ca_file || ca_path){
        if (!SSL_CTX_load_verify_locations(ctx, ca_file, ca_path))
            rb_warning("can't set verify locations");

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

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

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

    val = ossl_sslctx_get_options(self);
    if(!NIL_P(val)) {
        SSL_CTX_set_options(ctx, NUM2LONG(val));
    else {
        SSL_CTX_set_options(ctx, SSL_OP_ALL);

    val = ossl_sslctx_get_sess_id_ctx(self);
    if (!NIL_P(val)){
        if (!SSL_CTX_set_session_id_context(ctx, (unsigned char *)RSTRING_PTR(val),
            ossl_raise(eSSLError, "SSL_CTX_set_session_id_context:");

    if (RTEST(rb_iv_get(self, "@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_iv_get(self, "@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_iv_get(self, "@session_remove_cb"))) {
        SSL_CTX_sess_set_remove_cb(ctx, ossl_sslctx_session_remove_cb);
        OSSL_Debug("SSL SESSION remove callback added");

    val = rb_iv_get(self, "@servername_cb");
    if (!NIL_P(val)) {
        SSL_CTX_set_tlsext_servername_callback(ctx, ssl_servername_cb);
        OSSL_Debug("SSL TLSEXT servername callback added");

    return Qtrue;
ssl_version = :TLSv1 click to toggle source
ssl_version = "SSLv23_client"

You can get a list of valid versions with OpenSSL::SSL::SSLContext::METHODS

               static VALUE
ossl_sslctx_set_ssl_version(VALUE self, VALUE ssl_method)
    SSL_METHOD *method = NULL;
    const char *s;
    int i;

    SSL_CTX *ctx;
    if(TYPE(ssl_method) == T_SYMBOL)
        s = rb_id2name(SYM2ID(ssl_method));
        s =  StringValuePtr(ssl_method);
    for (i = 0; i < numberof(ossl_ssl_method_tab); i++) {
        if (strcmp(ossl_ssl_method_tab[i].name, s) == 0) {
            method = ossl_ssl_method_tab[i].func();
    if (!method) {
        ossl_raise(rb_eArgError, "unknown SSL method `%s'.", s);
    Data_Get_Struct(self, SSL_CTX, ctx);
    if (SSL_CTX_set_ssl_version(ctx, method) != 1) {
        ossl_raise(eSSLError, "SSL_CTX_set_ssl_version:");

    return ssl_method;

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus