The R13B03 release.OTP_R13B03

1 files changed, 235 insertions, 0 deletions

diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml
new file mode 100644
index 0000000000..c743cd67a3
--- /dev/null
+++ b/lib/ssl/doc/src/ssl_distribution.xml
@@ -0,0 +1,235 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2000</year><year>2009</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 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_ssl_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 depends on how the connections are set up, one can
+      use key files or certificates to just get a crypted
+      connection. One can also make the SSL package verify the
+      certificates of other nodes to get additional security. 
+      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 SSL application with its current version number
+      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","P7A"}, {erts, "5.0"},
+ [{kernel,"2.5"},
+  {stdlib,"1.8.1"},
+  {ssl,"2.2.1"}]}.    </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_server).
+<0.32.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 really need not be started for the
+      distribution to come up, a primitive version of the ssl server
+      is started by the distribution module itself, so as long as the
+      primitive code server can reach the code, the distribution will
+      start. The <c>-pa</c> method is only recommended for testing
+      purposes.</p>
+  </section>
+
+  <section>
+    <title>Specifying distribution module for net_kernel</title>
+    <p>The distribution module for SSL is named <c>inet_ssl_dist</c>
+      and is specified on the command line whit 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_ssl</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_ssl    </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_ssl -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 certificates or key files are supplied
+      (see below).</p>
+    <p>When the SSL distribution starts, the OTP system is in its
+      early boot stage, why neither <c>application</c> nor <c>code</c>
+      are usable. As SSL needs to start a port program in this early
+      stage, it tries to determine the path to that program from the
+      primitive code loaders code path. If this fails, one need to
+      specify the directory where the port program resides. This can
+      be done either with an environment variable 
+      <c>ERL_SSL_PORTPROGRAM_DIR</c> or with the command line option
+      <c>-ssl_portprogram_dir</c>. The value should be the directory
+      where the <c>ssl_esock</c> port program is located. Note that
+      this option is never needed in a normal Erlang installation.</p>
+  </section>
+
+  <section>
+    <title>Specifying security options and other SSL options</title>
+    <p>For SSL to work, you either need certificate files or a
+      key file. Certificate files can be specified both when working as
+      client and as server (connecting or accepting). </p>
+    <p></p>
+    <p>On the <c>erl</c> command line one can specify options that the
+      ssl distribution will add when creation a socket. It is
+      mandatory to specify at least a key file or client and server
+      certificates. One can specify any <em>SSL option</em> on the
+      command line, but must not specify any socket options (like
+      packet size and such). The SSL options are listed in the
+      Reference Manual. The only difference between the
+      options in the reference manual and the ones that can be
+      specified to the distribution on the command line is that
+      <c>certfile</c> can (and usually needs to) be specified as
+      <c>client_certfile</c> and <c>server_certfile</c>. The
+      <c>client_certfile</c> is used when the distribution initiates a
+      connection to another node and the <c>server_cerfile</c> is used
+      when accepting a connection from a remote node. </p>
+    <p>The command line argument for specifying the SSL options is named 
+      <c>-ssl_dist_opt</c> and should be followed by an even number of
+      SSL options/option 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_ssl 
+  -ssl_dist_opt client_certfile "/home/me/ssl/erlclient.pem" 
+  -ssl_dist_opt server_certfile "/home/me/ssl/erlserver.pem" 
+  -ssl_dist_opt verify 1 depth 1     
+  -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):</p>
+    <code type="none">
+$ ERL_FLAGS="-boot \\"/home/me/ssl/start_ssl\\" -proto_dist inet_ssl 
+  -ssl_dist_opt client_certfile \\"/home/me/ssl/erlclient.pem\\" 
+  -ssl_dist_opt server_certfile \\"/home/me/ssl/erlserver.pem\\" 
+  -ssl_dist_opt verify 1 -ssl_dist_opt depth 1"
+$ 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_ssl"]},
+ {ssl_dist_opt,["client_certfile","/home/me/ssl/erlclient.pem"]},
+ {ssl_dist_opt,["server_certfile","/home/me/ssl/erlserver.pem"]},
+ {ssl_dist_opt,["verify","1"]},
+ {ssl_dist_opt,["depth","1"]},
+ {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>
+
+