From 88021d58ff1c5b92689b100d1288ef7d3185233f Mon Sep 17 00:00:00 2001
From: Ingela Anderton Andin <ingela@erlang.org>
Date: Mon, 1 Feb 2016 21:15:45 +0100
Subject: ssl: Include options form connect/listen/accept in
 connection_information/[1,2]

Make sure that options only relevant for one role (client|server) is set
to undefined when the other role is invoked. As there are many options to
ssl, and many are optional, we choose to filter out all undefined options
to avoid overwhelming the user with not relevant information.
This way there is no need for any special handling of the role specific options
which is also nice.
---
 lib/ssl/doc/src/ssl.xml | 57 ++++++++++++++++++-------------------------------
 1 file changed, 21 insertions(+), 36 deletions(-)

(limited to 'lib/ssl/doc/src')

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index aaf03d1cd8..d3881ad117 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -144,7 +144,9 @@
       <p>According to old API.</p></item>
 
       <tag><c>ciphersuite() =</c></tag>
-      <item><p><c>{key_exchange(), cipher(), hash()}</c></p></item>
+
+      <item><p><c>{key_exchange(), cipher(), MAC::hash()} |
+      {key_exchange(), cipher(), MAC::hash(), PRF::hash()}</c></p></item>
 
       <tag><c>key_exchange()=</c></tag>
       <item><p><c>rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk
@@ -156,7 +158,7 @@
       | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm</c></p></item>
 
       <tag><c>hash() =</c></tag>
-      <item><p><c>md5 | sha</c></p></item>
+      <item><p><c>md5 | sha | sha224 | sha256 | sha348 | sha512</c></p></item>
 
       <tag><c>prf_random() =</c></tag>
       <item><p><c>client_random | server_random</c></p></item>
@@ -754,20 +756,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
       the following options set: <c>[{active, false}, {packet, 0}, {mode, binary}]</c></p>
       </desc>
     </func>
-
-    <func>
-	<name>connection_info(SslSocket) ->
-	  {ok, {ProtocolVersion, CipherSuite}} | {error, Reason}</name>
-      <fsummary>Returns the Negotiated Protocol version and cipher suite.
-      </fsummary>
-      <type>
-        <v>CipherSuite = ciphersuite()</v>
-        <v>ProtocolVersion = protocol()</v>
-      </type>
-      <desc><p>Returns the Negotiated Protocol version and cipher suite.</p> 
-      </desc>
-    </func>
-
+    
     <func>
       <name>controlling_process(SslSocket, NewOwner) ->
 	ok | {error, Reason}</name>
@@ -786,40 +775,36 @@ fun(srp, Username :: string(), UserState :: term()) ->
 
     <func>
       <name>connection_information(SslSocket) ->
-        {ok, Info} |  {error, Reason} </name>
+        {ok, Result} |  {error, Reason} </name>
       <fsummary>Returns all the connection information.
       </fsummary>
       <type>
-        <v>Info = [InfoTuple]</v>
-        <v>InfoTuple = {protocol, Protocol} | {cipher_suite, CipherSuite} | {sni_hostname, SNIHostname}</v>
-        <v>CipherSuite = ciphersuite()</v>
-        <v>ProtocolVersion = protocol()</v>
-        <v>SNIHostname = string()</v>
+        <v>Item = protocol | cipher_suite | sni_hostname | atom()</v>
+	<d>Meaningful atoms, not specified above, are the ssl option names.</d>
+	<v>Result = [{Item::atom(), Value::term()}]</v>
         <v>Reason = term()</v>
       </type>
-      <desc><p>Return all the connection information containing negotiated protocol version, cipher suite, and the hostname of SNI extension.
-      Info will be a proplists containing all the connection information on success, otherwise <c>{error, Reason}</c> will be returned.</p> 
+      <desc><p>Returns all relevant information about the connection, ssl options that
+      are undefined will be filtered out.</p>
       </desc>
     </func>
 
     <func>
       <name>connection_information(SslSocket, Items) ->
-        {ok, Info} |  {error, Reason} </name>
+        {ok, Result} |  {error, Reason} </name>
       <fsummary>Returns the requested connection information.
       </fsummary>
       <type>
-        <v>Items = [Item]</v>
-        <v>Item = protocol | cipher_suite | sni_hostname</v>
-        <v>Info = [InfoTuple]</v>
-        <v>InfoTuple = {protocol, Protocol} | {cipher_suite, CipherSuite} | {sni_hostname, SNIHostname}</v>
-        <v>CipherSuite = ciphersuite()</v>
-        <v>ProtocolVersion = protocol()</v>
-        <v>SNIHostname = string()</v>
+	<v>Items = [Item]</v>
+	<v>Item = protocol | cipher_suite | sni_hostname | atom()</v>
+	<d>Meaningful atoms, not specified above, are the ssl option names.</d>
+	<v>Result = [{Item::atom(), Value::term()}]</v>
         <v>Reason = term()</v>
       </type>
-      <desc><p>Returns the connection information you requested. The connection information you can request contains protocol, cipher_suite, and sni_hostname.
-      <c>{ok, Info}</c> will be returned if it executes successfully. <c>Info</c> is a proplist containing the information you requested.
-      Otherwise, <c>{error, Reason}</c> will be returned.</p>
+      <desc><p>Returns the requested information items about the connection,
+      if they are defined.</p>
+      <note><p>If only undefined options are requested the
+      resulting list can be empty.</p></note>
       </desc>
     </func>
 
@@ -1146,7 +1131,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
 	  <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
-	  marker="#connection_info-1">ssl:connection_info/1
+	  marker="#connection_information-1">ssl:connection_information/1
 	  </seealso>.</item>
   
 	  <tag><c>available</c></tag>
-- 
cgit v1.2.3