aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc/src/ssl_distribution.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssl/doc/src/ssl_distribution.xml')
-rw-r--r--lib/ssl/doc/src/ssl_distribution.xml235
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>
+
+