module Ronin::Support::Network::TLS

@since 1.0.0

Public Class Methods

accept(min_version: 1, **kwargs, &block) click to toggle source

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

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {server_socket}.

@!macro server_kwargs

@yield [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.

@yieldparam [OpenSSL::SSL::SSLSocket] client

The newly connected client.

@return [nil]

@example

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

@example Using a self-signed certificate:

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

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 531
def self.accept(min_version: 1, **kwargs, &block)
  SSL.accept(min_version: min_version, **kwargs, &block)
end
banner(host,port, min_version: 1, **kwargs, &block) click to toggle source

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

@param [String] host

The host to connect to.

@param [Integer] port

The port to connect to.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {connect}.

@!macro connect_kwargs

@yield [banner]

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

@yieldparam [String] banner

The grabbed banner.

@return [String]

The grabbed banner.

@example

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

@api public

@since 1.1.0

connect(host,port, min_version: 1, **kwargs, &block) click to toggle source

Establishes a SSL connection.

@param [String] host

The host to connect to.

@param [Integer] port

The port to connect to.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {socket}.

@!macro connect_kwargs

@yield [tls_socket]

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

@yieldparam [OpenSSL::SSL::SSLSocket] tls_socket

The new SSL Socket.

@return [OpenSSL::SSL::SSLSocket, nil]

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

@example

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

@example

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

  sock.each_line { |line| puts line }
end

@see rubydoc.info/stdlib/openssl/OpenSSL/SSL/SSLSocket

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 203
def self.connect(host,port, min_version: 1, **kwargs, &block)
  SSL.connect(host,port, min_version: min_version, **kwargs, &block)
end
connect_and_send(data,host,port, min_version: 1, **kwargs, &block) click to toggle source

Creates a new SSL connection and sends the given data.

@param [String] data

The data to send through the connection.

@param [String] host

The host to connect to.

@param [Integer] port

The port to connect to.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {connect}.

@!macro connect_kwargs

@yield [tls_socket]

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

@yieldparam [OpenSSL::SSL::SSLSocket] tls_socket

The newly created SSL Socket.

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 237
def self.connect_and_send(data,host,port, min_version: 1, **kwargs, &block)
  SSL.connect_and_send(data,host,port, min_version: min_version, **kwargs, &block)
end
context(min_version: 1, **kwargs) click to toggle source

Creates a new TLS context.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {SSL.context}.

@!macro context_kwargs

@return [OpenSSL::SSL::SSLContext]

The newly created SSL Context.

@api semipublic

# File lib/ronin/support/network/tls.rb, line 83
def self.context(min_version: 1, **kwargs)
  SSL.context(min_version: min_version, **kwargs)
end
get_cert(host,port, min_version: 1, **kwargs) click to toggle source

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

@param [String] host

The host to connect to.

@param [Integer] port

The port to connect to.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {connect}.

@!macro connect_kwargs

@yield [tls_socket]

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

@return [OpenSSL::X509::Certificate]

The server's certificate.

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 266
def self.get_cert(host,port, min_version: 1, **kwargs)
  SSL.get_cert(host,port, min_version: min_version, **kwargs)
end
open?(host,port, min_version: 1, **kwargs) click to toggle source

Tests whether a remote SSLed TCP port is open.

@param [String] host

The host to connect to.

@param [Integer] port

The port to connect to.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {SSL.connect}.

@!macro connect_kwargs

@return [Boolean, nil]

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

@example

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

@example Using a timeout:

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

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 155
def self.open?(host,port, min_version: 1, **kwargs)
  SSL.open?(host,port, min_version: min_version, **kwargs)
end
send(data,host,port, min_version: 1, **kwargs) click to toggle source

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

@param [String] data

The data to send through the connection.

@param [String] host

The host to connect to.

@param [Integer] port

The port to connect to.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {connect}.

@!macro connect_kwargs

@return [true]

The data was successfully sent.

@example

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

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 342
def self.send(data,host,port, min_version: 1, **kwargs)
  SSL.send(data,host,port, min_version: min_version, **kwargs)
end
server(min_version: 1, **kwargs, &block) click to toggle source

Creates a new TLS server listening on a given host and port.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {context}.

@!macro server_kwargs

@yield [server]

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

@yieldparam [OpenSSL::SSL::SSLServer] server

The newly created SSL server.

@return [OpenSSL::SSL::SSLServer]

The newly created SSL server.

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 420
def self.server(min_version: 1, **kwargs, &block)
  SSL.server(min_version: min_version, **kwargs, &block)
end
server_loop(min_version: 1, **kwargs, &block) click to toggle source

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

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {server_socket}.

@!macro server_kwargs

@yield [client]

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

@yieldparam [OpenSSL::SSL::SSLSocket] client

A newly connected client.

@return [nil]

@example

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

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 487
def self.server_loop(min_version: 1, **kwargs, &block)
  SSL.server_loop(min_version: min_version, **kwargs, &block)
end
server_session(min_version: 1, **kwargs, &block) click to toggle source

Creates a new temporary TLS server listening on a given host and port.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {context}.

@!macro server_kwargs

@yield [server]

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

@yieldparam [OpenSSL::SSL::SSLServer] server

The newly created SSL server. Once the block has finished,
the server will be closed.

@return [OpenSSL::SSL::SSLServer]

The newly created SSL server.

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 449
def self.server_session(min_version: 1, **kwargs, &block)
  SSL.server_session(min_version: min_version, **kwargs, &block)
end
server_socket(socket, min_version: 1, **kwargs) click to toggle source

Accepts an TLS session from an existing TCP socket.

@param [TCPSocket] socket

The existing TCP socket.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {socket}.

@!macro server_context_kwargs

@return [OpenSSL::SSL::SSLSocket]

the new SSL Socket.

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 378
def self.server_socket(socket, min_version: 1, **kwargs)
  SSL.server_socket(socket, min_version: min_version, **kwargs)
end
socket(socket, min_version: 1, **kwargs) click to toggle source

Initiates an SSL session with an existing TCP socket.

@param [TCPSocket] socket

The existing TCP socket.

@param [1, 1.1, 1.2, 1.3, Symbol, nil] min_version

The minimum TLS version to use.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {SSL.context}.

@!macro context_kwargs

@return [OpenSSL::SSL::SSLSocket]

the new SSL Socket.

@api public

@since 1.1.0

# File lib/ronin/support/network/tls.rb, line 108
def self.socket(socket, min_version: 1, **kwargs)
  SSL.socket(socket,min_version: min_version, **kwargs)
end