Module: Ronin::Support::Network::TLS::Mixin

Includes:

SSL::Mixin

Defined in:

lib/ronin/support/network/tls/mixin.rb

Overview

Provides helper methods for communicating with TLS-enabled services.

Since:

• 1.0.0

Instance Method Summary

• #tls_accept(version: 1.2, **kwargs) {|client| ... } ⇒ nil

  Creates a new SSL socket listening on a given host and port, accepts only one client and then stops listening.

• #tls_banner(host, port, version: 1.2, **kwargs) {|banner| ... } ⇒ String

  Reads the banner from the service running on the given host and port.

• #tls_cert(host, port, version: 1.2, **kwargs) {|tls_socket| ... } ⇒ OpenSSL::X509::Certificate

  Connects to the host and port and returns the server's certificate.

• #tls_connect(host, port, version: 1.2, **kwargs) {|tls_socket| ... } ⇒ OpenSSL::SSL::SSLSocket^?

  Establishes a SSL connection.

• #tls_connect_and_send(data, host, port, version: 1.2, **kwargs) {|tls_socket| ... } ⇒ Object

  Creates a new SSL connection and sends the given data.

• #tls_context(version: 1.2, **kwargs) ⇒ OpenSSL::SSL::SSLContext

  Creates a new TLS Context.

• #tls_open?(host, port, version: 1.2, **kwargs) ⇒ Boolean^?

  Tests whether a remote SSLed TCP port is open.

• #tls_send(data, host, port, version: 1.2, **kwargs) ⇒ true

  Connects to a specified host and port, sends the given data and then closes the connection.

• #tls_server_loop(version: 1.2, **kwargs) {|client| ... } ⇒ nil

  Creates a new SSL socket listening on a given host and port, accepting clients in a loop.

• #tls_server_socket(socket, version: 1.2, **kwargs) ⇒ OpenSSL::SSL::SSLSocket

  Accepts an SSL session from an existing TCP socket.

• #tls_socket(socket, version: 1.2, **kwargs) ⇒ OpenSSL::SSL::SSLSocket

  Initiates an SSL session with an existing TCP socket.

Methods included from SSL::Mixin

#ssl_accept, #ssl_banner, #ssl_cert, #ssl_connect, #ssl_connect_and_send, #ssl_context, #ssl_open?, #ssl_send, #ssl_server_loop, #ssl_server_socket, #ssl_socket

Methods included from Ronin::Support::Network::TCP::Mixin

#tcp_accept, #tcp_banner, #tcp_connect, #tcp_connect_and_send, #tcp_open?, #tcp_send, #tcp_server, #tcp_server_loop, #tcp_server_session

Instance Method Details

#tls_accept(version: 1.2, **kwargs) {|client| ... } ⇒ nil

Creates a new SSL socket listening on a given host and port, accepts only one client and then stops listening.

Examples:

tls_accept(1337) do |client|
  client.puts 'lol'
end

# $ openssl genrsa -out ssl.key 1024
# $ openssl req -new -key ssl.key -x509 -days 3653 -out ssl.crt
# $ cat ssl.key ssl.crt > ssl.pem
# $ chmod 600 ssl.key ssl.pem
tls_accept(port: 1337, cert: 'ssl.crt', key: 'ssl.key') do |client|
  client.puts 'lol'
end

Parameters:

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for #tls_server_socket.

Options Hash (**kwargs):

• :port (Integer) —

  The local port to listen on.

• :host (String) —

  The host to bind to.

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) — default: Network::SSL.key —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) — default: Network::SSL.cert —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Yields:

• (client) —

  The given block will be passed the newly connected client. After the block has finished, both the client and the server will be closed.

Yield Parameters:

• client (OpenSSL::SSL::SSLSocket) —

  The newly connected client.

Returns:

• (nil)

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 663

def tls_accept(version: 1.2, **kwargs, &block)
  ssl_accept(version: version, **kwargs, &block)
end

#tls_banner(host, port, version: 1.2, **kwargs) {|banner| ... } ⇒ String

Reads the banner from the service running on the given host and port.

Examples:

tls_banner('smtp.gmail.com',465)
# => "220 mx.google.com ESMTP c20sm3096959rvf.1"

Parameters:

• host (String) —

  The host to connect to.

• port (Integer) —

  The port to connect to.

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for #tls_connect.

Options Hash (**kwargs):

• :bind_host (String) —

  The local host to bind to.

• :bind_port (Integer) —

  The local port to bind to.

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Yields:

• (banner) —

  If a block is given, it will be passed the grabbed banner.

Yield Parameters:

• banner (String) —

  The grabbed banner.

Returns:

• (String) —

  The grabbed banner.

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 433

def tls_banner(host,port, version: 1.2, **kwargs, &block)
  ssl_banner(host,port, version: version, **kwargs, &block)
end

#tls_cert(host, port, version: 1.2, **kwargs) {|tls_socket| ... } ⇒ OpenSSL::X509::Certificate

Connects to the host and port and returns the server's certificate.

Parameters:

• host (String) —

  The host to connect to.

• port (Integer) —

  The port to connect to.

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for #tls_connect.

Options Hash (**kwargs):

• :bind_host (String) —

  The local host to bind to.

• :bind_port (Integer) —

  The local port to bind to.

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Yields:

• (tls_socket) —

  The given block will be passed the newly created SSL Socket.

Returns:

• (OpenSSL::X509::Certificate) —

  The server's certificate.

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 368

def tls_cert(host,port, version: 1.2, **kwargs)
  ssl_cert(host,port, version: version, **kwargs)
end

#tls_connect(host, port, version: 1.2, **kwargs) {|tls_socket| ... } ⇒ OpenSSL::SSL::SSLSocket^?

Establishes a SSL connection.

Examples:

socket = tls_connect('twitter.com',443)

tls_connect('twitter.com',443) do |sock|
  sock.write("GET / HTTP/1.1\n\r\n\r")

  sock.each_line { |line| puts line }
end

Parameters:

• host (String) —

  The host to connect to.

• port (Integer) —

  The port to connect to.

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for #tls_socket.

Options Hash (**kwargs):

• :bind_host (String) —

  The local host to bind to.

• :bind_port (Integer) —

  The local port to bind to.

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Yields:

• (tls_socket) —

  The given block will be passed the new SSL socket. Once the block returns the SSL socket will be closed.

Yield Parameters:

• tls_socket (OpenSSL::SSL::SSLSocket) —

  The new SSL Socket.

Returns:

• (OpenSSL::SSL::SSLSocket, nil) —

  The new SSL Socket. If a block is given, then nil will be returned.

See Also:

• http://rubydoc.info/stdlib/openssl/OpenSSL/SSL/SSLSocket

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 253

def tls_connect(host,port, version: 1.2, **kwargs, &block)
  ssl_connect(host,port, version: version, **kwargs, &block)
end

#tls_connect_and_send(data, host, port, version: 1.2, **kwargs) {|tls_socket| ... } ⇒ Object

Creates a new SSL connection and sends the given data.

Parameters:

• data (String) —

  The data to send through the connection.

• host (String) —

  The host to connect to.

• port (Integer) —

  The port to connect to.

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for #tls_connect.

Options Hash (**kwargs):

• :bind_host (String) —

  The local host to bind to.

• :bind_port (Integer) —

  The local port to bind to.

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Yields:

• (tls_socket) —

  The given block will be passed the newly created SSL Socket.

Yield Parameters:

• tls_socket (OpenSSL::SSL::SSLSocket) —

  The newly created SSL Socket.

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 313

def tls_connect_and_send(data,host,port, version: 1.2, **kwargs, &block)
  ssl_connect_and_send(data,host,port, version: version, **kwargs, &block)
end

#tls_context(version: 1.2, **kwargs) ⇒ OpenSSL::SSL::SSLContext

Creates a new TLS Context.

Parameters:

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for SSL.context.

Options Hash (**kwargs):

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Returns:

• (OpenSSL::SSL::SSLContext) —

  The newly created SSL Context.

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 69

def tls_context(version: 1.2, **kwargs)
  ssl_context(version: version, **kwargs)
end

#tls_open?(host, port, version: 1.2, **kwargs) ⇒ Boolean^?

Tests whether a remote SSLed TCP port is open.

Examples:

tls_open?('www.bankofamerica.com',443)

Using a timeout:

tls_open?('example.com',80, timeout: 5)
# => nil

Parameters:

• host (String) —

  The host to connect to.

• port (Integer) —

  The port to connect to.

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for SSL::Mixin#ssl_connect.

• options (Hash) —

  a customizable set of options

Options Hash (**kwargs):

• :bind_host (String) —

  The local host to bind to.

• :bind_port (Integer) —

  The local port to bind to.

• :timeout (Integer) — default: 5 —

  The maximum time to attempt connecting.

• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Returns:

• (Boolean, nil) —

  Specifies whether the remote SSLed TCP port is open. If the connection was not accepted, nil will be returned.

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 179

def tls_open?(host,port, version: 1.2, **kwargs)
  ssl_open?(host,port, version: version, **kwargs)
end

#tls_send(data, host, port, version: 1.2, **kwargs) ⇒ true

Connects to a specified host and port, sends the given data and then closes the connection.

Examples:

buffer = "GET /#{'A' * 4096}\n\r"
tls_send(buffer,'victim.com',443)
# => true

Parameters:

• data (String) —

  The data to send through the connection.

• host (String) —

  The host to connect to.

• port (Integer) —

  The port to connect to.

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for #tls_connect.

Options Hash (**kwargs):

• :bind_host (String) —

  The local host to bind to.

• :bind_port (Integer) —

  The local port to bind to.

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Returns:

• (true) —

  The data was successfully sent.

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 496

def tls_send(data,host,port, version: 1.2, **kwargs)
  ssl_send(data,host,port, version: version, **kwargs)
end

#tls_server_loop(version: 1.2, **kwargs) {|client| ... } ⇒ nil

Creates a new SSL socket listening on a given host and port, accepting clients in a loop.

Examples:

# $ openssl genrsa -out ssl.key 1024
# $ openssl req -new -key ssl.key -x509 -days 3653 -out ssl.crt
# $ cat ssl.key ssl.crt > ssl.pem
# $ chmod 600 ssl.key ssl.pem
tls_server_loop(port: 1337, cert: 'ssl.crt', key: 'ssl.key') do |sock|
  sock.puts 'lol'
end

Parameters:

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for #tls_server_socket.

Options Hash (**kwargs):

• :port (Integer) —

  The local port to listen on.

• :host (String) —

  The host to bind to.

• :backlog (Integer) — default: 5 —

  The maximum backlog of pending connections.

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) — default: Network::SSL.key —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) — default: Network::SSL.cert —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Yields:

• (client) —

  The given block will be passed the newly connected client. After the block has finished, the client will be closed.

Yield Parameters:

• client (OpenSSL::SSL::SSLSocket) —

  A newly connected client.

Returns:

• (nil)

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 593

def tls_server_loop(version: 1.2, **kwargs, &block)
  ssl_server_loop(version: 1.2, **kwargs, &block)
end

#tls_server_socket(socket, version: 1.2, **kwargs) ⇒ OpenSSL::SSL::SSLSocket

Accepts an SSL session from an existing TCP socket.

Parameters:

• socket (TCPSocket) —

  The existing TCP socket.

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for #tls_socket.

Options Hash (**kwargs):

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once

Returns:

• (OpenSSL::SSL::SSLSocket) —

  The new SSL Socket.

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 526

def tls_server_socket(socket, version: 1.2, **kwargs)
  ssl_server_socket(socket, version: version, **kwargs)
end

#tls_socket(socket, version: 1.2, **kwargs) ⇒ OpenSSL::SSL::SSLSocket

Initiates an SSL session with an existing TCP socket.

Parameters:

• socket (TCPSocket) —

  The existing TCP socket.

• version (1, 1.1, 1.2, String, Symbol, nil) (defaults to: 1.2) —

  The TLS version to use.

• kwargs (Hash{Symbol => Object}) —

  Additional keyword arguments for SSL::Mixin#ssl_context.

Options Hash (**kwargs):

• :verify (Symbol, Boolean) —

  Specifies whether to verify the SSL certificate. May be one of the following:

  • :none
  • :peer
  • :fail_if_no_peer_cert
  • :client_once
• :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

  The RSA key to use for the SSL context.

• :key_file (String) —

  The path to the SSL .key file.

• :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

  The X509 certificate to use for the SSL context.

• :cert_file (String) —

  The path to the SSL .crt file.

• :ca_bundle (String) —

  Path to the CA certificate file or directory.

Returns:

• (OpenSSL::SSL::SSLSocket) —

  The new SSL Socket.

Since:

• 1.0.0

# File 'lib/ronin/support/network/tls/mixin.rb', line 114

def tls_socket(socket, version: 1.2, **kwargs)
  ssl_socket(socket,version: version, **kwargs)
end