Merge branch 'master' into sverk/hipe-line-table-bug/master/OTP-13282

5 files changed, 249 insertions, 59 deletions

diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml
index b87b1b4fa7..61d1c8355a 100644
--- a/lib/ssl/doc/src/notes.xml
+++ b/lib/ssl/doc/src/notes.xml
@@ -26,7 +26,152 @@
     <file>notes.xml</file>
   </header>
   <p>This document describes the changes made to the SSL application.</p>
-  <section><title>SSL 7.0</title>
+
+
+<section><title>SSL 7.2</title>
+
+    <section><title>Fixed Bugs and Malfunctions</title>
+      <list>
+        <item>
+          <p>
+	    Honor distribution port range options</p>
+          <p>
+	    Own Id: OTP-12838</p>
+        </item>
+        <item>
+          <p>
+	    Correct supervisor specification in TLS distribution.</p>
+          <p>
+	    Own Id: OTP-13134</p>
+        </item>
+        <item>
+          <p>
+	    Correct cache timeout</p>
+          <p>
+	    Own Id: OTP-13141</p>
+        </item>
+        <item>
+          <p>
+	    Avoid crash and restart of ssl process when key file does
+	    not exist.</p>
+          <p>
+	    Own Id: OTP-13144</p>
+        </item>
+        <item>
+          <p>
+	    Enable passing of raw socket options on the format
+	    {raw,_,_,_} to the underlying socket.</p>
+          <p>
+	    Own Id: OTP-13166</p>
+        </item>
+        <item>
+          <p>
+	    Hibernation with small or a zero timeout will now work as
+	    expected</p>
+          <p>
+	    Own Id: OTP-13189</p>
+        </item>
+      </list>
+    </section>
+
+
+    <section><title>Improvements and New Features</title>
+      <list>
+        <item>
+          <p>
+	    Add upper limit for session cache, configurable on ssl
+	    application level.</p>
+          <p>
+	    If upper limit is reached, invalidate the current cache
+	    entries, e.i the session lifetime is the max time a
+	    session will be keept, but it may be invalidated earlier
+	    if the max limit for the table is reached. This will keep
+	    the ssl manager process well behaved, not exhusting
+	    memeory. Invalidating the entries will incrementally
+	    empty the cache to make room for fresh sessions entries.</p>
+          <p>
+	    Own Id: OTP-12392</p>
+        </item>
+        <item>
+          <p>
+	    Use new time functions to measure passed time.</p>
+          <p>
+	    Own Id: OTP-12457</p>
+        </item>
+        <item>
+          <p>
+	    Improved error handling in TLS distribution</p>
+          <p>
+	    Own Id: OTP-13142</p>
+        </item>
+        <item>
+          <p>
+	    Distribution over TLS now honors the nodelay distribution
+	    flag</p>
+          <p>
+	    Own Id: OTP-13143</p>
+        </item>
+      </list>
+    </section>
+
+</section>
+
+<section><title>SSL 7.1</title>
+    <section><title>Fixed Bugs and Malfunctions</title>
+      <list>
+        <item>
+          <p>
+	    Add DER encoded ECPrivateKey as valid input format for
+	    key option.</p>
+          <p>
+	    Own Id: OTP-12974</p>
+        </item>
+        <item>
+          <p>
+	    Correct return value of default session callback module</p>
+          <p>
+	    This error had the symptom that the client check for
+	    unique session would always fail, potentially making the
+	    client session table grow a lot and causing long setup
+	    times.</p>
+          <p>
+	    Own Id: OTP-12980</p>
+        </item>
+      </list>
+    </section>
+
+
+    <section><title>Improvements and New Features</title>
+      <list>
+        <item>
+          <p>
+	    Add possibility to downgrade an SSL/TLS connection to a
+	    tcp connection, and give back the socket control to a
+	    user process.</p>
+          <p>
+	    This also adds the possibility to specify a timeout to
+	    the ssl:close function.</p>
+          <p>
+	    Own Id: OTP-11397</p>
+        </item>
+        <item>
+          <p>
+	    Add application setting to be able to change fatal alert
+	    shutdown timeout, also shorten the default timeout. The
+	    fatal alert timeout is the number of milliseconds between
+	    sending of a fatal alert and closing the connection.
+	    Waiting a little while improves the peers chances to
+	    properly receiving the alert so it may shutdown
+	    gracefully.</p>
+          <p>
+	    Own Id: OTP-12832</p>
+        </item>
+      </list>
+    </section>
+
+</section>
+
+<section><title>SSL 7.0</title>
 
     <section><title>Fixed Bugs and Malfunctions</title>
       <list>
@@ -51,12 +196,6 @@
           <p>
 	    Own Id: OTP-12815</p>
         </item>
-        <item>
-          <p>
-	    Gracefully ignore proprietary hash_sign algorithms</p>
-          <p>
-	    Own Id: OTP-12829</p>
-        </item>
       </list>
     </section>
 
@@ -107,6 +246,20 @@
 
 </section>
 
+<section><title>SSL 6.0.1.1</title>
+    <section><title>Fixed Bugs and Malfunctions</title>
+    <list>
+          <item>
+          <p>
+	    Gracefully ignore proprietary hash_sign algorithms</p>
+          <p>
+	    Own Id: OTP-12829</p>
+        </item>
+    </list>
+    </section>
+</section>
+
+
 <section><title>SSL 6.0.1</title>
 
     <section><title>Fixed Bugs and Malfunctions</title>
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index f23b71e28b..bf87644116 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -31,37 +31,13 @@
   <module>ssl</module>
   <modulesummary>Interface Functions for Secure Socket Layer</modulesummary>
   <description>
-    <p>This module contains interface functions for the SSL.</p>
+    <p>
+      This module contains interface functions for the SSL/TLS protocol.
+      For detailed information about the supported standards see 
+      <seealso marker="ssl_app">ssl(6)</seealso>.
+    </p>
   </description>
-  
-  <section>
-    <title>SSL</title>
-
-    <list type="bulleted">
-      <item>For application dependencies see <seealso marker="ssl_app"> ssl(6)</seealso> </item>
-      <item>Supported SSL/TLS-versions are SSL-3.0, TLS-1.0,
-      TLS-1.1, and 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>
-      <item>Ephemeral Diffie-Hellman cipher suites are supported,
-      but not Diffie Hellman Certificates cipher suites.</item>
-      <item>Elliptic Curve cipher suites are supported if the Crypto 
-      application supports it and named curves are used.
-      </item>
-      <item>Export cipher suites are not supported as the
-      U.S. lifted its export restrictions in early 2000.</item>
-      <item>IDEA cipher suites are not supported as they have
-      become deprecated by the latest TLS specification so it is not 
-      motivated to implement them.</item>
-      <item>CRL validation is supported.</item>
-      <item>Policy certificate extensions are not supported.</item>
-      <item>'Server Name Indication' extension client side
-      (RFC 6066, Section 3) is supported.</item>
-    </list>
- 
-  </section>
-  
+    
   <section>
     <title>DATA TYPES</title>
     <p>The following data types are used in the functions for SSL:</p>
@@ -84,11 +60,12 @@
       <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> manual pages
       in Kernel.</p></item>
 
-      <tag><marker id="type-ssloption"></marker><c>ssloption() =</c></tag>
+      <tag><marker id="type-ssloption"/><c>ssloption() =</c></tag>
       <item>
 	<p><c>{verify, verify_type()}</c></p>
 	<p><c>| {verify_fun, {fun(), term()}}</c></p>
-	<p><c>| {fail_if_no_peer_cert, boolean()} {depth, integer()}</c></p>
+	<p><c>| {fail_if_no_peer_cert, boolean()}</c></p>
+	<p><c>| {depth, integer()}</c></p>
 	<p><c>| {cert, public_key:der_encoded()}</c></p>
 	<p><c>| {certfile, path()}</c></p>
 	<p><c>| {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' 
@@ -159,7 +136,7 @@
       <tag><c>sslsocket() =</c></tag>
       <item><p>opaque()</p></item>
 
-      <tag><c>protocol() =</c></tag>
+      <tag><marker id="type-protocol"/><c>protocol() =</c></tag>
       <item><p><c>sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'</c></p></item>
 
       <tag><c>ciphers() =</c></tag>
@@ -479,8 +456,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
       <p>The negotiated protocol can be retrieved using the <c>negotiated_protocol/1</c> function.</p>
       </item>
 
-      <tag><c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()]}}</c></tag>
-      <tag><c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()], Default :: binary()}}</c></tag>
+      <tag><c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()]}}</c><br/>
+      <c>{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()], Default :: binary()}}</c></tag>
 	   <item>
 	   <p>Indicates that the client is to try to perform Next Protocol
 	   Negotiation.</p>
@@ -537,7 +514,6 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	 be supported by the server for the prevention to work.
 	</p></warning>
       </item>
-      
     </taglist>
    </section>
 
@@ -663,11 +639,6 @@ fun(srp, Username :: string(), UserState :: term()) ->
       cipher suite can encipher.
       </item>
 
-      <tag><c>{psk_identity, string()}</c></tag>
-      <item>Specifies the server identity hint the server presents to the client.
-      </item>
-      <tag><c>{log_alert, boolean()}</c></tag>
-      <item>If false, error reports will not be displayed.</item>
       <tag><c>{honor_cipher_order, boolean()}</c></tag>
       <item>If true, use the server's preference for cipher selection. If false
       (the default), use the client's preference.
@@ -770,6 +741,21 @@ fun(srp, Username :: string(), UserState :: term()) ->
     </func>
 
     <func>
+      <name>close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}</name>
+      <fsummary>Closes an SSL 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 later case the transport
+      connection will be handed over to the <c>NewController</c> process after reciving
+      the TLS close alert from the peer. The retuned transport socket will have
+      the following options set [{active, false}, {packet, 0}, {mode, binary}].</p>
+      </desc>
+    </func>
+
+    <func>
 	<name>connection_info(SslSocket) ->
 	  {ok, {ProtocolVersion, CipherSuite}} | {error, Reason}</name>
       <fsummary>Returns the Negotiated Protocol version and cipher suite.
diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml
index 2b6dc7e8be..6c82e32a74 100644
--- a/lib/ssl/doc/src/ssl_app.xml
+++ b/lib/ssl/doc/src/ssl_app.xml
@@ -33,7 +33,33 @@
   <appsummary>The ssl application provides secure communication over
   sockets.</appsummary>
 
-  <description></description>
+  <description>
+    <p>
+      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>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>
+      <item>Ephemeral Diffie-Hellman cipher suites are supported,
+      but not Diffie Hellman Certificates cipher suites.</item>
+      <item>Elliptic Curve cipher suites are supported if the Crypto 
+      application supports it and named curves are used.
+      </item>
+      <item>Export cipher suites are not supported as the
+      U.S. lifted its export restrictions in early 2000.</item>
+      <item>IDEA cipher suites are not supported as they have
+      become deprecated by the latest TLS specification so it is not 
+      motivated to implement them.</item>
+      <item>CRL validation is supported.</item>
+      <item>Policy certificate extensions are not supported.</item>
+      <item>'Server Name Indication' extension client side
+      (RFC 6066, Section 3) is supported.</item>
+    </list>
+   </description>
+
   <section>
     <title>DEPENDENCIES</title>
     <p>The SSL application uses the <c>public_key</c> and
@@ -58,7 +84,7 @@
     <p><c>erl -ssl protocol_version "['tlsv1.2', 'tlsv1.1']"</c></p>
 
     <taglist>
-      <tag><c><![CDATA[protocol_version =  <seealso marker="kernel:error_logger">ssl:protocol()</seealso> <optional>]]></c>.</tag>
+      <tag><c>protocol_version = </c><seealso marker="ssl#type-protocol">ssl:protocol()</seealso><c><![CDATA[<optional>]]></c></tag>
       <item><p>Protocol supported by started clients and
       servers. If this option is not set, it defaults to all
       protocols currently supported by the SSL application.
@@ -66,17 +92,24 @@
       to <c>ssl:connect/[2,3]</c> and <c>ssl:listen/2</c>.</p></item>
 
       <tag><c><![CDATA[session_lifetime = integer() <optional>]]></c></tag>
-      <item><p>Lifetime of the session data in seconds.</p></item>
+      <item><p>Maximum lifetime of the session data in seconds.</p></item>
 
       <tag><c><![CDATA[session_cb = atom() <optional>]]></c></tag>
       <item><p>Name of the session cache callback module that implements
       the <c>ssl_session_cache_api</c> behavior. Defaults to
-      <c>ssl_session_cache.erl</c>.</p></item>
+      <c>ssl_session_cache</c>.</p></item>
 
       <tag><c><![CDATA[session_cb_init_args = proplist:proplist() <optional>]]></c></tag>
 
       <item><p>List of extra user-defined arguments to the <c>init</c> function
       in the session cache callback module. Defaults to <c>[]</c>.</p></item>
+
+      <tag><c><![CDATA[session_cache_client_max = integer() <optional>]]></c><br/>
+      <c><![CDATA[session_cache_server_max = integer() <optional>]]></c></tag>
+      <item><p>Limits the growth of the clients/servers session cache,
+      if the maximum number of sessions is reached, the current cache entries will
+      be invalidated regardless of their remaining lifetime. Defaults to 1000.
+      </p></item>
       
       <tag><c><![CDATA[ssl_pem_cache_clean = integer() <optional>]]></c></tag>
       <item>
@@ -87,12 +120,26 @@
 	    marker="ssl#clear_pem_cache-0">ssl:clear_pem_cache/0</seealso>
 	
       </item>
+      <tag><c><![CDATA[alert_timeout = integer() <optional>]]></c></tag>
+      <item>
+	<p>
+	  Number of milliseconds between sending of a fatal alert and
+	  closing the connection. Waiting a little while improves the
+	  peers chances to properly receiving the alert so it may
+	  shutdown gracefully. Defaults to 5000 milliseconds.   
+	</p>
+      </item>
+
+      
     </taglist>
   </section>
 
   <section>
     <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 turned off with the <c>log_alert</c> option. </p>
+    <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
+    turned off with the <c>log_alert</c> option. </p>
   </section>
 
   <section>
diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml
index 71c1c61fe8..03ac010bfe 100644
--- a/lib/ssl/doc/src/ssl_crl_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache_api.xml
@@ -84,9 +84,9 @@
 	<v> CRLs = [<seealso
 	   marker="public_key:public_key">public_key:der_encoded()</seealso>] </v>
 	</type>
-	<desc> <p>Lookup the CRLs belonging to the distribution point <c> Distributionpoint</c>. </p>
+	<desc> <p>Lookup the CRLs belonging to the distribution point <c> Distributionpoint</c>.
 	This function may choose to only look in the cache or to follow distribution point
-	links depending on how the cache is administrated.
+	links depending on how the cache is administrated. </p>
 	</desc>
     </func>
     
@@ -103,4 +103,4 @@
 	</desc>
     </func>
   </funcs>
-</erlref>
\ No newline at end of file
+</erlref>
diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml
index bd9330056d..b85d8fb284 100644
--- a/lib/ssl/doc/src/ssl_session_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_session_cache_api.xml
@@ -31,9 +31,13 @@
   <module>ssl_session_cache_api</module>
   <modulesummary>TLS session cache API</modulesummary>
 
-  <description>Defines the API for the TLS session cache so
-    that the data storage scheme can be replaced by
-    defining a new callback module implementing this API.</description>
+  <description>
+    <p>
+      Defines the API for the TLS session cache so
+      that the data storage scheme can be replaced by
+      defining a new callback module implementing this API.
+    </p>
+  </description>
   <section>
     <title>DATA TYPES</title>