<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2000</year><year>2011</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
    
    </legalnotice>

    <title>Using SSL for Erlang Distribution</title>
    <prepared>P Nyblom</prepared>
    <responsible></responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date>2003-04-01</date>
    <rev>B</rev>
    <file>ssl_distribution.xml</file>
  </header>
  <p>This chapter describes how the Erlang distribution can use 
    SSL to get additional verification and security.
  </p>

  <section>
    <title>Introduction</title>
    <p>The Erlang distribution can in theory use almost any connection
      based protocol as bearer. A module that implements the protocol
      specific parts of the connection setup is however needed. The
      default distribution module is <c>inet_tcp_dist</c> which is
      included in the Kernel application. When starting an
      Erlang node distributed, <c>net_kernel</c> uses this module to
      setup listen ports and connections. </p>

      <p>In the SSL application there is an additional distribution
      module, <c>inet_tls_dist</c> which can be used as an
      alternative. All distribution connections will be using SSL and
      all participating Erlang nodes in a distributed system must use
      this distribution module.</p>

      <p>The security level depends on the parameters provided to the
      SSL connection setup. Erlang node cookies are however always
      used, as they can be used to differentiate between two different
      Erlang networks.</p>
    <p>Setting up Erlang distribution over SSL involves some simple but
      necessary steps:</p>

      <list type="bulleted">
      <item>Building boot scripts including the SSL application</item>
      <item>Specifying the distribution module for net_kernel</item>
      <item>Specifying security options and other SSL options</item>
    </list>
    <p>The rest of this chapter describes the above mentioned steps in
      more detail.</p>
  </section>

  <section>
    <title>Building boot scripts including the SSL application</title>
    <p>Boot scripts are built using the <c>systools</c> utility in the
      SASL application. Refer to the SASL documentations
      for more information on systools. This is only an example of
      what can be done.</p>

      <p>The simplest boot script possible includes only the Kernel
      and STDLIB applications. Such a script is located in the
      Erlang distributions bin directory. The source for the script
      can be found under the Erlang installation top directory under
      <c><![CDATA[releases/<OTP version>/start_clean.rel]]></c>. Copy that
      script to another location (and preferably another name) 
      and add the applications crypto, public_key and SSL with their current version numbers
      after the STDLIB application.</p>
    <p>An example .rel file with SSL added may look like this:</p>

    <code type="none">
      {release, {"OTP  APN 181 01","R15A"}, {erts, "5.9"},
      [{kernel,"2.15"},
      {stdlib,"1.18"},
      {crypto, "2.0.3"},
      {public_key, "0.12"},
      {ssl, "5.0"}
      ]}.
   </code>

   <p>Note that the version numbers surely will differ in your system.
   Whenever one of the applications included in the script is
   upgraded, the script has to be changed.</p>
   <p>Assuming the above .rel file is stored in a file
   <c>start_ssl.rel</c> in the current directory, a boot script
   can be built like this:</p>

   <code type="none">
   1> systools:make_script("start_ssl",[]).    </code>

   <p>There will now be a file <c>start_ssl.boot</c> in the current
   directory. To test the boot script, start Erlang with the
   <c>-boot</c> command line parameter specifying this boot script
   (with its full path but without the <c>.boot</c> suffix), in
   Unix it could look like this:</p>
   <p></p>

   <code type="none"><![CDATA[
$ erl -boot /home/me/ssl/start_ssl
Erlang (BEAM) emulator version 5.0
 
Eshell V5.0  (abort with ^G)
1> whereis(ssl_manager).
<0.41.0>    ]]></code>
    <p>The <c>whereis</c> function call verifies that the SSL
      application is really started.</p>

      <p>As an alternative to building a bootscript, one can explicitly
      add the path to the SSL <c>ebin</c> directory on the command
      line. This is done with the command line option <c>-pa</c>. This
      works as the SSL application does not need to be started for the
      distribution to come up, as a clone of the SSL application is
      hooked into the kernel application, so as long as the
      SSL applications code can be reached, the distribution will
      start. The <c>-pa</c> method is only recommended for testing
      purposes.</p>

      <note><p>Note that the clone of the SSL application is necessary to
      enable the use of the SSL code in such an early bootstage as
      needed to setup the distribution, however this will make it
      impossible to soft upgrade the SSL application.</p></note>
  </section>

  <section>
    <title>Specifying distribution module for net_kernel</title>
    <p>The distribution module for SSL is named <c>inet_tls_dist</c>
      and is specified on the command line with the <c>-proto_dist</c>
      option. The argument to <c>-proto_dist</c> should be the module
      name without the <c>_dist</c> suffix, so this distribution
      module is specified with <c>-proto_dist inet_tls</c> on the
      command line.</p>
    <p></p>

    <p>Extending the command line from above gives us the following:</p>
    <code type="none">
$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls    </code>

<p>For the distribution to actually be started, we need to give
the emulator a name as well:</p>
    <code type="none">
$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls -sname ssl_test
Erlang (BEAM) emulator version 5.0 [source]
 
Eshell V5.0  (abort with ^G)
(ssl_test@myhost)1>     </code>
    <p>Note however that a node started in this way will refuse to talk
      to other nodes, as no ssl parameters are supplied
      (see below).</p>
  </section>

  <section>
    <title>Specifying SSL options</title> <p>For SSL to work, at least
    a public key and certificate needs to be specified for the server
    side.  In the following example the PEM-files consists of two
    entries the servers certificate and its private key.</p>

    <p>On the <c>erl</c> command line one can specify options that the
    SSL distribution will add when creating a socket.</p>

    <p>One can specify the simpler SSL options certfile, keyfile,
    password, cacertfile, verify, reuse_sessions,
    secure_renegotiate, depth, hibernate_after and ciphers (use old
    string format) by adding the prefix server_ or client_ to the
    option name. The server can also take the options dhfile and
    fail_if_no_peer_cert (also prefixed).
    <c>client_</c>-prfixed options are used when the distribution initiates a
    connection to another node and the <c>server_</c>-prefixed options are used
    when accepting a connection from a remote node. </p>

    <p> More complex options such as verify_fun are not available at
    the moment but a mechanism to handle such options may be added in
    a future release. </p>

    <p> Raw socket options such as packet and size must not be specified on
    the command line</p>.

    <p>The command line argument for specifying the SSL options is named
    <c>-ssl_dist_opt</c> and should be followed by pairs of
    SSL options and their values. The <c>-ssl_dist_opt</c> argument can
    be repeated any number of times.</p>

      <p>An example command line would now look something like this
      (line breaks in the command are for readability, 
      they should not be there when typed):</p>
    <code type="none">
$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls
  -ssl_dist_opt server_certfile "/home/me/ssl/erlserver.pem" 
  -ssl_dist_opt server_secure_renegotiate true client_secure_renegotiate true
  -sname ssl_test
Erlang (BEAM) emulator version 5.0 [source]
 
Eshell V5.0  (abort with ^G)
(ssl_test@myhost)1>     </code>
    <p>A node started in this way will be fully functional, using SSL
      as the distribution protocol.</p>
  </section>

  <section>
    <title>Setting up environment to always use SSL</title>
    <p>A convenient way to specify arguments to Erlang is to use the
      <c>ERL_FLAGS</c> environment variable. All the flags needed to
      use SSL distribution can be specified in that variable and will
      then be interpreted as command line arguments for all
      subsequent invocations of Erlang.</p>
    <p></p>
    <p>In a Unix (Bourne) shell it could look like this (line breaks for
      readability, they should not be there when typed):</p>
    <code type="none">
$ ERL_FLAGS="-boot /home/me/ssl/start_ssl -proto_dist inet_tls
  -ssl_dist_opt server_certfile /home/me/ssl/erlserver.pem
  -ssl_dist_opt server_secure_renegotiate true client_secure_renegotiate true"
$ export ERL_FLAGS
$ erl -sname ssl_test
Erlang (BEAM) emulator version 5.0 [source]
 
Eshell V5.0  (abort with ^G)
(ssl_test@myhost)1> init:get_arguments().
[{root,["/usr/local/erlang"]},
 {progname,["erl "]},
 {sname,["ssl_test"]},
 {boot,["/home/me/ssl/start_ssl"]},
 {proto_dist,["inet_tls"]},
 {ssl_dist_opt,["server_certfile","/home/me/ssl/erlserver.pem"]},
 {ssl_dist_opt,["server_secure_renegotiate","true",
                "client_secure_renegotiate","true"]
 {home,["/home/me"]}]    </code>
    <p>The <c>init:get_arguments()</c> call verifies that the correct
      arguments are supplied to the emulator. </p>
  </section>
</chapter>
