Class: OpenSSL::SSL::SSLSocket

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

Constant Summary

Constants included from Buffering

Buffering::BLOCK_SIZE

Instance Attribute Summary

Attributes included from Buffering

#sync

Class Method Summary collapse

Instance Method Summary collapse

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, #initialize, #print, #printf, #puts, #read, #read_nonblock, #readchar, #readline, #readlines, #readpartial, #ungetc, #write, #write_nonblock

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. remote_host and remote_port are used to open TCPSocket. If local_host and local_port 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



542
543
544
545
546
547
548
549
 
# File 'lib/openssl/ssl.rb', line 542

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

#close_read ⇒ Object

Close the stream for reading. This method is ignored by OpenSSL as there is no reasonable way to implement it, but exists for compatibility with IO.



473
474
475
476
 
# File 'lib/openssl/ssl.rb', line 473

def close_read
  # Unsupported and ignored.
  # Just don't read any more.
end

#close_write ⇒ Object

Closes the stream for writing. The behavior of this method depends on the version of OpenSSL and the TLS protocol in use.

  • Sends a 'close_notify' alert to the peer.
  • Does not wait for the peer's 'close_notify' alert in response.

In TLS 1.2 and earlier:

  • On receipt of a 'close_notify' alert, responds with a 'close_notify' alert of its own and close down the connection immediately, discarding any pending writes.

Therefore, on TLS 1.2, this method will cause the connection to be completely shut down. On TLS 1.3, the connection will remain open for reading only.



492
493
494
 
# File 'lib/openssl/ssl.rb', line 492

def close_write
  stop
end

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



428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/openssl/ssl.rb', line 428

def post_connection_check(hostname)
  # if connect already verified this hostname (via verify_hostname), skip;
  # avoids double-verification in libraries that call post_connection_check
  if defined?(@verified_hostname) && @verified_hostname == hostname
    @verified_hostname = nil
    return true
  end

  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.



464
465
466
467
468
 
# File 'lib/openssl/ssl.rb', line 464

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

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



415
416
417
418
419
 
# File 'lib/openssl/ssl.rb', line 415

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