From 5b0a4180582921fe3b61b430f0c87d9a68ba6da8 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Thu, 30 Jun 2011 15:38:55 +0200 Subject: First fully working version --- lib/ssl/doc/src/ssl_distribution.xml | 209 ++++++++++++++++++----------------- lib/ssl/doc/src/ssl_protocol.xml | 16 +-- 2 files changed, 115 insertions(+), 110 deletions(-) (limited to 'lib/ssl/doc') 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 @@
- 20002010 + 20002011 Ericsson AB. All Rights Reserved. @@ -33,36 +33,32 @@

This chapter describes how the Erlang distribution can use SSL to get additional verification and security. - -

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.

Introduction

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 inet_tcp_dist which is included in the Kernel application. When starting an Erlang node distributed, net_kernel uses this module to setup listen ports and connections.

-

In the SSL application there is an additional distribution - module, inet_ssl_dist which can be used as an + +

In the SSL application there is an additional distribution + module, inet_tls_dist 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.

-

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.

+ +

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.

Setting up Erlang distribution over SSL involves some simple but necessary steps:

- + + Building boot scripts including the SSL application Specifying the distribution module for net_kernel Specifying security options and other SSL options @@ -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.

-

The simplest boot script possible includes only the Kernel + +

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 - start_clean.rel]]>. Copy that + /start_clean.rel]]>. 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.

An example .rel file with SSL added may look like this:

+ -{release, {"OTP APN 181 01","P7A"}, {erts, "5.0"}, - [{kernel,"2.5"}, - {stdlib,"1.8.1"}, - {ssl,"2.2.1"}]}. -

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.

-

Assuming the above .rel file is stored in a file - start_ssl.rel in the current directory, a boot script - can be built like this:

- -1> systools:make_script("start_ssl",[]). -

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

-

- + +

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.

+

Assuming the above .rel file is stored in a file + start_ssl.rel in the current directory, a boot script + can be built like this:

+ + + 1> systools:make_script("start_ssl",[]). + +

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

+

+ + whereis(ssl_server). -<0.32.0> ]]> +1> whereis(ssl_manager). +<0.41.0> ]]>

The whereis function call verifies that the SSL application is really started.

-

As an alternative to building a bootscript, one can explicitly - add the path to the ssl ebin directory on the command + +

As an alternative to building a bootscript, one can explicitly + add the path to the SSL ebin directory on the command line. This is done with the command line option -pa. 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 -pa method is only recommended for testing purposes.

+ +

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.
Specifying distribution module for net_kernel -

The distribution module for SSL is named inet_ssl_dist - and is specified on the command line whit the -proto_dist +

The distribution module for SSL is named inet_tls_dist + and is specified on the command line with the -proto_dist option. The argument to -proto_dist should be the module name without the _dist suffix, so this distribution - module is specified with -proto_dist inet_ssl on the + module is specified with -proto_dist inet_tls on the command line.

+

Extending the command line from above gives us the following:

-$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_ssl -

For the distribution to actually be started, we need to give - the emulator a name as well:

+$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls + +

For the distribution to actually be started, we need to give +the emulator a name as well:

-$ 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>

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).

-

When the SSL distribution starts, the OTP system is in its - early boot stage, why neither application nor code - 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 - ERL_SSL_PORTPROGRAM_DIR or with the command line option - -ssl_portprogram_dir. The value should be the directory - where the ssl_esock port program is located. Note that - this option is never needed in a normal Erlang installation.

- Specifying security options and other SSL options -

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).

-

+ Specifying SSL options

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.

+

On the erl 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 SSL option 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 - certfile can (and usually needs to) be specified as - client_certfile and server_certfile. The - client_certfile is used when the distribution initiates a - connection to another node and the server_certfile is used - when accepting a connection from a remote node.

-

The command line argument for specifying the SSL options is named - -ssl_dist_opt and should be followed by an even number of - SSL options/option values. The -ssl_dist_opt argument can - be repeated any number of times.

-

An example command line would now look something like this + SSL distribution will add when creating a socket.

+ +

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). + client_-prfixed options are used when the distribution initiates a + connection to another node and the server_-prefixed options are used + when accepting a connection from a remote node.

+ +

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.

+ +

Raw socket options such as packet and size must not be specified on + the command line

. + +

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

+ +

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):

-$ 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.

In a Unix (Bourne) shell it could look like this (line breaks for - readability):

+ readability, they should not be there when typed):

-$ 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"]}]

The init:get_arguments() call verifies that the correct arguments are supplied to the emulator.

- - diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml index ca5cc8bc7a..17268a634d 100644 --- a/lib/ssl/doc/src/ssl_protocol.xml +++ b/lib/ssl/doc/src/ssl_protocol.xml @@ -4,7 +4,7 @@
- 20032010 + 20032011 Ericsson AB. All Rights Reserved. @@ -25,18 +25,18 @@ ssl_protocol.xml
-

The erlang ssl application currently supports SSL 3.0 and TLS 1.0 +

The erlang SSL application currently supports SSL 3.0 and TLS 1.0 RFC 2246, and will in the future also support later versions of TLS. SSL 2.0 is not supported.

-

By default erlang ssl is run over the TCP/IP protocol even +

By default erlang SSL is run over the TCP/IP protocol even though you could plug in any other reliable transport protocol with the same API as gen_tcp.

If a client and server wants to use an upgrade mechanism, such as - defined by RFC2817, to upgrade a regular TCP/IP connection to an ssl - connection the erlang ssl API supports this. This can be useful for + defined by RFC2817, to upgrade a regular TCP/IP connection to an SSL + connection the erlang SSL API supports this. This can be useful for things such as supporting HTTP and HTTPS on the same port and implementing virtual hosting.

@@ -131,7 +131,7 @@ connections. Sessions are used to avoid the expensive negotiation of new security parameters for each connection."

-

Session data is by default kept by the ssl application in a +

Session data is by default kept by the SSL application in a memory storage hence session data will be lost at application restart or takeover. Users may define their own callback module to handle session data storage if persistent data storage is @@ -140,8 +140,8 @@ possible to configure the amount of time the session data should be saved.

-

Ssl clients will by default try to reuse an available session, - ssl servers will by default agree to reuse sessions when clients +

SSL clients will by default try to reuse an available session, + SSL servers will by default agree to reuse sessions when clients ask to do so.

-- cgit v1.2.3