From 1776467988178ff24376499747fed836b1765e1d Mon Sep 17 00:00:00 2001 From: xsipewe Date: Mon, 16 Mar 2015 14:18:41 +0100 Subject: ssl: Editorial updates --- lib/ssl/doc/src/using_ssl.xml | 101 ++++++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 49 deletions(-) (limited to 'lib/ssl/doc/src/using_ssl.xml') diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml index cce388d02a..e3ebca9410 100644 --- a/lib/ssl/doc/src/using_ssl.xml +++ b/lib/ssl/doc/src/using_ssl.xml @@ -21,126 +21,129 @@ - Using the SSL API + Using SSL API + + + + + + + using_ssl.xml - -
- General information -

To see relevant version information for ssl you can - call ssl:versions/0

+

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

-

To see all supported cipher suites - call ssl:cipher_suites/0. Note that available cipher suites - for a connection will depend on your certificate. It is also - possible to specify a specific cipher suite(s) that you - want your connection to use. Default is to use the strongest - available.

- -
+

To see all supported cipher suites, call ssl:cipher_suites/0. + 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 + Setting up Connections -

Here follows some small example of how to set up client/server connections - using the erlang shell. The returned value of the sslsocket has been abbreviated with - [...] as it can be fairly large and is opaque.

+

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.

- Minmal example + Minimal Example -

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

+

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

 - -

Start server side

+ +

To set up client/server connections:

+ +

Step 1: Start the server side:

1 server> ssl:start(). ok -

Create an ssl listen socket

+

Step 2: Create an SSL listen socket:

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

Do a transport accept on the ssl listen socket

+

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

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

Start client side

+

Step 4: Start the client side:

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

Do the ssl handshake

+

Step 5: Do the SSL handshake:

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

Send a messag over ssl

+

Step 6: Send a message over SSL:

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

Flush the shell message queue to see that we got the message - sent on the server side

+

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 + Upgrade Example -

To upgrade a TCP/IP connection to an ssl connection the - client and server have to aggre to do so. Agreement - may be accompliced by using a protocol such the one used by HTTP - specified in RFC 2817.

 +

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:

-

Start server side

+

Step 1: Start the server side:

1 server> ssl:start(). ok -

Create a normal tcp listen socket

+

Step 2: Create a normal TCP listen socket:

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

Accept client connection

+

Step 3: Accept client connection:

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

Start client side

+

Step 4: Start the client side:

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

Make sure active is set to false before trying - to upgrade a connection to an ssl connection, otherwhise - ssl handshake messages may be deliverd to the wrong process.

+

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 -

Do the ssl handshake.

+

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,[...]}} -

Upgrade to an ssl connection. Note that the client and server - must agree upon the upgrade and the server must call - ssl:accept/2 before the client calls ssl:connect/3.

+

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,[...]}} -

Send a messag over ssl

+

Step 8: Send a message over SSL:

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

Set active true on the ssl socket

+

Step 9: Set active true on the SSL socket:

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

Flush the shell message queue to see that we got the message - sent on the client side

+

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 -- cgit v1.2.3