File: using_ssl.html

package info (click to toggle)
erlang-doc-html 1%3A10.b.1a-1
links: PTS
area: main
in suites: sarge
size: 22,488 kB
ctags: 9,933
sloc: erlang: 505; ansic: 323; perl: 61; sh: 45; makefile: 39
file content (207 lines) | stat: -rw-r--r-- 6,169 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
  <TITLE>Using the SSL application</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><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 <CODE>ssl</CODE> interface
module. 


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

<A NAME="2.1"><!-- Empty --></A>
<H3>2.1 The ssl Module</H3>

<P> The <CODE>ssl</CODE> module provides the user interface to the Erlang/OTP
SSL application. The interface functions provided are very similar
to those provided by the <CODE>gen_tcp</CODE> and <CODE>inet</CODE> modules. 


<P>Servers use the interface functions <CODE>listen</CODE> and
<CODE>accept</CODE>. The <CODE>listen</CODE> function specifies a TCP port
to to listen to, and each call to the <CODE>accept</CODE> function
establishes an incoming connection.


<P>Clients use the <CODE>connect</CODE> function which specifies the address 
and port of a server to connect to, and a successful call establishes
such a connection. 


<P>The <CODE>listen</CODE> and <CODE>connect</CODE> functions have almost all
the options that the corresponding functions in <CODE>gen_tcp/</CODE> have, 
but there are also additional options specific to the SSL protocol. 


<P>The most important SSL specific option is the <CODE>cacertfile</CODE>
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>The <CODE>certfile</CODE> 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>Similarly, the <CODE>keyfile</CODE> option points to a local file
containing the private key of the holder of the endpoint. If the
<CODE>certfile</CODE> 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 <CODE>certfile</CODE> option (a
certificate and a private key can thus coexist in the same file).


<P>The <CODE>verify</CODE> 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 <CODE>depth</CODE> 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>The <CODE>ciphers</CODE> option specifies which ciphers to use (a
string of colon separated cipher names). To obtain a list of
available ciphers, evaluate the <CODE>ssl:ciphers/0</CODE> function
(the SSL application has to be running). 

<A NAME="2.2"><!-- Empty --></A>
<H3>2.2 A Client-Server Example</H3>

<P>Here is a simple client server 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>
<CENTER>
<HR>
<SMALL>
Copyright &copy; 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>