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

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


417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
# 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