Class: OpenSSL::SSL::SSLSocket

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

Overview

The following attributes are available but don’t show up in rdoc.

  • io, context, sync_close

Constant Summary

Constants included from Buffering

Buffering::BLOCK_SIZE

Instance Attribute Summary collapse

Attributes included from Buffering

#sync

Instance Method Summary collapse

Methods included from SocketForwarder

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

Methods included from Buffering

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

Constructor Details

#initialize(io, context = OpenSSL::SSL::SSLContext.new) ⇒ SSLSocket

call-seq:

SSLSocket.new(io) => aSSLSocket
SSLSocket.new(io, ctx) => aSSLSocket

Creates a new SSL socket from io which must be a real ruby 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.



279
 
# File 'lib/openssl/ssl.rb', line 279

def initialize(io, ctx = nil); raise NotImplementedError; end

Instance Attribute Details

#context ⇒ Object (readonly)

Returns the value of attribute context.



260
261
262
 
# File 'lib/openssl/ssl.rb', line 260

def context
  @context
end

#hostname ⇒ Object

Returns the value of attribute hostname.



257
258
259
 
# File 'lib/openssl/ssl.rb', line 257

def hostname
  @hostname
end

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

Returns the value of attribute io.



260
261
262
 
# File 'lib/openssl/ssl.rb', line 260

def io
  @io
end

#sync_close ⇒ Object

Returns the value of attribute sync_close.



261
262
263
 
# File 'lib/openssl/ssl.rb', line 261

def sync_close
  @sync_close
end

Instance Method Details

#accept ⇒ self

Waits for a SSL/TLS client to initiate a handshake. The handshake may be started after unencrypted data has been sent over the socket.



1373
1374
1375
1376
1377
1378
1379
 
# File 'ossl_ssl.c', line 1373

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 ‘exception: false`, the options hash allows you to indicate that accept_nonblock should not raise an IO::WaitReadable or IO::WaitWritable exception, but return the symbol :wait_readable or :wait_writable instead.



1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
 
# File 'ossl_ssl.c', line 1403

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

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



1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
 
# File 'ossl_ssl.c', line 1898

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

    ossl_ssl_data_get_struct(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.



1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
 
# File 'ossl_ssl.c', line 1627

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

    ossl_ssl_data_get_struct(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 ⇒ Array

The cipher being used for the current connection



1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
 
# File 'ossl_ssl.c', line 1725

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

    ossl_ssl_data_get_struct(self, ssl);

    cipher = (SSL_CIPHER *)SSL_get_current_cipher(ssl);

    return ossl_ssl_cipher_to_ary(cipher);
}

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



1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
 
# File 'ossl_ssl.c', line 1853

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

    ossl_ssl_data_get_struct(self, ssl);

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

#connect ⇒ self

Initiates an SSL/TLS handshake with a server. The handshake may be started after unencrypted data has been sent over the socket.



1325
1326
1327
1328
1329
1330
1331
 
# File 'ossl_ssl.c', line 1325

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 ‘exception: false`, the options hash allows you to indicate that connect_nonblock should not raise an IO::WaitReadable or IO::WaitWritable exception, but return the symbol :wait_readable or :wait_writable instead.



1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
 
# File 'ossl_ssl.c', line 1355

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

#npn_protocol ⇒ String

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



1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
 
# File 'ossl_ssl.c', line 1873

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

    ossl_ssl_data_get_struct(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.



1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
 
# File 'ossl_ssl.c', line 1653

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

    ossl_ssl_data_get_struct(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.



1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
 
# File 'ossl_ssl.c', line 1679

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

    ossl_ssl_data_get_struct(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;
}

#pending ⇒ Integer

The number of bytes that are immediately available for reading



1766
1767
1768
1769
1770
1771
1772
1773
1774
 
# File 'ossl_ssl.c', line 1766

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

    ossl_ssl_data_get_struct(self, ssl);

    return INT2NUM(SSL_pending(ssl));
}

#post_connection_check(hostname) ⇒ Object

Perform hostname verification after an SSL connection is established

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



305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/openssl/ssl.rb', line 305

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 



320
321
322
323
324
 
# File 'lib/openssl/ssl.rb', line 320

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.



1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
 
# File 'ossl_ssl.c', line 1804

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

/* why is ossl_ssl_setup delayed? */
    ossl_ssl_setup(self);

    ossl_ssl_data_get_struct(self, ssl);

    SafeGetSSLSession(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.



1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
 
# File 'ossl_ssl.c', line 1782

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

    ossl_ssl_data_get_struct(self, ssl);

    switch(SSL_session_reused(ssl)) {
    case 1: return Qtrue;
    case 0: return Qfalse;
    default:  ossl_raise(eSSLError, "SSL_session_reused");
    }

    UNREACHABLE;
}

#ssl_version ⇒ String

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



1709
1710
1711
1712
1713
1714
1715
1716
1717
 
# File 'ossl_ssl.c', line 1709

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

    ossl_ssl_data_get_struct(self, ssl);

    return rb_str_new2(SSL_get_version(ssl));
}

#state ⇒ String

A description of the current connection state.



1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
 
# File 'ossl_ssl.c', line 1744

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

    ossl_ssl_data_get_struct(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

Shuts down the SSL connection and prepares it for another connection.



294
295
296
297
298
 
# File 'lib/openssl/ssl.rb', line 294

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.



1497
1498
1499
1500
1501
 
# File 'ossl_ssl.c', line 1497

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.



1573
1574
1575
1576
1577
 
# File 'ossl_ssl.c', line 1573

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

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



1832
1833
1834
1835
1836
1837
1838
1839
1840
 
# File 'ossl_ssl.c', line 1832

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

    ossl_ssl_data_get_struct(self, ssl);

    return INT2FIX(SSL_get_verify_result(ssl));
}