First fully working version

1 files changed, 107 insertions, 102 deletions

diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml
index 7bcc12eb5f..a2c7370ddc 100644
--- a/lib/ssl/doc/src/ssl_distribution.xml
+++ b/lib/ssl/doc/src/ssl_distribution.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2000</year><year>2010</year>
+      <year>2000</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -33,36 +33,32 @@
   </header>
   <p>This chapter describes how the Erlang distribution can use 
     SSL to get additional verification and security.
-
-    <note><p>Note this
-    documentation is written for the old ssl implementation and
-    will be updated for the new one once this functionality is
-    supported by the new implementation.</p></note>
   </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
+      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_ssl_dist</c> which can be used as an
+
+      <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 depends on how the connections are set up, one can
-      use key files or certificates to just get a encrypted
-      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>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">
+
+      <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>
@@ -77,122 +73,135 @@
       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
+
+      <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
+      <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
+      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","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[
+      {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_server).
-<0.32.0>    ]]></code>
+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
+
+      <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
+      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_ssl_dist</c>
-      and is specified on the command line whit the <c>-proto_dist</c>
+    <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_ssl</c> on the
+      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_ssl    </code>
-    <p>For the distribution to actually be started, we need to give
-      the emulator a name as well:</p>
+$ 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_ssl -sname ssl_test
+$ 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 certificates or key files are supplied
+      to other nodes, as no ssl parameters 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>
+    <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 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_certfile</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
+    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_renegotiation, 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_ssl 
-  -ssl_dist_opt client_certfile "/home/me/ssl/erlclient.pem" 
+$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls
   -ssl_dist_opt server_certfile "/home/me/ssl/erlserver.pem" 
-  -ssl_dist_opt verify 1 depth 1     
+  -ssl_dist_opt server_secure_renegotiation true client_secure_renegotiate true
   -sname ssl_test
 Erlang (BEAM) emulator version 5.0 [source]
  
@@ -211,12 +220,11 @@ Eshell V5.0  (abort with ^G)
       subsequent invocations of Erlang.</p>
     <p></p>
     <p>In a Unix (Bourne) shell it could look like this (line breaks for
-      readability):</p>
+      readability, they should not be there when typed):</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"
+$ 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_renegotiation true client_secure_renegotiate true"
 $ export ERL_FLAGS
 $ erl -sname ssl_test
 Erlang (BEAM) emulator version 5.0 [source]
@@ -227,15 +235,12 @@ Eshell V5.0  (abort with ^G)
  {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"]},
+ {proto_dist,["inet_tls"]},
  {ssl_dist_opt,["server_certfile","/home/me/ssl/erlserver.pem"]},
- {ssl_dist_opt,["verify","1"]},
- {ssl_dist_opt,["depth","1"]},
+ {ssl_dist_opt,["server_secure_renegotiation","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>
-
-