ssl: Document DTLS

6 files changed, 104 insertions, 97 deletions

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 8fcda78ed5..ebef8bd69a 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -32,7 +32,7 @@
   <modulesummary>Interface Functions for Secure Socket Layer</modulesummary>
   <description>
     <p>
-      This module contains interface functions for the SSL/TLS protocol.
+      This module contains interface functions for the SSL/TLS/DTLS protocol.
       For detailed information about the supported standards see 
       <seealso marker="ssl_app">ssl(6)</seealso>.
     </p>
@@ -40,7 +40,7 @@
     
   <section>
     <title>DATA TYPES</title>
-    <p>The following data types are used in the functions for SSL:</p>
+    <p>The following data types are used in the functions for SSL/TLS/DTLS:</p>
 
     <taglist>
 
@@ -56,9 +56,11 @@
       <p>The default socket options are
       <c>[{mode,list},{packet, 0},{header, 0},{active, true}]</c>.</p>
       <p>For valid options, see the
-      <seealso marker="kernel:inet">inet(3)</seealso> and
-      <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> manual pages
-      in Kernel.</p></item>
+      <seealso marker="kernel:inet">inet(3)</seealso>,
+      <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> and
+      <seealso marker="kernel:gen_tcp">gen_udp(3)</seealso> 
+      manual pages
+      in Kernel. Note that stream oriented options such as packet are only relevant for SSL/TLS and not DTLS</p></item>
 
       <tag><marker id="type-ssloption"/><c>ssl_option() =</c></tag>
       <item>
@@ -95,13 +97,14 @@
       <item><p><c>{cb_info, {CallbackModule::atom(), DataTag::atom(),
 
       ClosedTag::atom(), ErrTag:atom()}}</c></p>
-      <p>Defaults to <c>{gen_tcp, tcp, tcp_closed, tcp_error}</c>. Can be used
-      to customize the transport layer. The callback module must implement a
+      <p>Defaults to <c>{gen_tcp, tcp, tcp_closed, tcp_error}</c> for TLS
+      and <c>{gen_udp, udp, udp_closed, udp_error}</c> for DTLS. Can be used
+      to customize the transport layer. For TLS the callback module must implement a
       reliable transport protocol, behave as <c>gen_tcp</c>, and have functions
       corresponding to <c>inet:setopts/2</c>, <c>inet:getopts/2</c>,
       <c>inet:peername/1</c>, <c>inet:sockname/1</c>, and <c>inet:port/1</c>.
       The callback <c>gen_tcp</c> is treated specially and calls <c>inet</c>
-      directly.</p>
+      directly.</p> For DTLS this feature must be considered exprimental.
       <taglist>
 	<tag><c>CallbackModule =</c></tag>
 	<item><p><c>atom()</c></p></item>
@@ -184,7 +187,7 @@
   </section>
 
   <section>
-    <title>SSL OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT</title>
+    <title>TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT</title>
 
     <p>The following options have the same meaning in the client and 
     the server:</p>
@@ -289,11 +292,11 @@ atom()}} |
 	<list type="bulleted">
 	  <item><p>If the verify callback fun returns <c>{fail, Reason}</c>,
 	  the verification process is immediately stopped, an alert is
-	  sent to the peer, and the TLS/SSL handshake terminates.</p></item>
+	  sent to the peer, and the TLS/DTLS handshake terminates.</p></item>
 	  <item><p>If the verify callback fun returns <c>{valid, UserState}</c>,
 	  the verification process continues.</p></item> 
 	  <item><p>If the verify callback fun always returns
-	  <c>{valid, UserState}</c>, the TLS/SSL handshake does not
+	  <c>{valid, UserState}</c>, the TLS/DTLS handshake does not
 	  terminate regarding verification failures and the connection is
 	  established.</p></item>
 	  <item><p>If called with an extension unknown to the user application,
@@ -464,7 +467,7 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
       See also <seealso marker="ssl:ssl_app">ssl(6).</seealso></p></item>
 
       <tag><c>{hibernate_after, integer()|undefined}</c></tag>
-      <item><p>When an integer-value is specified, <c>ssl_connection</c>
+      <item><p>When an integer-value is specified, <c>TLS/DTLS-connection</c>
       goes into hibernation after the specified number of milliseconds
       of inactivity, thus reducing its memory footprint. When
       <c>undefined</c> is specified (this is the default), the process
@@ -524,7 +527,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
   </section>
   
   <section>
-    <title>SSL OPTION DESCRIPTIONS - CLIENT SIDE</title>
+    <title>TLS/DTLS OPTION DESCRIPTIONS - CLIENT SIDE</title>
 
     <p>The following options are client-specific or have a slightly different
     meaning in the client than in the server:</p>
@@ -664,7 +667,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
    </section>
    
   <section>
-    <title>SSL OPTION DESCRIPTIONS - SERVER SIDE</title>
+    <title>TLS/DTLS OPTION DESCRIPTIONS - SERVER SIDE</title>
 
     <p>The following options are server-specific or have a slightly different
     meaning in the server than in the client:</p>
@@ -702,7 +705,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       </p></item>
 
       <tag><c>{fail_if_no_peer_cert, boolean()}</c></tag>
-      <item><p>Used together with <c>{verify, verify_peer}</c> by an SSL server.
+      <item><p>Used together with <c>{verify, verify_peer}</c> by an TLS/DTLS server.
       If set to <c>true</c>, the server fails if the client does not have
       a certificate to send, that is, sends an empty certificate. If set to
       <c>false</c>, it fails only if the client sends an invalid
@@ -716,7 +719,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
 
       <tag><c>{reuse_session, fun(SuggestedSessionId,
       PeerCert, Compression, CipherSuite) -> boolean()}</c></tag>
-      <item><p>Enables the SSL server to have a local policy
+      <item><p>Enables the TLS/DTLS server to have a local policy
       for deciding if a session is to be reused or not.
       Meaningful only if <c>reuse_sessions</c> is set to <c>true</c>.
       <c>SuggestedSessionId</c> is a <c>binary()</c>, <c>PeerCert</c> is
@@ -814,7 +817,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
   <section>
     <title>General</title>
       
-    <p>When an SSL socket is in active mode (the default), data from the
+    <p>When an TLS/DTLS socket is in active mode (the default), data from the
       socket is delivered to the owner of the socket in the form of
       messages:</p>
 
@@ -872,20 +875,20 @@ fun(srp, Username :: string(), UserState :: term()) ->
    
     <func>
       <name>connect(Socket, SslOptions) -> </name>
-      <name>connect(Socket, SslOptions, Timeout) -> {ok, SslSocket}
+      <name>connect(Socket, SslOptions, Timeout) -> {ok, TLSSocket}
 	| {error, Reason}</name>
       <fsummary>Upgrades a <c>gen_tcp</c>, or
-	equivalent, connected socket to an SSL socket.</fsummary>
+	equivalent, connected socket to an TLS socket.</fsummary>
       <type>
 	<v>Socket = socket()</v>
 	<v>SslOptions = [ssl_option()]</v>
 	<v>Timeout = integer() | infinity</v>
-	<v>SslSocket = sslsocket()</v>
+	<v>TLSSocket = sslsocket()</v>
 	<v>Reason = term()</v>
       </type>
       <desc><p>Upgrades a <c>gen_tcp</c>, or equivalent,
-	  connected socket to an SSL socket, that is, performs the
-	  client-side ssl handshake.</p>
+	  connected socket to an TLS socket, that is, performs the
+	  client-side TLS handshake.</p>
 	  
 	  <note><p>If the option <c>verify</c> is set to <c>verify_peer</c>
 	  the option <c>server_name_indication</c> shall also be specified,
@@ -899,7 +902,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name>connect(Host, Port, Options) -></name>
       <name>connect(Host, Port, Options, Timeout) ->
 	  {ok, SslSocket} | {error, Reason}</name>
-      <fsummary>Opens an SSL connection to <c>Host</c>, <c>Port</c>.</fsummary>
+      <fsummary>Opens an TLS/DTLS connection to <c>Host</c>, <c>Port</c>.</fsummary>
       <type>
 	  <v>Host = host()</v>
 	  <v>Port = integer()</v>
@@ -908,7 +911,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	  <v>SslSocket = sslsocket()</v>
 	  <v>Reason = term()</v>
       </type>
-      <desc><p>Opens an SSL connection to <c>Host</c>, <c>Port</c>.</p>
+      <desc><p>Opens an TLS/DTLS connection to <c>Host</c>, <c>Port</c>.</p>
       
       <p> When the option <c>verify</c> is set to <c>verify_peer</c> the check 
       <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso> 
@@ -930,24 +933,24 @@ fun(srp, Username :: string(), UserState :: term()) ->
 
     <func>
       <name>close(SslSocket) -> ok | {error, Reason}</name>
-      <fsummary>Closes an SSL connection.</fsummary>
+      <fsummary>Closes an TLS/DTLS connection.</fsummary>
       <type>
 	  <v>SslSocket = sslsocket()</v>
 	  <v>Reason = term()</v>
       </type>
-      <desc><p>Closes an SSL connection.</p>
+      <desc><p>Closes an TLS/DTLS connection.</p>
       </desc>
     </func>
 
     <func>
       <name>close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}</name>
-      <fsummary>Closes an SSL connection.</fsummary>
+      <fsummary>Closes an TLS connection.</fsummary>
       <type>
 	  <v>SslSocket = sslsocket()</v>
 	  <v>How =  timeout() | {NewController::pid(), timeout()} </v>
 	  <v>Reason = term()</v>
       </type>
-      <desc><p>Closes or downgrades an SSL connection. In the latter case the transport
+      <desc><p>Closes or downgrades an TLS connection. In the latter case the transport
       connection will be handed over to the <c>NewController</c> process after receiving
       the TLS close alert from the peer. The returned transport socket will have
       the following options set: <c>[{active, false}, {packet, 0}, {mode, binary}]</c></p>
@@ -958,7 +961,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <name>controlling_process(SslSocket, NewOwner) ->
 	ok | {error, Reason}</name>
 	<fsummary>Assigns a new controlling process to the
-	SSL socket.</fsummary>
+	TLS/DTLS socket.</fsummary>
 	<type>
 	  <v>SslSocket = sslsocket()</v>
 	  <v>NewOwner = pid()</v>
@@ -1121,7 +1124,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	  extra key material. It either takes user-generated values for
 	  <c>Secret</c> and <c>Seed</c> or atoms directing it to use a specific
 	  value from the session security parameters.</p>
-        <p>Can only be used with TLS connections; <c>{error, undefined}</c>
+        <p>Can only be used with TLS/DTLS connections; <c>{error, undefined}</c>
 	  is returned for SSLv3 connections.</p>
       </desc>
     </func>
@@ -1221,7 +1224,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Performs the SSL/TLS server-side handshake.</p>
+        <p>Performs the SSL/TLS/DTLS server-side handshake.</p>
 	<p><c>Socket</c> is a socket as returned by
 	<seealso marker="#transport_accept-2">ssl:transport_accept/[1,2]</seealso>
 	</p>
@@ -1231,7 +1234,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
     <func>
       <name>ssl_accept(Socket, SslOptions) -> </name>
       <name>ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}</name>
-      <fsummary>Performs server-side SSL/TLS handshake.</fsummary>
+      <fsummary>Performs server-side SSL/TLS/DTLS handshake.</fsummary>
       <type>
         <v>Socket = socket() | sslsocket() </v>
 	<v>SslOptions = [ssl_option()]</v>
@@ -1248,10 +1251,10 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	by calling this function, else the upgrade succeeds or does not
 	succeed depending on timing.</p></warning>
 	
-	<p>If <c>Socket</c> is an <c>sslsocket()</c>: provides extra SSL/TLS
+	<p>If <c>Socket</c> is an <c>sslsocket()</c>: provides extra SSL/TLS/DTLS
 	options to those specified in
 	<seealso marker="#listen-2">ssl:listen/2 </seealso> and then performs
-	the SSL/TLS handshake.
+	the SSL/TLS/DTLS handshake.
 	</p>
       </desc>
     </func>
@@ -1310,7 +1313,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	The socket returned is to be passed to
 	<seealso marker="#ssl_accept-2"> ssl:ssl_accept[2,3]</seealso>
 	to complete handshaking, that is,
-	establishing the SSL/TLS connection.</p>
+	establishing the SSL/TLS/DTLS connection.</p>
         <warning>
           <p>The socket returned can only be used with
 	  <seealso marker="#ssl_accept-2"> ssl:ssl_accept[2,3]</seealso>.
@@ -1342,17 +1345,17 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	  <item>The application version of the SSL application.</item>
 
 	  <tag><c>supported</c></tag>
-	  <item>TLS/SSL versions supported by default.
+	  <item>SSL/TLS/DTLS versions supported by default.
 	  Overridden by a version option on
 	  <seealso marker="#connect-2"> connect/[2,3,4]</seealso>,
 	  <seealso marker="#listen-2"> listen/2</seealso>, and <seealso
 	  marker="#ssl_accept-2">ssl_accept/[1,2,3]</seealso>.
-	  For the negotiated TLS/SSL version, see <seealso
+	  For the negotiated SSL/TLS/DTLS version, see <seealso
 	  marker="#connection_information-1">ssl:connection_information/1
 	  </seealso>.</item>
   
 	  <tag><c>available</c></tag>
-	  <item>All TLS/SSL versions supported by the SSL application.
+	  <item>All SSL/TLS/DTLS versions supported by the SSL application.
 	  TLS 1.2 requires sufficient support from the Crypto
 	  application.</item>
 	</taglist>
@@ -1365,6 +1368,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
     <title>SEE ALSO</title>
     <p><seealso marker="kernel:inet">inet(3)</seealso> and
       <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>
+      <seealso marker="kernel:gen_udp">gen_udp(3)</seealso>
     </p>
   </section>
 
diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml
index f317dfded4..07cbfb3bd9 100644
--- a/lib/ssl/doc/src/ssl_app.xml
+++ b/lib/ssl/doc/src/ssl_app.xml
@@ -38,8 +38,8 @@
       The ssl application is an implementation of the SSL/TLS protocol in Erlang.
     </p>
     <list type="bulleted">
-      <item>Supported SSL/TLS-versions are SSL-3.0, TLS-1.0,
-      TLS-1.1, and TLS-1.2.</item>
+      <item>Supported SSL/TLS/DTLS-versions are SSL-3.0, TLS-1.0,
+      TLS-1.1, TLS-1.2, DTLS-1.0 (based on TLS-1.1), DTLS-1.2 (based on TLS-1.2)</item>
       <item>For security reasons SSL-2.0 is not supported.</item>
       <item>For security reasons SSL-3.0 is no longer supported by default,
       but can be configured.</item>
@@ -167,7 +167,7 @@
     <title>ERROR LOGGER AND EVENT HANDLERS</title>
     <p>The SSL application uses the default <seealso
     marker="kernel:error_logger">OTP error logger</seealso> to log
-    unexpected errors and TLS alerts. The logging of TLS alerts may be
+    unexpected errors and TLS/DTLS alerts. The logging of TLS/DTLS alerts may be
     turned off with the <c>log_alert</c> option. </p>
   </section>
 
diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml
index 7f8a08f704..e14f3f90dc 100644
--- a/lib/ssl/doc/src/ssl_distribution.xml
+++ b/lib/ssl/doc/src/ssl_distribution.xml
@@ -22,7 +22,7 @@
     
     </legalnotice>
 
-    <title>Using SSL for Erlang Distribution</title>
+    <title>Using TLS for Erlang Distribution</title>
     <prepared>P Nyblom</prepared>
     <responsible></responsible>
     <docno></docno>
@@ -33,7 +33,7 @@
     <file>ssl_distribution.xml</file>
   </header>
   <p>This section describes how the Erlang distribution can use 
-    SSL to get extra verification and security.</p>
+    TLS to get extra verification and security.</p>
 
     <p>The Erlang distribution can in theory use almost any 
       connection-based protocol as bearer. However, a module that 
@@ -45,16 +45,16 @@
 
       <p>In the SSL application, an extra distribution
       module, <c>inet_tls_dist</c>, can be used as an
-      alternative. All distribution connections will use SSL and
+      alternative. All distribution connections will use TLS and
       all participating Erlang nodes in a distributed system must use
       this distribution module.</p>
 
       <p>The security level depends on the parameters provided to the
-      SSL connection setup. Erlang node cookies are however always
+      TLS connection setup. Erlang node cookies are however always
       used, as they can be used to differentiate between two different
       Erlang networks.</p>
 
-    <p>To set up Erlang distribution over SSL:</p>
+    <p>To set up Erlang distribution over TLS:</p>
 
       <list type="bulleted">
       <item><em>Step 1:</em> Build boot scripts including the
@@ -63,13 +63,13 @@
       <c>net_kernel</c>.</item>
       <item><em>Step 3:</em> Specify the security options and other 
       SSL options.</item>
-      <item><em>Step 4:</em> Set up the environment to always use SSL.</item>
+      <item><em>Step 4:</em> Set up the environment to always use TLS.</item>
     </list>
 
     <p>The following sections describe these steps.</p>
 
   <section>
-    <title>Building Boot Scripts Including the ssl Application</title>
+    <title>Building Boot Scripts Including the SSL Application</title>
     <p>Boot scripts are built using the <c>systools</c> utility in the
       SASL application. For more information on <c>systools</c>,
       see the SASL documentation. This is only an example of
@@ -90,7 +90,7 @@
 	STDLIB application.</p></item>
       </list>
 
-    <p>The following shows an example <c>.rel</c> file with SSL 
+    <p>The following shows an example <c>.rel</c> file with TLS 
     added:</p>
     <code type="none">
       {release, {"OTP  APN 181 01","R15A"}, {erts, "5.9"},
@@ -154,7 +154,7 @@ Eshell V5.0  (abort with ^G)
 
   <section>
     <title>Specifying Distribution Module for net_kernel</title>
-    <p>The distribution module for SSL is named <c>inet_tls_dist</c>
+    <p>The distribution module for SSL/TLS is named <c>inet_tls_dist</c>
       and is specified on the command line with option <c>-proto_dist</c>.
       The argument to <c>-proto_dist</c> is to be the module
       name without suffix <c>_dist</c>. So, this distribution
@@ -174,21 +174,21 @@ Eshell V5.0  (abort with ^G)
 (ssl_test@myhost)1>     </code>
 
     <p>However, a node started in this way refuses to talk
-      to other nodes, as no SSL parameters are supplied
+      to other nodes, as no TLS parameters are supplied
       (see the next section).</p>
   </section>
 
   <section>
-    <title>Specifying SSL Options</title>
+    <title>Specifying SSL/TLS Options</title>
 
     <p>
-      The SSL distribution options can be written into a file
+      The SSL/TLS distribution options can be written into a file
       that is consulted when the node is started.  This file name
       is then specified with the command line argument
       <c>-ssl_dist_optfile</c>.
     </p>
     <p>
-      Any available SSL option can be specified in an options file,
+      Any available SSL/TLS option can be specified in an options file,
       but note that options that take a <c>fun()</c> has to use
       the syntax <c>fun Mod:Func/Arity</c> since a function
       body can not be compiled when consulting a file.
@@ -202,7 +202,7 @@ Eshell V5.0  (abort with ^G)
       interfere severely, so beware!
     </p>
     <p>
-      For SSL to work, at least a public key and a certificate
+      For SSL/TLS to work, at least a public key and a certificate
       must be specified for the server side.
       In the following example, the PEM file
       <c>"/home/me/ssl/erlserver.pem"</c> contains both
@@ -257,13 +257,13 @@ $ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls
       still be accepted if it does not present any certificate.
     </p>
     <p>
-      A node started in this way is fully functional, using SSL
+      A node started in this way is fully functional, using TLS
       as the distribution protocol.
     </p>
   </section>
 
   <section>
-    <title>Specifying SSL Options (Legacy)</title>
+    <title>Specifying SSL/TLS Options (Legacy)</title>
 
     <p>
       As in the previous section the PEM file
@@ -272,9 +272,9 @@ $ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls
     </p>
 
     <p>On the <c>erl</c> command line you can specify options that the
-    SSL distribution adds when creating a socket.</p>
+    SSL/TLS distribution adds when creating a socket.</p>
 
-    <p>The simplest SSL options in the following list can be specified 
+    <p>The simplest SSL/TLS options in the following list can be specified 
     by adding the 
     prefix <c>server_</c> or <c>client_</c> to the option name:</p>
     <list type="bulleted">
@@ -294,7 +294,7 @@ $ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls
     </list>
 
     <p>Note that <c>verify_fun</c> needs to be written in a different
-    form than the corresponding SSL option, since funs are not
+    form than the corresponding SSL/TLS option, since funs are not
     accepted on the command line.</p>
 
     <p>The server can also take the options <c>dhfile</c> and
@@ -307,7 +307,7 @@ $ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls
     <p>Raw socket options, such as <c>packet</c> and <c>size</c> must not 
     be specified on the command line.</p>
 
-    <p>The command-line argument for specifying the SSL options is named
+    <p>The command-line argument for specifying the SSL/TLS options is named
     <c>-ssl_dist_opt</c> and is to be followed by pairs of
     SSL options and their values. Argument <c>-ssl_dist_opt</c> can
     be repeated any number of times.</p>
@@ -331,10 +331,10 @@ Eshell V5.0  (abort with ^G)
   </section>
 
   <section>
-    <title>Setting up Environment to Always Use SSL (Legacy)</title>
+    <title>Setting up Environment to Always Use SSL/TLS (Legacy)</title>
     <p>A convenient way to specify arguments to Erlang is to use environment 
       variable <c>ERL_FLAGS</c>. All the flags needed to
-      use the SSL distribution can be specified in that variable and are
+      use the SSL/TLS distribution can be specified in that variable and are
       then interpreted as command-line arguments for all
       subsequent invocations of Erlang.</p>
 
@@ -365,8 +365,8 @@ Eshell V5.0  (abort with ^G)
   </section>
 
   <section>
-    <title>Using SSL distribution over IPv6</title>
-    <p>It is possible to use SSL distribution over IPv6 instead of
+    <title>Using SSL/TLS distribution over IPv6</title>
+    <p>It is possible to use SSL/TLS distribution over IPv6 instead of
     IPv4. To do this, pass the option <c>-proto_dist inet6_tls</c>
     instead of <c>-proto_dist inet_tls</c> when starting Erlang,
     either on the command line or in the <c>ERL_FLAGS</c> environment
@@ -380,6 +380,6 @@ $ erl -boot /home/me/ssl/start_ssl -proto_dist inet6_tls
     </code>
 
     <p>A node started in this way will only be able to communicate with
-    other nodes using SSL distribution over IPv6.</p>
+    other nodes using SSL/TLS distribution over IPv6.</p>
   </section>
 </chapter>
diff --git a/lib/ssl/doc/src/ssl_introduction.xml b/lib/ssl/doc/src/ssl_introduction.xml
index d3e39dbb01..bbb1c276cc 100644
--- a/lib/ssl/doc/src/ssl_introduction.xml
+++ b/lib/ssl/doc/src/ssl_introduction.xml
@@ -5,7 +5,7 @@
   <header>
     <copyright>
       <year>2015</year>
-      <year>2015</year>
+      <year>2017</year>
       <holder>Ericsson AB, All Rights Reserved</holder>
     </copyright>
     <legalnotice>
@@ -41,14 +41,15 @@
     authenticate the counterpart with whom they communicate,
     and to exchange a symmetric key for payload encryption. The protocol provides
     data/message confidentiality (encryption), integrity (through message authentication code checks)
-    and host verification (through certificate path validation).</p>
+    and host verification (through certificate path validation). DTLS (Datagram Transport Layer Security) that
+    is based on TLS but datagram oriented instead of stream oriented.</p>
   </section>
 
   <section>
     <title>Prerequisites</title>
     <p>It is assumed that the reader is familiar with the Erlang
     programming language, the concepts of OTP, and has a basic
-    understanding of SSL/TLS.</p>
+    understanding of SSL/TLS/DTLS.</p>
   </section>
 
 </chapter>
diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml
index 31a22db58b..0b12dc7dc5 100644
--- a/lib/ssl/doc/src/ssl_protocol.xml
+++ b/lib/ssl/doc/src/ssl_protocol.xml
@@ -22,7 +22,7 @@
       
     </legalnotice>
 
-    <title>TLS and its Predecessor, SSL</title>
+    <title>TLS/DTLS and TLS Predecessor, SSL</title>
     <prepared></prepared>
     <responsible></responsible>
     <docno></docno>
@@ -33,7 +33,7 @@
     <file>ssl_protocol.xml</file>
   </header>
   
-  <p>The Erlang SSL application implements the SSL/TLS protocol
+  <p>The Erlang SSL application implements the SSL/TLS/DTLS protocol
   for the currently supported versions,  see the
   <seealso marker="ssl">ssl(3)</seealso> manual page.
   </p>
@@ -41,20 +41,22 @@
   <p>By default SSL/TLS is run over the TCP/IP protocol even
   though you can plug in any other reliable transport protocol
   with the same Application Programming Interface (API) as the
-  <c>gen_tcp</c> module in Kernel.</p>
+  <c>gen_tcp</c> module in Kernel. DTLS is by default run over UDP/IP,
+  which means that application data has no delivery guarentees. Other 
+  transports, such as SCTP, may be supported in future releases.</p>
   
   <p>If a client and a server wants to use an upgrade mechanism, such as
-  defined by RFC 2817, to upgrade a regular TCP/IP connection to an SSL
+  defined by RFC 2817, to upgrade a regular TCP/IP connection to an TLS
   connection, this is supported by the Erlang SSL application API. This can be 
   useful for, for example, supporting HTTP and HTTPS on the same port and
-  implementing virtual hosting.
+  implementing virtual hosting. Note this is a TLS feature only.
   </p>
 
   <section>
     <title>Security Overview</title>
       
    <p>To achieve authentication and privacy, the client and server
-    perform a TLS handshake procedure before transmitting or receiving
+    perform a TLS/DTLS handshake procedure before transmitting or receiving
     any data. During the handshake, they agree on a protocol version and
     cryptographic algorithms, generate shared secrets using public
     key cryptographies, and optionally authenticate each other with
@@ -73,10 +75,10 @@
     
     <p>The keys for the symmetric encryption are generated uniquely
     for each connection and are based on a secret negotiated
-    in the TLS handshake.</p>
+    in the TLS/DTLS handshake.</p>
     
-    <p>The TLS handshake protocol and data transfer is run on top of
-    the TLS Record Protocol, which uses a keyed-hash Message
+    <p>The TLS/DTLS handshake protocol and data transfer is run on top of
+    the TLS/DTLS Record Protocol, which uses a keyed-hash Message
     Authenticity Code (MAC), or a Hash-based MAC (HMAC),
     to protect the message data
     integrity. From the TLS RFC: "A Message Authentication Code is a
@@ -152,8 +154,8 @@
      from it was saved, for security reasons. The amount of time the 
      session data is to be saved can be configured.</p>
 
-     <p>By default the SSL clients try to reuse an available session and 
-     by default the SSL servers agree to reuse sessions when clients
+     <p>By default the TLS/DTLS clients try to reuse an available session and 
+     by default the TLS/DTLS servers agree to reuse sessions when clients
      ask for it.</p>
 
    </section>
diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml
index f84cd6e391..ea5811fe34 100644
--- a/lib/ssl/doc/src/using_ssl.xml
+++ b/lib/ssl/doc/src/using_ssl.xml
@@ -22,7 +22,7 @@
     
     </legalnotice>
 
-    <title>Using SSL API</title>
+    <title>Using SSL application API</title>
     <prepared></prepared>
     <responsible></responsible>
     <docno></docno>
@@ -51,7 +51,7 @@
     <section>
       <title>Minimal Example</title>
       
-      <note><p> The minimal setup is not the most secure setup of SSL.</p>    
+      <note><p> The minimal setup is not the most secure setup of SSL/TLS/DTLS.</p>    
       </note>
 
       <p>To set up client/server connections:</p>
@@ -60,27 +60,27 @@
       <code type="erl">1 server> ssl:start().
 ok</code>
       
-      <p><em>Step 2:</em> Create an SSL listen socket:</p>
+      <p><em>Step 2:</em> Create an TLS listen socket: (To run DTLS add the option {protocol, dtls})</p>
       <code type="erl">2 server> {ok, ListenSocket} =
 ssl:listen(9999, [{certfile, "cert.pem"}, {keyfile, "key.pem"},{reuseaddr, true}]).
 {ok,{sslsocket, [...]}}</code>
       
-      <p><em>Step 3:</em> Do a transport accept on the SSL listen socket:</p>
+      <p><em>Step 3:</em> Do a transport accept on the TLS listen socket:</p>
       <code type="erl">3 server> {ok, Socket} = ssl:transport_accept(ListenSocket).
 {ok,{sslsocket, [...]}}</code>
 
-      <p><em>Step 4:</em> Start the client side:</p>
+      <p><em>Step 4:</em> Start the client side: </p>
       <code type="erl">1 client> ssl:start().
 ok</code>
-      
+      <p> To run DTLS add the option {protocol, dtls} to third argument.</p>
       <code type="erl">2 client> {ok, Socket} = ssl:connect("localhost", 9999,  [], infinity).
 {ok,{sslsocket, [...]}}</code>
       
-      <p><em>Step 5:</em> Do the SSL handshake:</p>
+      <p><em>Step 5:</em> Do the TLS handshake:</p>
       <code type="erl">4 server> ok = ssl:ssl_accept(Socket).
 ok</code>
       
-      <p><em>Step 6:</em> Send a message over SSL:</p>
+      <p><em>Step 6:</em> Send a message over TLS:</p>
       <code type="erl">5 server> ssl:send(Socket, "foo").
 ok</code>
       
@@ -92,7 +92,7 @@ ok</code>
     </section>
     
     <section>
-      <title>Upgrade Example</title>
+      <title>Upgrade Example - TLS only </title>
       
       <note><p>To upgrade a TCP/IP connection to an SSL connection, the
       client and server must agree to do so. The agreement
@@ -125,24 +125,24 @@ ok</code>
       <code type="erl">4 server> inet:setopts(Socket, [{active, false}]).
 ok</code>
       
-      <p><em>Step 6:</em> Do the SSL handshake:</p>
-      <code type="erl">5 server> {ok, SSLSocket} = ssl:ssl_accept(Socket, [{cacertfile, "cacerts.pem"},
+      <p><em>Step 6:</em> Do the TLS handshake:</p>
+      <code type="erl">5 server> {ok, TLSSocket} = ssl:ssl_accept(Socket, [{cacertfile, "cacerts.pem"},
 {certfile, "cert.pem"}, {keyfile, "key.pem"}]).
 {ok,{sslsocket,[...]}}</code>
       
-      <p><em>Step 7:</em> Upgrade to an SSL connection. The client and server
+      <p><em>Step 7:</em> Upgrade to an TLS connection. The client and server
       must agree upon the upgrade. The server must call
       <c>ssl:accept/2</c> before the client calls <c>ssl:connect/3.</c></p>
-      <code type="erl">3 client>{ok, SSLSocket} = ssl:connect(Socket, [{cacertfile, "cacerts.pem"},
+      <code type="erl">3 client>{ok, TLSSocket} = ssl:connect(Socket, [{cacertfile, "cacerts.pem"},
 {certfile, "cert.pem"}, {keyfile, "key.pem"}], infinity).
 {ok,{sslsocket,[...]}}</code>
       
-      <p><em>Step 8:</em> Send a message over SSL:</p>
-      <code type="erl">4 client> ssl:send(SSLSocket, "foo").
+      <p><em>Step 8:</em> Send a message over TLS:</p>
+      <code type="erl">4 client> ssl:send(TLSSocket, "foo").
 ok</code>
       
-      <p><em>Step 9:</em> Set <c>active true</c> on the SSL socket:</p>
-      <code type="erl">4 server> ssl:setopts(SSLSocket, [{active, true}]).
+      <p><em>Step 9:</em> Set <c>active true</c> on the TLS socket:</p>
+      <code type="erl">4 server> ssl:setopts(TLSSocket, [{active, true}]).
 ok</code>
       
       <p><em>Step 10:</em> Flush the shell message queue to see that the message