Class: OpenSSL::SSL::SSLSocket
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
SocketForwarder,
::OpenSSL::Buffering,
Enumerable
|
|
Inherits: | Object |
Defined in: | ext/openssl/ossl_ssl.c, ext/openssl/lib/openssl/ssl.rb |
Overview
The following attributes are available but don't show up in rdoc.
-
io, context, sync_close
Constant Summary
::OpenSSL::Buffering - Included
Class Method Summary
- .new(io, ctx = nil) ⇒ SSLSocket constructor
Instance Attribute Summary
- #hostname rw
- #session rw
-
#session=(session) ⇒ session
rw
Sets the Session to be used when the connection is established.
- #sync_close rw
- #context readonly
- #io (also: #to_io) readonly
-
#session_reused? ⇒ Boolean
readonly
Returns true if a reused session was negotiated during the handshake.
-
#to_io
readonly
Alias for #io.
- #using_anon_cipher? ⇒ Boolean readonly private
SocketForwarder - Included
::OpenSSL::Buffering - Included
#sync | The “sync mode” of the |
#eof | Alias for Buffering#eof?. |
Instance Method Summary
-
#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
Returns the ALPN protocol string that was finally selected by the client during the handshake.
-
#cert ⇒ cert?
The X509 certificate for this socket endpoint.
-
#cipher ⇒ Array, ...
The cipher being used for the current connection.
-
#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.
-
#new(io) ⇒ SSLSocket
constructor
Creates a new ::OpenSSL::SSL socket from #io which must be a real ruby object (not an IO-like object that responds to read/write).
-
#npn_protocol ⇒ String
Returns the protocol string that was finally selected by the client during the handshake.
-
#peer_cert ⇒ cert?
The X509 certificate for this socket's peer.
-
#peer_cert_chain ⇒ Array, ...
The X509 certificate chain for this socket's peer.
-
#pending ⇒ Integer
The number of bytes that are immediately available for reading.
-
#post_connection_check(hostname)
Perform hostname verification after an ::OpenSSL::SSL connection is established.
-
#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 ⇒ nil
Sends “close notify” to the peer and tries to shut down the ::OpenSSL::SSL connection gracefully.
-
#sysread(length) ⇒ String
Reads
length
bytes from the ::OpenSSL::SSL connection. -
#syswrite(string) ⇒ Integer
Writes
string
to the ::OpenSSL::SSL connection. -
#verify_result ⇒ Integer
Returns the result of the peer certificates verification.
- #client_cert_cb private
- #session_get_cb private
- #session_new_cb private
-
#stop ⇒ nil
private
Sends “close notify” to the peer and tries to shut down the ::OpenSSL::SSL connection gracefully.
-
#sysread_nonblock(length) ⇒ String
private
A non-blocking version of #sysread.
-
#syswrite_nonblock(string) ⇒ Integer
private
Writes
string
to the ::OpenSSL::SSL connection in a non-blocking manner. - #tmp_dh_callback private
- #tmp_ecdh_callback private
SocketForwarder - Included
::OpenSSL::Buffering - Included
#<< | Writes |
#close | Closes the |
#each | Executes the block for every line in the stream where lines are separated by |
#each_byte | Calls the given block once for each byte in the stream. |
#each_line | Alias for Buffering#each. |
#eof? | Returns true if the stream is at file which means there is no more data to be read. |
#flush | Flushes buffered data to the |
#getc | Reads one character from the stream. |
#gets | Reads the next “line+ from the stream. |
#initialize | Creates an instance of OpenSSL's buffering IO module. |
Writes |
|
#printf | Formats and writes to the stream converting parameters under control of the format string. |
#puts | Writes |
#read | Reads |
#read_nonblock | Reads at most |
#readchar | Reads a one-character string from the stream. |
#readline | Reads a line from the stream which is separated by |
#readlines | Reads lines from the stream which are separated by |
#readpartial | Reads at most |
#ungetc | Pushes character |
#write | Writes |
#write_nonblock | Writes |
#consume_rbuff | Consumes |
#do_write | Writes |
#fill_rbuff | Fills the buffer from the underlying |
Constructor Details
.new(io, ctx = nil) ⇒ SSLSocket
# File 'ext/openssl/lib/openssl/ssl.rb', line 254
def initialize(io, ctx = nil); raise NotImplementedError; end
#new(io) ⇒ SSLSocket
#new(io, ctx) ⇒ SSLSocket
SSLSocket
#new(io, ctx) ⇒ SSLSocket
Creates a new ::OpenSSL::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 ::OpenSSL::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.
Instance Attribute Details
#context (readonly)
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 260
attr_reader :io, :context
#hostname (rw)
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 257
attr_accessor :hostname
#io (readonly) Also known as: #to_io
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 260
attr_reader :io, :context
#session (rw)
[ GitHub ]#session=(session) ⇒ session (rw)
Sets the Session to be used when the connection is established.
#session_reused? ⇒ Boolean
(readonly)
Returns true if a reused session was negotiated during the handshake.
#sync_close (rw)
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 261
attr_accessor :sync_close
#to_io (readonly)
Alias for #io.
# File 'ext/openssl/lib/openssl/ssl.rb', line 262
alias :to_io :io
#using_anon_cipher? ⇒ Boolean
(readonly, private)
[ GitHub ]
# File 'ext/openssl/lib/openssl/ssl.rb', line 331
def using_anon_cipher? ctx = OpenSSL::SSL::SSLContext.new ctx.ciphers = "aNULL" ctx.ciphers.include?(cipher) 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.
#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.
#alpn_protocol ⇒ String
Returns the ALPN protocol string that was finally selected by the client during the handshake.
#cert ⇒ cert?
The X509 certificate for this socket endpoint.
#cipher ⇒ Array
, ...
The cipher being used for the current connection
#client_ca ⇒ Array
, ...
Returns the list of client CAs. Please note that in contrast to SSLContext#client_ca= no array of ::OpenSSL::X509::Certificate is returned but ::OpenSSL::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.
#client_cert_cb (private)
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 337
def client_cert_cb @context.client_cert_cb end
#connect ⇒ self
Initiates an SSL/TLS handshake with a server. The handshake may be started after unencrypted data has been sent over the socket.
#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.
#npn_protocol ⇒ String
Returns the protocol string that was finally selected by the client during the handshake.
#peer_cert ⇒ cert?
The X509 certificate for this socket's peer.
#peer_cert_chain ⇒ Array
, ...
The X509 certificate chain for this socket's peer.
#pending ⇒ Integer
The number of bytes that are immediately available for reading
#post_connection_check(hostname)
Perform hostname verification after an ::OpenSSL::SSL connection is established
This method MUST be called after calling #connect to ensure that the hostname of a remote peer has been verified.
# File 'ext/openssl/lib/openssl/ssl.rb', line 308
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_get_cb (private)
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 353
def session_get_cb @context.session_get_cb end
#session_new_cb (private)
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 349
def session_new_cb @context.session_new_cb end
#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.
#stop ⇒ nil
(private)
Sends “close notify” to the peer and tries to shut down the ::OpenSSL::SSL connection gracefully.
#sysclose ⇒ nil
Sends “close notify” to the peer and tries to shut down the ::OpenSSL::SSL connection gracefully.
If sync_close is set to true
, the underlying IO is also closed.
# File 'ext/openssl/lib/openssl/ssl.rb', line 297
def sysclose return if closed? stop io.close if sync_close end
#sysread(length) ⇒ String
#sysread(length, buffer) ⇒ buffer
String
#sysread(length, buffer) ⇒ buffer
Reads length
bytes from the ::OpenSSL::SSL connection. If a pre-allocated buffer
is provided the data will be written into it.
#sysread_nonblock(length) ⇒ String
(private)
#sysread_nonblock(length, buffer) ⇒ buffer
#sysread_nonblock(length[, buffer [, opts]) ⇒ buffer
String
(private)
#sysread_nonblock(length, buffer) ⇒ buffer
#sysread_nonblock(length[, buffer [, opts]) ⇒ buffer
A non-blocking version of #sysread. Raises an SSLError if reading would block. If “exception: false” is passed, this method returns a symbol of :wait_readable
, :wait_writable
, or nil, rather than raising an exception.
Reads length
bytes from the ::OpenSSL::SSL connection. If a pre-allocated buffer
is provided the data will be written into it.
#syswrite(string) ⇒ Integer
Writes string
to the ::OpenSSL::SSL connection.
#syswrite_nonblock(string) ⇒ Integer (private)
Writes string
to the ::OpenSSL::SSL connection in a non-blocking manner. Raises an SSLError if writing would block.
#tmp_dh_callback (private)
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 341
def tmp_dh_callback @context.tmp_dh_callback || OpenSSL::PKey::DEFAULT_TMP_DH_CALLBACK end
#tmp_ecdh_callback (private)
[ GitHub ]# File 'ext/openssl/lib/openssl/ssl.rb', line 345
def tmp_ecdh_callback @context.tmp_ecdh_callback end
#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.