Method: EventMachine::Connection#start_tls

Defined in:

lib/em/connection.rb

#start_tls(args = {}) ⇒ Object

TODO:

support passing an encryption parameter, which can be string or Proc, to get a passphrase

TODO:

support passing key material via raw strings or Procs that return strings instead of

Call #start_tls at any point to initiate TLS encryption on connected streams. The method is smart enough to know whether it should perform a server-side or a client-side handshake. An appropriate place to call #start_tls is in your redefined #post_init method, or in the #connection_completed handler for an outbound connection.

for encrypted private keys. just filenames.

Examples:

Using TLS with EventMachine

require 'rubygems'
require 'eventmachine'

module Handler
  def post_init
    start_tls(:private_key_file => '/tmp/server.key', :cert_chain_file => '/tmp/server.crt', :verify_peer => false)
  end
end

 EventMachine.run do
  EventMachine.start_server("127.0.0.1", 9999, Handler)
end

Parameters:

• args (Hash) (defaults to: {})

Options Hash (args):

• :cert_chain_file (String) — default: nil —

  local path of a readable file that contants a chain of X509 certificates in the [PEM format](en.wikipedia.org/wiki/Privacy_Enhanced_Mail), with the most-resolved certificate at the top of the file, successive intermediate certs in the middle, and the root (or CA) cert at the bottom.

• :private_key_file (String) — default: nil —

  local path of a readable file that must contain a private key in the [PEM format](en.wikipedia.org/wiki/Privacy_Enhanced_Mail).

• :verify_peer (Boolean) — default: false —

  indicates whether a server should request a certificate from a peer, to be verified by user code. If true, the #ssl_verify_peer callback on the EventMachine::Connection object is called with each certificate in the certificate chain provided by the peer. See documentation on #ssl_verify_peer for how to use this.

• :fail_if_no_peer_cert (Boolean) — default: false —

  Used in conjunction with verify_peer. If set the SSL handshake will be terminated if the peer does not provide a certificate.

• :cipher_list (String) — default: "ALL:!ADH:!LOW:!EXP:!DES-CBC3-SHA:@STRENGTH" —

  indicates the available SSL cipher values. Default value is “ALL:!ADH:!LOW:!EXP:!DES-CBC3-SHA:@STRENGTH”. Check the format of the OpenSSL cipher string at www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT.

• :ecdh_curve (String) — default: nil —

  The curve for ECDHE ciphers. See available ciphers with ‘openssl ecparam -list_curves’

• :dhparam (String) — default: nil —

  The local path of a file containing DH parameters for EDH ciphers in [PEM format](en.wikipedia.org/wiki/Privacy_Enhanced_Mail) See: ‘openssl dhparam’

• :ssl_version (Array) — default: TLSv1 TLSv1_1 TLSv1_2 —

  indicates the allowed SSL/TLS versions. Possible values are: SSLv2, SSLv3, TLSv1, TLSv1_1, TLSv1_2.

See Also:

• #ssl_verify_peer

# File 'lib/em/connection.rb', line 417

def start_tls args={}
  priv_key     = args[:private_key_file]
  cert_chain   = args[:cert_chain_file]
  verify_peer  = args[:verify_peer]
  sni_hostname = args[:sni_hostname]
  cipher_list  = args[:cipher_list]
  ssl_version  = args[:ssl_version]
  ecdh_curve   = args[:ecdh_curve]
  dhparam      = args[:dhparam]
  fail_if_no_peer_cert = args[:fail_if_no_peer_cert]

  [priv_key, cert_chain].each do |file|
    next if file.nil? or file.empty?
    raise FileNotFoundException,
    "Could not find #{file} for start_tls" unless File.exist? file
  end

  protocols_bitmask = 0
  if ssl_version.nil?
    protocols_bitmask |= EventMachine::EM_PROTO_TLSv1
    protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_1
    protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_2
  else
    [ssl_version].flatten.each do |p|
      case p.to_s.downcase
      when 'sslv2'
        protocols_bitmask |= EventMachine::EM_PROTO_SSLv2
      when 'sslv3'
        protocols_bitmask |= EventMachine::EM_PROTO_SSLv3
      when 'tlsv1'
        protocols_bitmask |= EventMachine::EM_PROTO_TLSv1
      when 'tlsv1_1'
        protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_1
      when 'tlsv1_2'
        protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_2
      else
        raise("Unrecognized SSL/TLS Protocol: #{p}")
      end
    end
  end

  EventMachine::set_tls_parms(@signature, priv_key || '', cert_chain || '', verify_peer, fail_if_no_peer_cert, sni_hostname || '', cipher_list || '', ecdh_curve || '', dhparam || '', protocols_bitmask)
  EventMachine::start_tls @signature
end