<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Using SSL for Erlang Distribution</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/ssl-3.10.8.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Secure Socket Layer </strong><br><strong>User's Guide</strong><br><small>Version 3.10.8</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="The SSL Protocol" expanded="false">The SSL Protocol<ul>
<li><a href="ssl_protocol.html">
Top of chapter
</a></li>
<li title="SSL Connections"><a href="ssl_protocol.html#id2254451">SSL Connections</a></li>
<li title="Certificates"><a href="ssl_protocol.html#id2251968">Certificates</a></li>
<li title="Encryption Algorithms"><a href="ssl_protocol.html#id2259644">Encryption Algorithms</a></li>
<li title="SSL Handshake"><a href="ssl_protocol.html#id2252047">SSL Handshake</a></li>
<li title="Authentication"><a href="ssl_protocol.html#id2259261">Authentication</a></li>
</ul>
</li>
<li id="no" title="Using the SSL application" expanded="false">Using the SSL application<ul>
<li><a href="using_ssl.html">
Top of chapter
</a></li>
<li title="The ssl Module"><a href="using_ssl.html#id2255101">The ssl Module</a></li>
<li title="A Client-Server Example"><a href="using_ssl.html#id2258745">A Client-Server Example</a></li>
</ul>
</li>
<li id="no" title="PKIX Certificates" expanded="false">PKIX Certificates<ul>
<li><a href="pkix_certs.html">
Top of chapter
</a></li>
<li title="Introduction to Certificates"><a href="pkix_certs.html#id2251860">Introduction to Certificates</a></li>
<li title="PKIX Certificates"><a href="pkix_certs.html#id2252755">PKIX Certificates</a></li>
</ul>
</li>
<li id="no" title="Creating Certificates" expanded="false">Creating Certificates<ul>
<li><a href="create_certs.html">
Top of chapter
</a></li>
<li title="The openssl Command"><a href="create_certs.html#id2259452">The openssl Command</a></li>
<li title="An Example"><a href="create_certs.html#id2254962">An Example</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Using SSL for Erlang Distribution" expanded="true">Using SSL for Erlang Distribution<ul>
<li><a href="ssl_distribution.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ssl_distribution.html#id2252297">Introduction</a></li>
<li title="Building boot scripts including the SSL application"><a href="ssl_distribution.html#id2252373">Building boot scripts including the SSL application</a></li>
<li title="Specifying distribution module for net_kernel"><a href="ssl_distribution.html#id2252502">Specifying distribution module for net_kernel</a></li>
<li title="Specifying security options and other SSL options"><a href="ssl_distribution.html#id2257266">Specifying security options and other SSL options</a></li>
<li title="Setting up environment to always use SSL"><a href="ssl_distribution.html#id2257363">Setting up environment to always use SSL</a></li>
</ul>
</li>
<li id="no" title="Licenses" expanded="false">Licenses<ul>
<li><a href="licenses.html">
Top of chapter
</a></li>
<li title="OpenSSL License"><a href="licenses.html#id2257489">OpenSSL License</a></li>
<li title="SSLeay License"><a href="licenses.html#id2257546">SSLeay License</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>5 Using SSL for Erlang Distribution</h1>
<p>This chapter describes how the Erlang distribution can use
SSL to get additional verification and security.</p>
<h3><a name="id2252297">5.1
Introduction</a></h3>
<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 <span class="code">inet_tcp_dist</span> which is
included in the Kernel application. When starting an
Erlang node distributed, <span class="code">net_kernel</span> uses this module to
setup listen ports and connections. </p>
<p>In the SSL application there is an additional distribution
module, <span class="code">inet_ssl_dist</span> 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>
<ul>
<li>Building boot scripts including the SSL application</li>
<li>Specifying the distribution module for net_kernel</li>
<li>Specifying security options and other SSL options</li>
</ul>
<p>The rest of this chapter describes the above mentioned steps in
more detail.</p>
<h3><a name="id2252373">5.2
Building boot scripts including the SSL application</a></h3>
<p>Boot scripts are built using the <span class="code">systools</span> 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
<span class="code">releases/<OTP version>start_clean.rel</span>. 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>
<div class="example"><pre>
{release, {"OTP APN 181 01","P7A"}, {erts, "5.0"},
[{kernel,"2.5"},
{stdlib,"1.8.1"},
{ssl,"2.2.1"}]}. </pre></div>
<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
<span class="code">start_ssl.rel</span> in the current directory, a boot script
can be built like this:</p>
<div class="example"><pre>
1> systools:make_script("start_ssl",[]). </pre></div>
<p>There will now be a file <span class="code">start_ssl.boot</span> in the current
directory. To test the boot script, start Erlang with the
<span class="code">-boot</span> command line parameter specifying this boot script
(with its full path but without the <span class="code">.boot</span> suffix), in
Unix it could look like this:</p>
<p></p>
<div class="example"><pre>
$ 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> </pre></div>
<p>The <span class="code">whereis</span> 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 <span class="code">ebin</span> directory on the command
line. This is done with the command line option <span class="code">-pa</span>. 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 <span class="code">-pa</span> method is only recommended for testing
purposes.</p>
<h3><a name="id2252502">5.3
Specifying distribution module for net_kernel</a></h3>
<p>The distribution module for SSL is named <span class="code">inet_ssl_dist</span>
and is specified on the command line whit the <span class="code">-proto_dist</span>
option. The argument to <span class="code">-proto_dist</span> should be the module
name without the <span class="code">_dist</span> suffix, so this distribution
module is specified with <span class="code">-proto_dist inet_ssl</span> on the
command line.</p>
<p></p>
<p>Extending the command line from above gives us the following:</p>
<div class="example"><pre>
$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_ssl </pre></div>
<p>For the distribution to actually be started, we need to give
the emulator a name as well:</p>
<div class="example"><pre>
$ 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> </pre></div>
<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 <span class="code">application</span> nor <span class="code">code</span>
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
<span class="code">ERL_SSL_PORTPROGRAM_DIR</span> or with the command line option
<span class="code">-ssl_portprogram_dir</span>. The value should be the directory
where the <span class="code">ssl_esock</span> port program is located. Note that
this option is never needed in a normal Erlang installation.</p>
<h3><a name="id2257266">5.4
Specifying security options and other SSL options</a></h3>
<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 <span class="code">erl</span> 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 <strong>SSL option</strong> 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
<span class="code">certfile</span> can (and usually needs to) be specified as
<span class="code">client_certfile</span> and <span class="code">server_certfile</span>. The
<span class="code">client_certfile</span> is used when the distribution initiates a
connection to another node and the <span class="code">server_cerfile</span> is used
when accepting a connection from a remote node. </p>
<p>The command line argument for specifying the SSL options is named
<span class="code">-ssl_dist_opt</span> and should be followed by an even number of
SSL options/option values. The <span class="code">-ssl_dist_opt</span> 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>
<div class="example"><pre>
$ 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> </pre></div>
<p>A node started in this way will be fully functional, using SSL
as the distribution protocol.</p>
<h3><a name="id2257363">5.5
Setting up environment to always use SSL</a></h3>
<p>A convenient way to specify arguments to Erlang is to use the
<span class="code">ERL_FLAGS</span> 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>
<div class="example"><pre>
$ 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"]}] </pre></div>
<p>The <span class="code">init:get_arguments()</span> call verifies that the correct
arguments are supplied to the emulator. </p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1999-2010 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
13
>
i386
>
media
>
os
>
by-pkgid
>
f806c0f24240b25bde21a53f71766070
>
files
>
1407
