File: using_ssl.html

package info (click to toggle)
erlang-doc-html 1%3A12.b.3-dfsg-1
links: PTS
area: main
in suites: lenny
size: 27,712 kB
ctags: 13,052
sloc: erlang: 505; ansic: 323; perl: 61; makefile: 57; sh: 23
file content (242 lines) | stat: -rw-r--r-- 7,772 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- This document was generated using DocBuilder-0.9.8.4 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Using the SSL application</title>
  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
  <script type="text/javascript" src="../../../../doc/erlresolvelinks.js"></script>
  <style type="text/css">
<!--
    body          { font-family: Verdana, Arial, Helvetica, sans-serif }
    span.bold_code        { font-family: courier;font-weight: bold}
    span.code        { font-family: courier;font-weight: normal}

.note, .warning {
  border: solid black 1px;
  margin: 1em 3em;
}

.note .label {
  background: #30d42a;
  color: white;
  font-weight: bold;
  padding: 5px 10px;
}
.note .content {
  background: #eafeea;
  color: black;
  line-height: 120%;
  font-size: 90%;
  padding: 5px 10px;
}
.warning .label {
  background: #C00;
  color: white;
  font-weight: bold;
  padding: 5px 10px;
}
.warning .content {
  background: #FFF0F0;
  color: black;
  line-height: 120%;
  font-size: 90%;
  padding: 5px 10px;
}

    .example     { background-color:#eeeeff } 
    pre          { font-family: courier; font-weight: normal }
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </style>
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#FF00FF" alink="#FF0000">
<center>
<a href="http://www.ericsson.com/technology/opensource/erlang"><img border="0" alt="[Ericsson AB]" src="min_head.gif"/></a>
</center><a name="2"><!-- Empty --></a>
<h2>2 Using the SSL application</h2>

<p>Here we provide an introduction to using the Erlang/OTP SSL
application, which is accessed through the <span class="code">ssl</span> interface
module. 

</p>
<p>We also present example code in the Erlang module
<span class="code">client_server</span>, also provided in the directory
<span class="code">ssl-X.Y.Z/examples</span>, with source code in <span class="code">src</span> and the
compiled module in <span class="code">ebin</span> of that directory.

</p><a name="2.1"><!-- Empty --></a>
<h3>2.1 The ssl Module</h3>

<p>The <span class="code">ssl</span> module provides the user interface to the Erlang/OTP
SSL application. The interface functions provided are very similar
to those provided by the <span class="code">gen_tcp</span> and <span class="code">inet</span> modules. 

</p>
<p>Servers use the interface functions <span class="code">listen</span> and
<span class="code">accept</span>. The <span class="code">listen</span> function specifies a TCP port
to to listen to, and each call to the <span class="code">accept</span> function
establishes an incoming connection.

</p>
<p>Clients use the <span class="code">connect</span> function which specifies the address 
and port of a server to connect to, and a successful call establishes
such a connection. 

</p>
<p>The <span class="code">listen</span> and <span class="code">connect</span> functions have almost all
the options that the corresponding functions in <span class="code">gen_tcp/</span> have, 
but there are also additional options specific to the SSL protocol. 

</p>
<p>The most important SSL specific option is the <span class="code">cacertfile</span>
option which specifies a local file containing trusted CA
certificates which are and used for peer authentication. This
option is used by clients and servers in case they want to
authenticate their peers.

</p>
<p>The <span class="code">certfile</span> option specifies a local path to a file
containing the certificate of the holder of the connection
endpoint. In case of a server endpoint this option is mandatory
since the contents of the sever certificate is needed in the
the handshake preceeding the establishment of a connection. 

</p>
<p>Similarly, the <span class="code">keyfile</span> option points to a local file
containing the private key of the holder of the endpoint. If the
<span class="code">certfile</span> option is present, this option has to be
specified as well, unless the private key is provided in the
same file as specified by the <span class="code">certfile</span> option (a
certificate and a private key can thus coexist in the same file).

</p>
<p>The <span class="code">verify</span> option specifies how the peer should be verified:

</p>
<dl>

<dt>
0
</dt>

<dd>
Do not verify the peer,
</dd>

<dt>
1
</dt>

<dd>
Verify peer,
</dd>

<dt>
2
</dt>

<dd>
Verify peer, fail the verification if the peer has no 
certificate. 
</dd>

</dl>

<p>The <span class="code">depth</span> option specifies the maximum length of the
verification certificate chain. Depth = 0 means the peer
certificate, depth = 1 the CA certificate, depth = 2 the next CA
certificate etc. If the verification process does not find a
trusted CA certificate within the maximum length, the verification
fails.

</p>
<p>The <span class="code">ciphers</span> option specifies which ciphers to use (a
string of colon separated cipher names). To obtain a list of
available ciphers, evaluate the <span class="code">ssl:ciphers/0</span> function
(the SSL application has to be running). 

</p><a name="2.2"><!-- Empty --></a>
<h3>2.2 A Client-Server Example</h3>

<p>Here is a simple client server example. 

</p>
<div class="example"><pre>
%%% Purpose: Example of SSL client and server using example certificates.

-module(client_server).

-export([start/0, start/1, init_connect/1]).

start() -&#62;
    start([ssl, subject]).

start(CertOpts) -&#62;
    %% Start ssl application
    application:start(ssl),

    %% Always seed 
    ssl:seed(&#34;ellynatefttidppohjeh&#34;),

    %% Let the current process be the server that listens and accepts
    %% Listen
    {ok, LSock} = ssl:listen(0, mk_opts(listen)),
    {ok, LPort} = ssl:port(LSock),
    io:fwrite(&#34;Listen: port = ~w.~n&#34;, [LPort]),

    %% Spawn the client process that connects to the server
    spawn(?MODULE, init_connect, [{LPort, CertOpts}]),

    %% Accept
    {ok, ASock} = ssl:accept(LSock),
    io:fwrite(&#34;Accept: accepted.~n&#34;),
    {ok, Cert} = ssl:peercert(ASock, CertOpts),
    io:fwrite(&#34;Accept: peer cert:~n~p~n&#34;, [Cert]),
    io:fwrite(&#34;Accept: sending \&#34;hello\&#34;.~n&#34;),
    ssl:send(ASock, &#34;hello&#34;),
    {error, closed} = ssl:recv(ASock, 0),
    io:fwrite(&#34;Accept: detected closed.~n&#34;),
    ssl:close(ASock),
    io:fwrite(&#34;Listen: closing and terminating.~n&#34;),
    ssl:close(LSock),
    application:stop(ssl).


%% Client connect
init_connect({LPort, CertOpts}) -&#62;
    {ok, Host} = inet:gethostname(), 
    {ok, CSock} = ssl:connect(Host, LPort, mk_opts(connect)),
    io:fwrite(&#34;Connect: connected.~n&#34;),
    {ok, Cert} = ssl:peercert(CSock, CertOpts),
    io:fwrite(&#34;Connect: peer cert:~n~p~n&#34;, [Cert]),
    {ok, Data} = ssl:recv(CSock, 0),
    io:fwrite(&#34;Connect: got data: ~p~n&#34;, [Data]),
    io:fwrite(&#34;Connect: closing and terminating.~n&#34;),
    ssl:close(CSock).

mk_opts(listen) -&#62;
    mk_opts(&#34;server&#34;);
mk_opts(connect) -&#62;
    mk_opts(&#34;client&#34;);
mk_opts(Role) -&#62;
    Dir = filename:join([code:lib_dir(ssl), &#34;examples&#34;, &#34;certs&#34;, &#34;etc&#34;]),
    [{active, false}, 
     {verify, 2},
     {depth, 2},
     {cacertfile, filename:join([Dir, Role, &#34;cacerts.pem&#34;])}, 
     {certfile, filename:join([Dir, Role, &#34;cert.pem&#34;])}, 
     {keyfile, filename:join([Dir, Role, &#34;key.pem&#34;])}].


</pre></div>
<center>
<hr/>
<small>ssl 3.9<br/>
  Copyright &copy; 1991-2008
  <a href="http://www.ericsson.com/technology/opensource/erlang">Ericsson AB</a><br/>
</small>
</center></body>
</html>