User's Guide
Reference Manual
Release Notes
PDF
Top

Secure Socket Layer
User's Guide
Version 7.2

Expand All
Contract All

Chapters

- Introduction
  - Top of chapter
  - Purpose
  - Prerequisites
- TLS and its Predecessor, SSL
  - Top of chapter
  - Security Overview
  - Data Privacy and Integrity
  - Digital Certificates
  - Peer Authentication
  - TLS Sessions
- Using SSL API
  - Top of chapter
  - Setting up Connections
- Using SSL for Erlang Distribution
  - Top of chapter
  - Building Boot Scripts Including the ssl Application
  - Specifying Distribution Module for net_kernel
  - Specifying SSL Options
  - Setting up Environment to Always Use SSL

# 3 Using SSL API

To see relevant version information for ssl, call ssl:versions/0 .

To see all supported cipher suites, call ssl:cipher_suites(all) . The available cipher suites for a connection depend on your certificate. Specific cipher suites that you want your connection to use can also be specified. Default is to use the strongest available.

### 3.1 Setting up Connections

This section shows a small example of how to set up client/server connections using the Erlang shell. The returned value of the sslsocket is abbreviated with [...] as it can be fairly large and is opaque.

#### Minimal Example

Note

The minimal setup is not the most secure setup of SSL.

To set up client/server connections:

Step 1: Start the server side:

    1 server> ssl:start().
    ok

Step 2: Create an SSL listen socket:

    2 server> {ok, ListenSocket} =
    ssl:listen(9999, [{certfile, "cert.pem"}, {keyfile, "key.pem"},{reuseaddr, true}]).
    {ok,{sslsocket, [...]}}

Step 3: Do a transport accept on the SSL listen socket:

    3 server> {ok, Socket} = ssl:transport_accept(ListenSocket).
    {ok,{sslsocket, [...]}}

Step 4: Start the client side:

    1 client> ssl:start().
    ok

    2 client> {ok, Socket} = ssl:connect("localhost", 9999,  [], infinity).
    {ok,{sslsocket, [...]}}

Step 5: Do the SSL handshake:

    4 server> ok = ssl:ssl_accept(Socket).
    ok

Step 6: Send a message over SSL:

    5 server> ssl:send(Socket, "foo").
    ok

Step 7: Flush the shell message queue to see that the message was sent on the server side:

    3 client> flush().
    Shell got {ssl,{sslsocket,[...]},"foo"}
    ok

#### Upgrade Example

Note

To upgrade a TCP/IP connection to an SSL connection, the client and server must agree to do so. The agreement can be accomplished by using a protocol, for example, the one used by HTTP specified in RFC 2817.

To upgrade to an SSL connection:

Step 1: Start the server side:

    1 server> ssl:start().
    ok

Step 2: Create a normal TCP listen socket:

    2 server> {ok, ListenSocket} = gen_tcp:listen(9999, [{reuseaddr, true}]).
    {ok, #Port<0.475>}

Step 3: Accept client connection:

    3 server> {ok, Socket} = gen_tcp:accept(ListenSocket).
    {ok, #Port<0.476>}

Step 4: Start the client side:

    1 client> ssl:start().
    ok

    2 client> {ok, Socket} = gen_tcp:connect("localhost", 9999,  [], infinity).

Step 5: Ensure active is set to false before trying to upgrade a connection to an SSL connection, otherwise SSL handshake messages can be delivered to the wrong process:

    4 server> inet:setopts(Socket, [{active, false}]).
    ok

Step 6: Do the SSL handshake:

    5 server> {ok, SSLSocket} = ssl:ssl_accept(Socket, [{cacertfile, "cacerts.pem"},
    {certfile, "cert.pem"}, {keyfile, "key.pem"}]).
    {ok,{sslsocket,[...]}}

Step 7: Upgrade to an SSL connection. The client and server must agree upon the upgrade. The server must call ssl:accept/2 before the client calls ssl:connect/3.

    3 client>{ok, SSLSocket} = ssl:connect(Socket, [{cacertfile, "cacerts.pem"},
    {certfile, "cert.pem"}, {keyfile, "key.pem"}], infinity).
    {ok,{sslsocket,[...]}}

Step 8: Send a message over SSL:

    4 client> ssl:send(SSLSocket, "foo").
    ok

Step 9: Set active true on the SSL socket:

    4 server> ssl:setopts(SSLSocket, [{active, true}]).
    ok

Step 10: Flush the shell message queue to see that the message was sent on the client side:

    5 server> flush().
    Shell got {ssl,{sslsocket,[...]},"foo"}
    ok