Module: Ronin::Support::Network::SSL::Mixin

Includes:
TCP::Mixin
Included in:
Mixin, Ronin::Support::Network::SMTP::Mixin, TLS::Mixin
Defined in:
lib/ronin/support/network/ssl/mixin.rb

Overview

Provides helper methods for communicating with SSL-enabled services.

Instance Method Summary collapse

Methods included from 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

#ssl_accept(port: nil, host: nil, **kwargs) {|client| ... } ⇒ nil

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

Examples:

ssl_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
ssl_accept(port: 1337, cert: 'ssl.crt', key: 'ssl.key') do |client|
  client.puts 'lol'
end

Parameters:

  • port (Integer) (defaults to: nil)

    The local port to listen on.

  • host (String) (defaults to: nil)

    The host to bind to.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments for #ssl_server_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
  • :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:

  • 0.6.0



728
729
730
731
732
733
734
735
736
737
# File 'lib/ronin/support/network/ssl/mixin.rb', line 728

def ssl_accept(port: nil, host: nil,**kwargs)
  tcp_server_session(port: port, host: host, backlog: 1) do |server|
    client     = server.accept
    ssl_client = ssl_server_socket(client,options)
    ssl_client.accept

    yield ssl_client if block_given?
    ssl_client.close
  end
end

#ssl_banner(host, port, bind_host: nil, bind_port: nil, **kwargs) {|banner| ... } ⇒ String

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

Examples:

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

  • bind_host (String) (defaults to: nil)

    The local host to bind to.

  • bind_port (Integer) (defaults to: nil)

    The local port to bind to.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments for #ssl_connect.

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.

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:

  • 0.6.0



462
463
464
465
466
467
468
469
470
471
472
473
# File 'lib/ronin/support/network/ssl/mixin.rb', line 462

def ssl_banner(host,port, bind_host: nil, bind_port: nil, **kwargs)
  banner = nil

  ssl_connect(host,port, bind_host: bind_host,
                         bind_port: bind_port,
                         **kwargs) do |ssl_socket|
    banner = ssl_socket.readline.strip
  end

  yield banner if block_given?
  return banner
end

#ssl_cert(host, port, **kwargs) ⇒ Crypto::Cert

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.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments.

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:



394
395
396
397
398
399
400
# File 'lib/ronin/support/network/ssl/mixin.rb', line 394

def ssl_cert(host,port,**kwargs)
  socket = ssl_connect(host,port,**kwargs)
  cert   = Crypto::Cert(socket.peer_cert)

  socket.close
  return cert
end

#ssl_connect(host, port, bind_host: nil, bind_port: nil, **kwargs) {|ssl_socket| ... } ⇒ OpenSSL::SSL::SSLSocket?

Establishes a SSL connection.

Examples:

socket = ssl_connect('twitter.com',443)
ssl_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.

  • bind_host (String) (defaults to: nil)

    The local host to bind to.

  • bind_port (Integer) (defaults to: nil)

    The local port to bind to.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments for #ssl_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
  • :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:

  • (ssl_socket)

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

Yield Parameters:

  • ssl_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:



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
# File 'lib/ronin/support/network/ssl/mixin.rb', line 266

def ssl_connect(host,port, bind_host: nil, bind_port: nil, **kwargs)
  socket     = tcp_connect(host,port,bind_host: bind_host,
                                     bind_port: bind_port)
  ssl_socket = ssl_socket(socket,**kwargs)

  ssl_socket.hostname = host
  ssl_socket.connect

  if block_given?
    yield ssl_socket
    ssl_socket.close
  else
    return ssl_socket
  end
end

#ssl_connect_and_send(data, host, port, bind_host: nil, bind_port: nil, **kwargs) {|ssl_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.

  • bind_host (String) (defaults to: nil)

    The local host to bind to.

  • bind_port (Integer) (defaults to: nil)

    The local port to bind to.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments for #ssl_connect.

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.

Yields:

  • (ssl_socket)

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

Yield Parameters:

  • ssl_socket (OpenSSL::SSL::SSLSocket)

    The newly created SSL Socket.

Since:

  • 0.6.0



337
338
339
340
341
342
343
344
345
346
347
# File 'lib/ronin/support/network/ssl/mixin.rb', line 337

def ssl_connect_and_send(data,host,port, bind_host: nil,
                                         bind_port: nil,
                                         **kwargs)
  socket = ssl_connect(host,port, bind_host: bind_host,
                                  bind_port: bind_port,
                                  **kwargs)
  socket.write(data)

  yield socket if block_given?
  return socket
end

#ssl_context(**kwargs) ⇒ OpenSSL::SSL::SSLContext

Creates a new SSL Context.

Parameters:

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments.

Options Hash (**kwargs):

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

    The SSL version to use.

  • :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:

  • 0.6.0



73
74
75
# File 'lib/ronin/support/network/ssl/mixin.rb', line 73

def ssl_context(**kwargs)
  Network::SSL.context(**kwargs)
end

#ssl_open?(host, port, bind_host: nil, bind_port: nil, timeout: 5, **kwargs) ⇒ Boolean?

Tests whether a remote SSLed TCP port is open.

Examples:

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

Using a timeout:

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

Parameters:

  • host (String)

    The host to connect to.

  • port (Integer)

    The port to connect to.

  • bind_host (String) (defaults to: nil)

    The local host to bind to.

  • bind_port (Integer) (defaults to: nil)

    The local port to bind to.

  • timeout (Integer) (defaults to: 5)

    (5) The maximum time to attempt connecting.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments for #ssl_connect.

  • options (Hash)

    a customizable set of options

Options Hash (**kwargs):

  • :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:

  • 0.6.0



184
185
186
187
188
189
190
191
192
193
194
195
196
197
# File 'lib/ronin/support/network/ssl/mixin.rb', line 184

def ssl_open?(host,port, bind_host: nil, bind_port: nil, timeout: 5,
                                                         **kwargs)
  Timeout.timeout(timeout) do
    ssl_connect(host,port, bind_host: bind_host,
                           bind_port: bind_port,
                           **kwargs)
  end

  return true
rescue Timeout::Error
  return nil
rescue SocketError, SystemCallError
  return false
end

#ssl_send(data, host, port, bind_host: nil, bind_port: nil, **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"
ssl_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.

  • bind_host (String) (defaults to: nil)

    The local host to bind to.

  • bind_port (Integer) (defaults to: nil)

    The local port to bind to.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments for #ssl_connect.

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:

  • (true)

    The data was successfully sent.

Since:

  • 0.6.0



533
534
535
536
537
538
539
540
# File 'lib/ronin/support/network/ssl/mixin.rb', line 533

def ssl_send(data,host,port, bind_host: nil, bind_port: nil,**kwargs)
  ssl_connect(host,port, bind_host: bind_host,
                         bind_port: bind_port,**kwargs) do |socket|
    socket.write(data)
  end

  return true
end

#ssl_server_loop(port: nil, host: nil, backlog: 5, **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
ssl_server_loop(port: 1337, cert: 'ssl.crt', key: 'ssl.key') do |sock|
  sock.puts 'lol'
end

Parameters:

  • port (Integer) (defaults to: nil)

    The local port to listen on.

  • host (String) (defaults to: nil)

    The host to bind to.

  • backlog (Integer) (defaults to: 5)

    (5) The maximum backlog of pending connections.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments for #ssl_server_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
  • :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:

  • 0.6.0



650
651
652
653
654
655
656
657
658
659
660
661
# File 'lib/ronin/support/network/ssl/mixin.rb', line 650

def ssl_server_loop(port: nil, host: nil, backlog: 5, **kwargs)
  return tcp_server_session(port: port, host: host, backlog: backlog) do |server|
    loop do
      client     = server.accept
      ssl_client = ssl_server_socket(client,**kwargs)
      ssl_client.accept

      yield ssl_client if block_given?
      ssl_client.close
    end
  end
end

#ssl_server_socket(socket, key: Network::SSL.key, cert: Network::SSL.cert, **kwargs) ⇒ OpenSSL::SSL::SSLSocket

Accepts an SSL session from an existing TCP socket.

Parameters:

  • socket (TCPSocket)

    The existing TCP socket.

  • key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) (defaults to: Network::SSL.key)

    The RSA key to use for the SSL context.

  • cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) (defaults to: Network::SSL.cert)

    The X509 certificate to use for the SSL context.

  • kwargs (Hash{Symbol => Object})

    Additional keyword arguments for #ssl_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
  • :key_file (String)

    The path to the SSL .key file.

  • :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:

  • 0.6.0



582
583
584
585
586
# File 'lib/ronin/support/network/ssl/mixin.rb', line 582

def ssl_server_socket(socket, key:  Network::SSL.key,
                              cert: Network::SSL.cert,
                              **kwargs)
  return ssl_socket(socket, cert: cert, key: key, **kwargs)
end

#ssl_socket(socket, **kwargs) ⇒ OpenSSL::SSL::SSLSocket

Initiates an SSL session with an existing TCP socket.

Parameters:

  • socket (TCPSocket)

    The existing TCP socket.

  • 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::SSLSocket)

    The new SSL Socket.

Since:

  • 0.6.0



117
118
119
120
121
122
# File 'lib/ronin/support/network/ssl/mixin.rb', line 117

def ssl_socket(socket,**kwargs)
  ssl_socket = OpenSSL::SSL::SSLSocket.new(socket,ssl_context(**kwargs))

  ssl_socket.sync_close = true
  return ssl_socket
end