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. If both :cert_chain_file and :cert are used, BadCertParams will be raised.

• :cert (String) — default: nil —

  a string with the client certificate to use, complete with header and footer. If a cert chain is required, you will have to use the :cert_chain_file option. If both :cert_chain_file and :cert are used, BadCertParams will be raised.

• :private_key_file (String) — default: nil —

  local path of a readable file that must contain a private key in the PEM format. If both :private_key_file and :private_key are used, BadPrivateKeyParams will be raised. If the Private Key does not match the certificate, InvalidPrivateKey will be raised.

• :private_key (String) — default: nil —

  a string, complete with header and footer, that must contain a private key in the PEM format. If both :private_key_file and :private_key are used, BadPrivateKeyParams will be raised. If the Private Key does not match the certificate, InvalidPrivateKey will be raised.

• :private_key_pass (String) — default: nil —

  a string to use as password to decode :private_key or :private_key_file

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

• #ssl_verify_peer

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

def start_tls args={}
  priv_key_path   = args[:private_key_file]
  priv_key        = args[:private_key]
  priv_key_pass   = args[:private_key_pass]
  cert_chain_path = args[:cert_chain_file]
  cert            = args[:cert]
  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_path, cert_chain_path].each do |file|
    next if file.nil? or file.empty?
    raise FileNotFoundException,
    "Could not find #{file} for start_tls" unless File.exist? file
  end

  if !priv_key_path.nil? && !priv_key_path.empty? && !priv_key.nil? && !priv_key.empty?
    raise BadPrivateKeyParams, "Specifying both private_key and private_key_file not allowed"
  end

  if !cert_chain_path.nil? && !cert_chain_path.empty? && !cert.nil? && !cert.empty?
    raise BadCertParams, "Specifying both cert and cert_chain_file not allowed"
  end

  if (!priv_key_path.nil? && !priv_key_path.empty?) || (!priv_key.nil? && !priv_key.empty?)
    if (cert_chain_path.nil? || cert_chain_path.empty?) && (cert.nil? || cert.empty?)
      raise BadParams, "You have specified a private key to use, but not the related cert"
    end
  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
    if EventMachine.const_defined? :EM_PROTO_TLSv1_3
      protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_3
    end
  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
      when 'tlsv1_3'
        protocols_bitmask |= EventMachine::EM_PROTO_TLSv1_3
      else
        raise("Unrecognized SSL/TLS Protocol: #{p}")
      end
    end
  end

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