Merge branch 'ingela/DTLS-supported'

* ingela/DTLS-supported:
  ssl: Fix typo
  dtls: Add DTLS handling to utility functions
  ssl: Document enhancment
  ssl: Document DTLS

1 files changed, 77 insertions, 48 deletions

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 8fcda78ed5..80b639155b 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. For DTLS this feature must be considered exprimental.</p>
       <taglist>
 	<tag><c>CallbackModule =</c></tag>
 	<item><p><c>atom()</c></p></item>
@@ -137,10 +140,16 @@
 
       <tag><c>sslsocket() =</c></tag>
       <item><p>opaque()</p></item>
-
-      <tag><marker id="type-protocol"/><c>protocol() =</c></tag>
+      
+      <tag><marker id="type-protocol"/><c> protocol_versions() =</c></tag>
+      <item><p><c> ssl_tls_protocol() |  dtls_protocol() </c></p></item>
+      
+      <tag><marker id="type-protocol"/><c> ssl_tls_protocol() =</c></tag>
       <item><p><c>sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'</c></p></item>
 
+      <tag><marker id="type-protocol"/><c> dtls_protocol() =</c></tag>
+      <item><p><c>'dtlsv1' | 'dtlsv1.2'</c></p></item>
+
       <tag><c>ciphers() =</c></tag>
       <item><p><c>= [ciphersuite()] | string()</c></p>
       <p>According to old API.</p></item>
@@ -184,7 +193,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 +298,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,
@@ -456,15 +465,15 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
       marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3</seealso>
       with the selected CA as trusted anchor and the rest of the chain.</p></item>
 
-      <tag><c>{versions, [protocol()]}</c></tag>
+      <tag><c>{versions, [protocol_versions()]}</c></tag>
       <item><p>TLS protocol versions supported by started clients and servers.
       This option overrides the application environment option
-      <c>protocol_version</c>. If the environment option is not set, it defaults
+      <c>protocol_version</c> and  <c>dtls_protocol_version</c>. If the environment option is not set, it defaults
       to all versions, except SSL-3.0, supported by the SSL application.
       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 +533,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 +673,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 +711,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 +725,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 +823,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>
 
@@ -832,6 +841,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
     <func>
       <name>cipher_suites() -></name>
       <name>cipher_suites(Type) -> ciphers()</name>
+      <name>cipher_suites(Type, protocol_version()) -> ciphers()</name>
       <fsummary>Returns a list of supported cipher suites.</fsummary>
       <type>
         <v>Type = erlang | openssl | all</v>
@@ -843,13 +853,14 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	all available cipher suites. The cipher suites not present
 	in <c>cipher_suites(erlang)</c> but included in
 	<c>cipher_suites(all)</c> are not used unless explicitly configured
-	by the user.</p>
+	by the user. If the version option is not specified, the highest supported
+	TLS version will be used to determine the supported cipher suites</p>
     </desc>
     </func>
 
     <func>
       <name>eccs() -></name>
-      <name>eccs(protocol()) -> [named_curve()]</name>
+      <name>eccs(protocol_version()) -> [named_curve()]</name>
       <fsummary>Returns a list of supported ECCs.</fsummary>
 
       <desc><p>Returns a list of supported ECCs. <c>eccs()</c>
@@ -857,7 +868,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       supported protocols and then deduplicating the output.</p>
       </desc>
     </func>
-
+    
     <func>
       <name>clear_pem_cache() -> ok </name>
       <fsummary> Clears the pem cache</fsummary>
@@ -872,20 +883,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 +910,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,13 +919,13 @@ 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> 
       will be performed in addition to the usual x509-path validation checks. If the check fails the error {bad_cert, hostname_check_failed} will
       be propagated to the path validation fun <seealso marker="#verify_fun">verify_fun</seealso>, where it is possible to do customized
-      checks by using the full possibilitis of the <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso> API.
+      checks by using the full possibilities of the <seealso marker="public_key:public_key#pkix_verify_hostname-3">public_key:pkix_verify_hostname/3</seealso> API.
       
       When the option <c>server_name_indication</c> is provided, its value (the DNS name) will be used as <c>ReferenceID</c>
       to <seealso marker="public_key:public_key#pkix_verify_hostname-2">public_key:pkix_verify_hostname/2</seealso>.
@@ -930,24 +941,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 +969,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 +1132,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 +1232,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 +1242,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 +1259,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 +1321,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>.
@@ -1332,7 +1343,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <fsummary>Returns version information relevant for the
 	SSL application.</fsummary>
       <type>
-	<v>versions_info() = {app_vsn, string()} | {supported | available, [protocol()] </v>
+	<v>versions_info() = {app_vsn, string()} | {supported | available, [ssl_tls_protocol()]} |
+	{supported_dtls | available_dtls, [dtls_protocol()]}	</v>
       </type>
       <desc>
 	<p>Returns version information relevant for the SSL
@@ -1342,19 +1354,35 @@ 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 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 version, see <seealso
 	  marker="#connection_information-1">ssl:connection_information/1
 	  </seealso>.</item>
-  
+	  
+	  <tag><c>supported_dtls</c></tag>
+	  <item>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 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 versions supported by the SSL application.
 	  TLS 1.2 requires sufficient support from the Crypto
 	  application.</item>
+
+	  <tag><c>available_dtls</c></tag>
+	  <item>All DTLS versions supported by the SSL application.
+	  DTLS 1.2 requires sufficient support from the Crypto
+	  application.</item>
+	  
 	</taglist>
       </desc>
     </func>
@@ -1365,6 +1393,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>