This class wraps an existing IO object and provides it SSL/TLS methods. This is only intended for servers that accept SSL/TLS connections.
Disables compression for a given SSL context, potentially resulting in reduced memory usage. This is identical to the OpenSSL::SSL::OP_NO_COMPRESSION constant that appears in Ruby 1.9.3. Not all versions of OpenSSL support this feature.
provides access to the underlying IO object, used internally by IO.select and Kgio.poll
Kgio::SSL.compression = false source
Setting this to false
disables compression globally within the
process. Other values are currently not supported, but may be in the
future. This affects /ALL/ OpenSSL connections within the process; OpenSSL
currently (1.0.0d) does not provide a way to enable/disable compression on
a per-context or per-connection basis.
Disabling compression can significantly reduce memory usage of idle connections.
Newer versions of OpenSSL supports the Kgio::SSL::OP_NO_COMPRESSION constant which allows disabling compression on a per-SSLContext basis. OpenSSL::SSL::OP_NO_COMPRESSION should also be supported in future versions of Ruby (1.9.3+).
Kgio::SSL.new(io, ssl_ctx) source
Wraps the existing io
object with the given
OpenSSL::SSL::Context ssl_ctx
.
kgio_ssl.closed? -> true or false source
Returns true if the kgio_ssl (and associated IO object) is completely closed, false otherwise.
kgio_ssl.compression -> nil or Symbol source
Returns the name of the compression used for a given connection as a
Symbol. Typical return values are :"zlib compression" or :"run length
compression" or nil
if no compression is not used.
kgio_ssl.compression? -> true or false source
Returns whether or not compression is active for the given Kgio::SSL session.
kgio_ssl.expansion -> nil or Symbol source
Returns the name of the expansion used for a given connection as a Symbol.
Typical return values are :"zlib compression" or :"run length compression"
or nil
if no expansion is not used.
kgio_ssl.expansion? -> true or false source
Returns whether or not expansion is active for the given Kgio::SSL session.
kgio_ssl.kgio_addr -> String or nil source
Returns a string representing the IP address of an accepted socket. This is forwarded to the underlying IO object, assuming it is an Kgio::Socket. If Kgio::SSL is used to wrap a non-Kgio::Socket object, this will raise NoMethodError
kgio_close (limit = 30) source
Synchronously closes the SSL connection, waiting up
to limit
seconds for an orderly shutdown before doing a hard
shutdown.
Returns nil
on success, will raise IOError if descriptor is
already closed.
kgio_peek (maxlen, buffer = "") source
See Kgio::PipeMethods#kgio_peek
kgio_read (maxlen, buffer = "") source
See Kgio::PipeMethods#kgio_read
kgio_read! (maxlen, buffer = "") source
See Kgio::PipeMethods#kgio_read!
kgio_ssl.kgio_tryclose source
returns nil
on success returns :wait_readable
or
:wait_writable
if the operation is in progress returns
false
on failure
kgio_ssl.kgio_trypeek(maxlen) -> buffer kgio_ssl.kgio_trypeek(maxlen, buffer) -> buffer source
Retrieves at most maxlen bytes from the SSL socket, but preserving it for future peeks or reads. Returns with a newly allocated buffer, or may reuse an existing buffer if supplied.
Returns nil on EOF.
Returns :wait_readable or :wait_writable if EAGAIN is encountered.
kgio_ssl.kgio_tryread(maxlen, buffer = "") -> buffer source
Reads at most maxlen bytes from the stream socket. Returns with a newly allocated buffer, or may reuse an existing buffer if supplied.
Returns nil on EOF.
Returns :wait_readable or :wait_writable if EAGAIN is encountered.
kgio_ssl.kgio_trysendfile(in_io, offset=0, count=nil) source
Returns:
Integer on success (number of bytes written)
nil on EOF
:wait_readable or :wait_writable if blocked
This API matches the IO#trysendfile in the sendfile RubyGem (except
:wait_readable
may be returned).
Unlike the equivalent C sendfile() function, this never modifies the offset
of in_io
, even if offset
is unspecified.
kgio_ssl.kgio_trywrite(str) source
Returns nil if the write was completed in full.
Returns a String containing the unwritten portion if EAGAIN was encountered, but some portion was successfully written.
Returns :wait_writable or :wait_readable if EAGAIN is encountered and nothing was written.
kgio_write (string) source
See Kgio::PipeMethods#kgio_write
kgio_ssl.peer_cert => cert or nil source
Returns the peer certificate for this Kgio::SSL object (for client sockets)
kgio_ssl.session -> OpenSSL::SSL::SSLSession source
Returns the SSLSession object associated with the given Kgio::SSL object
kgio_ssl.session_reused? -> true or false source
Returns whether or not the session was reused.
kgio_ssl.ssl_cipher -> String source
Returns the name of the cipher used in the connection as a frozen string.
ssl_client_cert () source
Returns the client certificate in PEM format in a format suitable for including in HTTP headers Raises NoMethodError if client did not send a peer certificate This matches the nginx variable of the same name.
ssl_client_i_dn () source
Returns the issuer Distinguished Name of the client peer certificate Raises NoMethodError if client did not send a peer certificate This matches the nginx variable of the same name.
ssl_client_raw_cert () source
Returns the client certificate in PEM format. Raises NoMethodError if client did not send a peer certificate This matches the nginx variable of the same name.
ssl_client_s_dn () source
Returns the subject Distinguished Name of the client peer certificate Raises NoMethodError if client did not send a peer certificate This matches the nginx variable of the same name.
ssl_client_serial () source
Returns the SSL client certificate serial number as a hexadecimal string Raises NoMethodError if client did not send a peer certificate This matches the nginx variable of the same name.
kgio_ssl.ssl_client_verify -> "SUCCESS", "NONE", or "FAILED" source
Returns "SUCCESS" if client verification failed, "NONE" if no peer certificate was provided, and "FAILED" if certificate verification failed.
This matches the $ssl_client_verify variable supported by nginx.
kgio_ssl.ssl_protocol -> "SSLv2", "SSLv3", or "TLSv1" source
Returns the name of the protocol version of a connection as a frozen string. May return "unknown" if no connection has been established.
ssl_session_id () source
Returns a hex-encoded string representing the SSL session ID This matches the nginx variable of the same name.