Class: OpenSSL::SSL::SSLSocket

Inherits:
Object
  • Object
show all
Includes:
Buffering, SocketForwarder
Defined in:
lib/openssl/ssl.rb,
ext/openssl/ossl_ssl.c

Constant Summary

Constants included from Buffering

Buffering::BLOCK_SIZE

Instance Attribute Summary collapse

Attributes included from Buffering

#sync

Class Method Summary collapse

Instance Method Summary collapse

Methods included from SocketForwarder

#addr, #closed?, #do_not_reverse_lookup=, #fcntl, #fileno, #getsockopt, #peeraddr, #setsockopt

Methods included from Buffering

#<<, #close, #each, #each_byte, #eof?, #flush, #getbyte, #getc, #gets, #print, #printf, #puts, #read, #read_nonblock, #readchar, #readline, #readlines, #readpartial, #ungetc, #write, #write_nonblock

Constructor Details

#new(io) ⇒ aSSLSocket #new(io, ctx) ⇒ aSSLSocket

Creates a new SSL socket from io which must be a real IO object (not an IO-like object that responds to read/write).

If ctx is provided the SSL Sockets initial params will be taken from the context.

The OpenSSL::Buffering module provides additional IO methods.

This method will freeze the SSLContext if one is provided; however, session management is still allowed in the frozen SSLContext.

Overloads:

  • #new(io) ⇒ aSSLSocket
  • #new(io, ctx) ⇒ aSSLSocket 


1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
 
# File 'ext/openssl/ossl_ssl.c', line 1618

static VALUE
ossl_ssl_initialize(int argc, VALUE *argv, VALUE self)
{
    VALUE io, v_ctx, verify_cb;
    SSL *ssl;
    SSL_CTX *ctx;

    TypedData_Get_Struct(self, SSL, &ossl_ssl_type, ssl);
    if (ssl)
	ossl_raise(eSSLError, "SSL already initialized");

    if (rb_scan_args(argc, argv, "11", &io, &v_ctx) == 1)
	v_ctx = rb_funcall(cSSLContext, rb_intern("new"), 0);

    GetSSLCTX(v_ctx, ctx);
    rb_ivar_set(self, id_i_context, v_ctx);
    ossl_sslctx_setup(v_ctx);

    if (rb_respond_to(io, rb_intern("nonblock=")))
	rb_funcall(io, rb_intern("nonblock="), 1, Qtrue);
    Check_Type(io, T_FILE);
    rb_ivar_set(self, id_i_io, io);

    ssl = SSL_new(ctx);
    if (!ssl)
	ossl_raise(eSSLError, NULL);
    RTYPEDDATA_DATA(self) = ssl;

    SSL_set_ex_data(ssl, ossl_ssl_ex_ptr_idx, (void *)self);
    SSL_set_info_callback(ssl, ssl_info_cb);
    verify_cb = rb_attr_get(v_ctx, id_i_verify_callback);
    SSL_set_ex_data(ssl, ossl_ssl_ex_vcb_idx, (void *)verify_cb);

    rb_call_super(0, NULL);

    return self;
}

Instance Attribute Details

#context ⇒ Object (readonly)

The SSLContext object used in this connection.



371
372
373
 
# File 'lib/openssl/ssl.rb', line 371

def context
  @context
end

#hostname ⇒ Object (readonly)

Returns the value of attribute hostname.



364
365
366
 
# File 'lib/openssl/ssl.rb', line 364

def hostname
  @hostname
end

#io ⇒ Object (readonly) Also known as: to_io

The underlying IO object.



367
368
369
 
# File 'lib/openssl/ssl.rb', line 367

def io
  @io
end

#sync_close ⇒ Object

Whether to close the underlying socket as well, when the SSL/TLS connection is shut down. This defaults to false.



375
376
377
 
# File 'lib/openssl/ssl.rb', line 375

def sync_close
  @sync_close
end

Class Method Details

.open(remote_host, remote_port, local_host = nil, local_port = nil, context: nil) ⇒ Object

call-seq:

open(remote_host, remote_port, local_host=nil, local_port=nil, context: nil)

Creates a new instance of SSLSocket. remotehost_ and remoteport_ are used to open TCPSocket. If localhost_ and localport_ are specified, then those parameters are used on the local end to establish the connection. If context is provided, the SSL Sockets initial params will be taken from the context.

Examples

sock = OpenSSL::SSL::SSLSocket.open('localhost', 443)
sock.connect # Initiates a connection to localhost:443

with SSLContext:

ctx = OpenSSL::SSL::SSLContext.new
sock = OpenSSL::SSL::SSLSocket.open('localhost', 443, context: ctx)
sock.connect # Initiates a connection to localhost:443 with SSLContext



470
471
472
473
474
475
476
477
 
# File 'lib/openssl/ssl.rb', line 470

def open(remote_host, remote_port, local_host=nil, local_port=nil, context: nil)
  sock = ::TCPSocket.open(remote_host, remote_port, local_host, local_port)
  if context.nil?
    return OpenSSL::SSL::SSLSocket.new(sock)
  else
    return OpenSSL::SSL::SSLSocket.new(sock, context)
  end
end

Instance Method Details

#accept ⇒ self

Waits for a SSL/TLS client to initiate a handshake.

Returns:

  • (self) 


1862
1863
1864
1865
1866
1867
1868
 
# File 'ext/openssl/ossl_ssl.c', line 1862

static VALUE
ossl_ssl_accept(VALUE self)
{
    ossl_ssl_setup(self);

    return ossl_start_ssl(self, SSL_accept, "SSL_accept", Qfalse);
}

#accept_nonblock([options]) ⇒ self

Initiates the SSL/TLS handshake as a server in non-blocking manner.

# emulates blocking accept
begin
  ssl.accept_nonblock
rescue IO::WaitReadable
  IO.select([s2])
  retry
rescue IO::WaitWritable
  IO.select(nil, [s2])
  retry
end

By specifying a keyword argument exception to false, you can indicate that accept_nonblock should not raise an IO::WaitReadable or IO::WaitWritable exception, but return the symbol :wait_readable or :wait_writable instead.

Returns:

  • (self) 


1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
 
# File 'ext/openssl/ossl_ssl.c', line 1892

static VALUE
ossl_ssl_accept_nonblock(int argc, VALUE *argv, VALUE self)
{
    VALUE opts;

    rb_scan_args(argc, argv, "0:", &opts);
    ossl_ssl_setup(self);

    return ossl_start_ssl(self, SSL_accept, "SSL_accept", opts);
}

#alpn_protocol ⇒ String | nil

Returns the ALPN protocol string that was finally selected by the server during the handshake.

Returns:

  • (String | nil) 


2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
 
# File 'ext/openssl/ossl_ssl.c', line 2483

static VALUE
ossl_ssl_alpn_protocol(VALUE self)
{
    SSL *ssl;
    const unsigned char *out;
    unsigned int outlen;

    GetSSL(self, ssl);

    SSL_get0_alpn_selected(ssl, &out, &outlen);
    if (!outlen)
	return Qnil;
    else
	return rb_str_new((const char *) out, outlen);
}

#cert ⇒ nil

The X509 certificate for this socket endpoint.

Returns:

  • (nil) 


2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
 
# File 'ext/openssl/ossl_ssl.c', line 2146

static VALUE
ossl_ssl_get_cert(VALUE self)
{
    SSL *ssl;
    X509 *cert = NULL;

    GetSSL(self, ssl);

    /*
     * Is this OpenSSL bug? Should add a ref?
     * TODO: Ask for.
     */
    cert = SSL_get_certificate(ssl); /* NO DUPs => DON'T FREE. */

    if (!cert) {
        return Qnil;
    }
    return ossl_x509_new(cert);
}

#cipher ⇒ nil, Array

Returns the cipher suite actually used in the current session, or nil if no session has been established.

Returns:

  • (nil, Array) 


2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
 
# File 'ext/openssl/ossl_ssl.c', line 2245

static VALUE
ossl_ssl_get_cipher(VALUE self)
{
    SSL *ssl;
    const SSL_CIPHER *cipher;

    GetSSL(self, ssl);
    cipher = SSL_get_current_cipher(ssl);
    return cipher ? ossl_ssl_cipher_to_ary(cipher) : Qnil;
}

#client_ca ⇒ Array

Returns the list of client CAs. Please note that in contrast to SSLContext#client_ca= no array of X509::Certificate is returned but X509::Name instances of the CA’s subject distinguished name.

In server mode, returns the list set by SSLContext#client_ca=. In client mode, returns the list of client CAs sent from the server.

Returns:

  • (Array) 


2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
 
# File 'ext/openssl/ossl_ssl.c', line 2439

static VALUE
ossl_ssl_get_client_ca_list(VALUE self)
{
    SSL *ssl;
    STACK_OF(X509_NAME) *ca;

    GetSSL(self, ssl);

    ca = SSL_get_client_CA_list(ssl);
    return ossl_x509name_sk2ary(ca);
}

#connect ⇒ self

Initiates an SSL/TLS handshake with a server.

Returns:

  • (self) 


1815
1816
1817
1818
1819
1820
1821
 
# File 'ext/openssl/ossl_ssl.c', line 1815

static VALUE
ossl_ssl_connect(VALUE self)
{
    ossl_ssl_setup(self);

    return ossl_start_ssl(self, SSL_connect, "SSL_connect", Qfalse);
}

#connect_nonblock([options]) ⇒ self

Initiates the SSL/TLS handshake as a client in non-blocking manner.

# emulates blocking connect
begin
  ssl.connect_nonblock
rescue IO::WaitReadable
  IO.select([s2])
  retry
rescue IO::WaitWritable
  IO.select(nil, [s2])
  retry
end

By specifying a keyword argument exception to false, you can indicate that connect_nonblock should not raise an IO::WaitReadable or IO::WaitWritable exception, but return the symbol :wait_readable or :wait_writable instead.

Returns:

  • (self) 


1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
 
# File 'ext/openssl/ossl_ssl.c', line 1845

static VALUE
ossl_ssl_connect_nonblock(int argc, VALUE *argv, VALUE self)
{
    VALUE opts;
    rb_scan_args(argc, argv, "0:", &opts);

    ossl_ssl_setup(self);

    return ossl_start_ssl(self, SSL_connect, "SSL_connect", opts);
}

#export_keying_material(label, length) ⇒ String

Enables use of shared session key material in accordance with RFC 5705.

Returns:

  • (String) 


2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
 
# File 'ext/openssl/ossl_ssl.c', line 2505

static VALUE
ossl_ssl_export_keying_material(int argc, VALUE *argv, VALUE self)
{
    SSL *ssl;
    VALUE str;
    VALUE label;
    VALUE length;
    VALUE context;
    unsigned char *p;
    size_t len;
    int use_ctx = 0;
    unsigned char *ctx = NULL;
    size_t ctx_len = 0;
    int ret;

    rb_scan_args(argc, argv, "21", &label, &length, &context);
    StringValue(label);

    GetSSL(self, ssl);

    len = (size_t)NUM2LONG(length);
    str = rb_str_new(0, len);
    p = (unsigned char *)RSTRING_PTR(str);
    if (!NIL_P(context)) {
	use_ctx = 1;
	StringValue(context);
	ctx = (unsigned char *)RSTRING_PTR(context);
	ctx_len = RSTRING_LEN(context);
    }
    ret = SSL_export_keying_material(ssl, p, len, (char *)RSTRING_PTR(label),
				     RSTRING_LENINT(label), ctx, ctx_len, use_ctx);
    if (ret == 0 || ret == -1) {
	ossl_raise(eSSLError, "SSL_export_keying_material");
    }
    return str;
}

#finished_message ⇒ Object

Returns the last Finished message sent



2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
 
# File 'ext/openssl/ossl_ssl.c', line 2385

static VALUE
ossl_ssl_get_finished(VALUE self)
{
    SSL *ssl;
    char sizer[1], *buf;
    size_t len;

    GetSSL(self, ssl);

    len = SSL_get_finished(ssl, sizer, 0);
    if (len == 0)
        return Qnil;

    buf = ALLOCA_N(char, len);
    SSL_get_finished(ssl, buf, len);
    return rb_str_new(buf, len);
}

#hostname=(hostname) ⇒ Object (readonly)

Sets the server hostname used for SNI. This needs to be set before SSLSocket#connect.



2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
 
# File 'ext/openssl/ossl_ssl.c', line 2339

static VALUE
ossl_ssl_set_hostname(VALUE self, VALUE arg)
{
    SSL *ssl;
    char *hostname = NULL;

    GetSSL(self, ssl);

    if (!NIL_P(arg))
	hostname = StringValueCStr(arg);

    if (!SSL_set_tlsext_host_name(ssl, hostname))
	ossl_raise(eSSLError, NULL);

    /* for SSLSocket#hostname */
    rb_ivar_set(self, id_i_hostname, arg);

    return arg;
}

#npn_protocol ⇒ String | nil

Returns the protocol string that was finally selected by the client during the handshake.

Returns:

  • (String | nil) 


2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
 
# File 'ext/openssl/ossl_ssl.c', line 2459

static VALUE
ossl_ssl_npn_protocol(VALUE self)
{
    SSL *ssl;
    const unsigned char *out;
    unsigned int outlen;

    GetSSL(self, ssl);

    SSL_get0_next_proto_negotiated(ssl, &out, &outlen);
    if (!outlen)
	return Qnil;
    else
	return rb_str_new((const char *) out, outlen);
}

#peer_cert ⇒ nil

The X509 certificate for this socket’s peer.

Returns:

  • (nil) 


2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
 
# File 'ext/openssl/ossl_ssl.c', line 2172

static VALUE
ossl_ssl_get_peer_cert(VALUE self)
{
    SSL *ssl;
    X509 *cert = NULL;
    VALUE obj;

    GetSSL(self, ssl);

    cert = SSL_get_peer_certificate(ssl); /* Adds a ref => Safe to FREE. */

    if (!cert) {
        return Qnil;
    }
    obj = ossl_x509_new(cert);
    X509_free(cert);

    return obj;
}

#peer_cert_chain ⇒ Array?

The X509 certificate chain for this socket’s peer.

Returns:

  • (Array, nil) 


2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
 
# File 'ext/openssl/ossl_ssl.c', line 2198

static VALUE
ossl_ssl_get_peer_cert_chain(VALUE self)
{
    SSL *ssl;
    STACK_OF(X509) *chain;
    X509 *cert;
    VALUE ary;
    int i, num;

    GetSSL(self, ssl);

    chain = SSL_get_peer_cert_chain(ssl);
    if(!chain) return Qnil;
    num = sk_X509_num(chain);
    ary = rb_ary_new2(num);
    for (i = 0; i < num; i++){
	cert = sk_X509_value(chain, i);
	rb_ary_push(ary, ossl_x509_new(cert));
    }

    return ary;
}

#peer_finished_message ⇒ Object

Returns the last Finished message received



2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
 
# File 'ext/openssl/ossl_ssl.c', line 2410

static VALUE
ossl_ssl_get_peer_finished(VALUE self)
{
    SSL *ssl;
    char sizer[1], *buf;
    size_t len;

    GetSSL(self, ssl);

    len = SSL_get_peer_finished(ssl, sizer, 0);
    if (len == 0)
        return Qnil;

    buf = ALLOCA_N(char, len);
    SSL_get_peer_finished(ssl, buf, len);
    return rb_str_new(buf, len);
}

#pending ⇒ Integer

The number of bytes that are immediately available for reading.

Returns:



2285
2286
2287
2288
2289
2290
2291
2292
2293
 
# File 'ext/openssl/ossl_ssl.c', line 2285

static VALUE
ossl_ssl_pending(VALUE self)
{
    SSL *ssl;

    GetSSL(self, ssl);

    return INT2NUM(SSL_pending(ssl));
}

#post_connection_check(hostname) ⇒ Object

call-seq:

ssl.post_connection_check(hostname) -> true

Perform hostname verification following RFC 6125.

This method MUST be called after calling #connect to ensure that the hostname of a remote peer has been verified.



397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
 
# File 'lib/openssl/ssl.rb', line 397

def post_connection_check(hostname)
  if peer_cert.nil?
    msg = "Peer verification enabled, but no certificate received."
    if using_anon_cipher?
      msg += " Anonymous cipher suite #{cipher[0]} was negotiated. " \
             "Anonymous suites must be disabled to use peer verification."
    end
    raise SSLError, msg
  end

  unless OpenSSL::SSL.verify_certificate_identity(peer_cert, hostname)
    raise SSLError, "hostname \"#{hostname}\" does not match the server certificate"
  end
  return true
end

#session ⇒ Object

call-seq:

ssl.session -> aSession

Returns the SSLSession object currently used, or nil if the session is not established.



418
419
420
421
422
 
# File 'lib/openssl/ssl.rb', line 418

def session
  SSL::Session.new(self)
rescue SSL::Session::SessionError
  nil
end

#session=(session) ⇒ Object

Sets the Session to be used when the connection is established.



2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
 
# File 'ext/openssl/ossl_ssl.c', line 2317

static VALUE
ossl_ssl_set_session(VALUE self, VALUE arg1)
{
    SSL *ssl;
    SSL_SESSION *sess;

    GetSSL(self, ssl);
    GetSSLSession(arg1, sess);

    if (SSL_set_session(ssl, sess) != 1)
        ossl_raise(eSSLError, "SSL_set_session");

    return arg1;
}

#session_reused? ⇒ Boolean

Returns true if a reused session was negotiated during the handshake.

Returns:

  • (Boolean) 


2301
2302
2303
2304
2305
2306
2307
2308
2309
 
# File 'ext/openssl/ossl_ssl.c', line 2301

static VALUE
ossl_ssl_session_reused(VALUE self)
{
    SSL *ssl;

    GetSSL(self, ssl);

    return SSL_session_reused(ssl) ? Qtrue : Qfalse;
}

#ssl_version ⇒ String

Returns a String representing the SSL/TLS version that was negotiated for the connection, for example “TLSv1.2”.

Returns:

  • (String) 


2228
2229
2230
2231
2232
2233
2234
2235
2236
 
# File 'ext/openssl/ossl_ssl.c', line 2228

static VALUE
ossl_ssl_get_version(VALUE self)
{
    SSL *ssl;

    GetSSL(self, ssl);

    return rb_str_new2(SSL_get_version(ssl));
}

#state ⇒ String

A description of the current connection state. This is for diagnostic purposes only.

Returns:

  • (String) 


2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
 
# File 'ext/openssl/ossl_ssl.c', line 2263

static VALUE
ossl_ssl_get_state(VALUE self)
{
    SSL *ssl;
    VALUE ret;

    GetSSL(self, ssl);

    ret = rb_str_new2(SSL_state_string(ssl));
    if (ruby_verbose) {
        rb_str_cat2(ret, ": ");
        rb_str_cat2(ret, SSL_state_string_long(ssl));
    }
    return ret;
}

#sysclose ⇒ Object

call-seq:

ssl.sysclose => nil

Sends “close notify” to the peer and tries to shut down the SSL connection gracefully.

If sync_close is set to true, the underlying IO is also closed.



384
385
386
387
388
 
# File 'lib/openssl/ssl.rb', line 384

def sysclose
  return if closed?
  stop
  io.close if sync_close
end

#sysread(length) ⇒ String #sysread(length, buffer) ⇒ Object

Reads length bytes from the SSL connection. If a pre-allocated buffer is provided the data will be written into it.

Overloads:

  • #sysread(length) ⇒ String

    Returns:

    • (String) 


1999
2000
2001
2002
2003
 
# File 'ext/openssl/ossl_ssl.c', line 1999

static VALUE
ossl_ssl_read(int argc, VALUE *argv, VALUE self)
{
    return ossl_ssl_read_internal(argc, argv, self, 0);
}

#syswrite(string) ⇒ Integer

Writes string to the SSL connection.

Returns:



2085
2086
2087
2088
2089
 
# File 'ext/openssl/ossl_ssl.c', line 2085

static VALUE
ossl_ssl_write(VALUE self, VALUE str)
{
    return ossl_ssl_write_internal(self, str, Qfalse);
}

#tmp_key ⇒ PKey?

Returns the ephemeral key used in case of forward secrecy cipher.

Returns:



2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
 
# File 'ext/openssl/ossl_ssl.c', line 2548

static VALUE
ossl_ssl_tmp_key(VALUE self)
{
    SSL *ssl;
    EVP_PKEY *key;

    GetSSL(self, ssl);
    if (!SSL_get_server_tmp_key(ssl, &key))
	return Qnil;
    return ossl_pkey_new(key);
}

#verify_result ⇒ Integer

Returns the result of the peer certificates verification. See verify(1) for error values and descriptions.

If no peer certificate was presented X509_V_OK is returned.

Returns:



2368
2369
2370
2371
2372
2373
2374
2375
2376
 
# File 'ext/openssl/ossl_ssl.c', line 2368

static VALUE
ossl_ssl_get_verify_result(VALUE self)
{
    SSL *ssl;

    GetSSL(self, ssl);

    return LONG2NUM(SSL_get_verify_result(ssl));
}