20032016 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Using SSL application API using_ssl.xml

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.

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

The minimal setup is not the most secure setup of SSL/TLS/DTLS.

To set up client/server connections:

Step 1: Start the server side:

1 server> ssl:start(). ok

Step 2: Create an TLS listen socket: (To run DTLS add the option {protocol, dtls})

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 TLS listen socket:

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

Step 4: Start the client side:

1 client> ssl:start(). ok

To run DTLS add the option {protocol, dtls} to third argument.

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

Step 5: Do the TLS handshake:

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

Step 6: Send a message over TLS:

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 - TLS only

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 TLS handshake:

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

Step 7: Upgrade to an TLS 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, TLSSocket} = ssl:connect(Socket, [{cacertfile, "cacerts.pem"}, {certfile, "cert.pem"}, {keyfile, "key.pem"}], infinity). {ok,{sslsocket,[...]}}

Step 8: Send a message over TLS:

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

Step 9: Set active true on the TLS socket:

4 server> ssl:setopts(TLSSocket, [{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