diff options
Diffstat (limited to 'lib/ssl/doc/src/using_ssl.xml')
| -rw-r--r-- | lib/ssl/doc/src/using_ssl.xml | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml new file mode 100644 index 0000000000..ba74dcfef4 --- /dev/null +++ b/lib/ssl/doc/src/using_ssl.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Using the SSL application</title> + <prepared>Peter Högfeldt</prepared> + <docno></docno> + <date>2003-04-23</date> + <rev>PA2</rev> + <file>using_ssl.xml</file> + </header> + <p>Here we provide an introduction to using the Erlang/OTP SSL + application, which is accessed through the <c>ssl</c> interface + module. + </p> + <p>We also present example code in the Erlang module + <c>client_server</c>, also provided in the directory + <c>ssl-X.Y.Z/examples</c>, with source code in <c>src</c> and the + compiled module in <c>ebin</c> of that directory. + </p> + + <section> + <title>The ssl Module</title> + <p>The <c>ssl</c> module provides the user interface to the Erlang/OTP + SSL application. The interface functions provided are very similar + to those provided by the <c>gen_tcp</c> and <c>inet</c> modules. + </p> + <p>Servers use the interface functions <c>listen</c> and + <c>accept</c>. The <c>listen</c> function specifies a TCP port + to to listen to, and each call to the <c>accept</c> function + establishes an incoming connection. + </p> + <p>Clients use the <c>connect</c> function which specifies the address + and port of a server to connect to, and a successful call establishes + such a connection. + </p> + <p>The <c>listen</c> and <c>connect</c> functions have almost all + the options that the corresponding functions in <c>gen_tcp/</c> have, + but there are also additional options specific to the SSL protocol. + </p> + <p>The most important SSL specific option is the <c>cacertfile</c> + 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 <c>certfile</c> 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 preceding the establishment of a connection. + </p> + <p>Similarly, the <c>keyfile</c> option points to a local file + containing the private key of the holder of the endpoint. If the + <c>certfile</c> 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 <c>certfile</c> option (a + certificate and a private key can thus coexist in the same file). + </p> + <p>The <c>verify</c> option specifies how the peer should be verified: + </p> + <taglist> + <tag>0</tag> + <item>Do not verify the peer,</item> + <tag>1</tag> + <item>Verify peer,</item> + <tag>2</tag> + <item>Verify peer, fail the verification if the peer has no + certificate. </item> + </taglist> + <p>The <c>depth</c> 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 <c>ciphers</c> option specifies which ciphers to use (a + string of colon separated cipher names). To obtain a list of + available ciphers, evaluate the <c>ssl:ciphers/0</c> function + (the SSL application has to be running). + </p> + </section> + + <section> + <title>A Client-Server Example</title> + <p>Here is a simple client server example. + </p> + <codeinclude file="../../examples/src/client_server.erl" tag="" type="erl"></codeinclude> + </section> +</chapter> + + + |