User's Guide
Reference Manual
Release Notes
PDF
Top

Secure Socket Layer
User's Guide
Version 3.10.8

Expand All
Contract All

Chapters

• The SSL Protocol
  • Top of chapter
  • SSL Connections
  • Certificates
  • Encryption Algorithms
  • SSL Handshake
  • Authentication
• Using the SSL application
  • Top of chapter
  • The ssl Module
  • A Client-Server Example
• PKIX Certificates
  • Top of chapter
  • Introduction to Certificates
  • PKIX Certificates
• Creating Certificates
  • Top of chapter
  • The openssl Command
  • An Example
• Using SSL for Erlang Distribution
  • Top of chapter
  • Introduction
  • Building boot scripts including the SSL application
  • Specifying distribution module for net_kernel
  • Specifying security options and other SSL options
  • Setting up environment to always use SSL
• Licenses
  • Top of chapter
  • OpenSSL License
  • SSLeay License

2 Using the SSL application

Here we provide an introduction to using the Erlang/OTP SSL application, which is accessed through the ssl interface module.

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

2.1  The ssl Module

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

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

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

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

The most important SSL specific option is the cacertfile 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.

The certfile 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.

Similarly, the keyfile option points to a local file containing the private key of the holder of the endpoint. If the certfile 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 certfile option (a certificate and a private key can thus coexist in the same file).

The verify option specifies how the peer should be verified:

0

Do not verify the peer,

1

Verify peer,

2

Verify peer, fail the verification if the peer has no certificate.

The depth 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.

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

2.2  A Client-Server Example

Here is a simple client server example.