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