Class: OpenSSL::SSL::SSLSocket
- Includes:
- Buffering, SocketForwarder
- Defined in:
- ext/openssl/ossl_ssl.c,
ext/openssl/lib/openssl/ssl.rb
Constant Summary
Constants included from Buffering
Instance Attribute Summary collapse
-
#context ⇒ Object
readonly
The SSLContext object used in this connection.
-
#hostname ⇒ Object
Returns the value of attribute hostname.
-
#io ⇒ Object
(also: #to_io)
readonly
The underlying IO object.
-
#sync_close ⇒ Object
Whether to close the underlying socket as well, when the SSL/TLS connection is shut down.
Attributes included from Buffering
Class Method Summary collapse
-
.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).
Instance Method Summary collapse
-
#accept ⇒ self
Waits for a SSL/TLS client to initiate a handshake.
-
#accept_nonblock([options]) ⇒ self
Initiates the SSL/TLS handshake as a server in non-blocking manner.
-
#alpn_protocol ⇒ String | nil
Returns the ALPN protocol string that was finally selected by the server during the handshake.
-
#cert ⇒ nil
The X509 certificate for this socket endpoint.
-
#cipher ⇒ nil, Array
Returns the cipher suite actually used in the current session, or nil if no session has been established.
-
#client_ca ⇒ Array
Returns the list of client CAs.
-
#connect ⇒ self
Initiates an SSL/TLS handshake with a server.
-
#connect_nonblock([options]) ⇒ self
Initiates the SSL/TLS handshake as a client in non-blocking manner.
-
#export_keying_material(label, length) ⇒ String
Enables use of shared session key material in accordance with RFC 5705.
-
#finished_message ⇒ Object
Returns the last Finished message sent.
-
#initialize(*args) ⇒ Object
constructor
Creates a new SSL socket from io which must be a real IO object (not an IO-like object that responds to read/write).
-
#npn_protocol ⇒ String | nil
Returns the protocol string that was finally selected by the client during the handshake.
-
#peer_cert ⇒ nil
The X509 certificate for this socket’s peer.
-
#peer_cert_chain ⇒ Array?
The X509 certificate chain for this socket’s peer.
-
#peer_finished_message ⇒ Object
Returns the last Finished message received.
-
#pending ⇒ Integer
The number of bytes that are immediately available for reading.
-
#post_connection_check(hostname) ⇒ Object
call-seq: ssl.post_connection_check(hostname) -> true.
-
#session ⇒ Object
call-seq: ssl.session -> aSession.
-
#session=(session) ⇒ Object
Sets the Session to be used when the connection is established.
-
#session_reused? ⇒ Boolean
Returns
true
if a reused session was negotiated during the handshake. -
#ssl_version ⇒ String
Returns a String representing the SSL/TLS version that was negotiated for the connection, for example “TLSv1.2”.
-
#state ⇒ String
A description of the current connection state.
-
#sysclose ⇒ Object
call-seq: ssl.sysclose => nil.
-
#sysread(*args) ⇒ Object
Reads length bytes from the SSL connection.
-
#syswrite(string) ⇒ Integer
Writes string to the SSL connection.
-
#tmp_key ⇒ PKey?
Returns the ephemeral key used in case of forward secrecy cipher.
-
#verify_result ⇒ Integer
Returns the result of the peer certificates verification.
Methods included from SocketForwarder
#addr, #close_on_exec=, #close_on_exec?, #closed?, #do_not_reverse_lookup=, #fcntl, #fileno, #getsockopt, #local_address, #peeraddr, #remote_address, #setsockopt, #timeout, #timeout=, #wait, #wait_readable, #wait_writable
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
Methods included from Enumerable
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.
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 1655 1656 1657 1658 1659 1660 |
# File 'ext/openssl/ossl_ssl.c', line 1622
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);
// We don't need to trigger a write barrier because it's already
// an instance variable of this object.
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.
409 410 411 |
# File 'ext/openssl/lib/openssl/ssl.rb', line 409 def context @context end |
#hostname ⇒ Object
Returns the value of attribute hostname.
402 403 404 |
# File 'ext/openssl/lib/openssl/ssl.rb', line 402 def hostname @hostname end |
#io ⇒ Object (readonly) Also known as: to_io
The underlying IO object.
405 406 407 |
# File 'ext/openssl/lib/openssl/ssl.rb', line 405 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
.
413 414 415 |
# File 'ext/openssl/lib/openssl/ssl.rb', line 413 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
508 509 510 511 512 513 514 515 |
# File 'ext/openssl/lib/openssl/ssl.rb', line 508 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.
1893 1894 1895 1896 1897 1898 1899 |
# File 'ext/openssl/ossl_ssl.c', line 1893
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.
1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 |
# File 'ext/openssl/ossl_ssl.c', line 1923
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.
2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 |
# File 'ext/openssl/ossl_ssl.c', line 2512
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.
2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 |
# File 'ext/openssl/ossl_ssl.c', line 2175
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.
2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 |
# File 'ext/openssl/ossl_ssl.c', line 2274
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.
2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 |
# File 'ext/openssl/ossl_ssl.c', line 2468
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.
1846 1847 1848 1849 1850 1851 1852 |
# File 'ext/openssl/ossl_ssl.c', line 1846
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.
1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 |
# File 'ext/openssl/ossl_ssl.c', line 1876
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.
2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 |
# File 'ext/openssl/ossl_ssl.c', line 2534
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
2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 |
# File 'ext/openssl/ossl_ssl.c', line 2414
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);
}
|
#npn_protocol ⇒ String | nil
Returns the protocol string that was finally selected by the client during the handshake.
2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 |
# File 'ext/openssl/ossl_ssl.c', line 2488
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.
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 2201
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.
2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 |
# File 'ext/openssl/ossl_ssl.c', line 2227
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
2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 |
# File 'ext/openssl/ossl_ssl.c', line 2439
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.
2314 2315 2316 2317 2318 2319 2320 2321 2322 |
# File 'ext/openssl/ossl_ssl.c', line 2314
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.
435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 |
# File 'ext/openssl/lib/openssl/ssl.rb', line 435 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.
456 457 458 459 460 |
# File 'ext/openssl/lib/openssl/ssl.rb', line 456 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.
2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 |
# File 'ext/openssl/ossl_ssl.c', line 2346
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.
2330 2331 2332 2333 2334 2335 2336 2337 2338 |
# File 'ext/openssl/ossl_ssl.c', line 2330
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”.
2257 2258 2259 2260 2261 2262 2263 2264 2265 |
# File 'ext/openssl/ossl_ssl.c', line 2257
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.
2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 |
# File 'ext/openssl/ossl_ssl.c', line 2292
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.
422 423 424 425 426 |
# File 'ext/openssl/lib/openssl/ssl.rb', line 422 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.
2028 2029 2030 2031 2032 |
# File 'ext/openssl/ossl_ssl.c', line 2028
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.
2114 2115 2116 2117 2118 |
# File 'ext/openssl/ossl_ssl.c', line 2114
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.
2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 |
# File 'ext/openssl/ossl_ssl.c', line 2577
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.
2397 2398 2399 2400 2401 2402 2403 2404 2405 |
# File 'ext/openssl/ossl_ssl.c', line 2397
static VALUE
ossl_ssl_get_verify_result(VALUE self)
{
SSL *ssl;
GetSSL(self, ssl);
return LONG2NUM(SSL_get_verify_result(ssl));
}
|