1 files changed, 65 insertions, 34 deletions

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 4bc1a9a644..19e0ba4c10 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -136,7 +136,7 @@
     </c></p>
 
    <p><c>cipher() = rc4_128 | des_cbc | '3des_ede_cbc'
-      | aes_128_cbc | aes_256_cbc </c></p>
+      | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm </c></p>
 
    <p> <c>hash() = md5 | sha
     </c></p>
@@ -226,7 +226,7 @@
 	<p>The verification fun should be defined as:</p>
 
 	<code>
-fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} |
+fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} |
 	     {extension, #'Extension'{}}, InitialUserState :: term()) ->
 	{valid, UserState :: term()} | {valid_peer, UserState :: term()} |
 	{fail, Reason :: term()} | {unknown, UserState :: term()}.
@@ -252,7 +252,7 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} |
 	always returns {valid, UserState}, the TLS/SSL handshake will
 	not be terminated with respect to verification failures and
 	the connection will be established. If called with an
-	extension unknown to the user application the return value
+	extension unknown to the user application, the return value
 	{unknown, UserState} should be used.</p>
 
 	<p>The default verify_fun option in verify_peer mode:</p>
@@ -283,9 +283,29 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom()} |
  end, []}
       </code>
 
-<p>Possible path validation errors: </p>
+      <p>Possible path validation errors are given on the form {bad_cert, Reason} where Reason is:</p>
 
-<p> {bad_cert, cert_expired}, {bad_cert, invalid_issuer}, {bad_cert, invalid_signature}, {bad_cert, unknown_ca},{bad_cert, selfsigned_peer}, {bad_cert, name_not_permitted}, {bad_cert, missing_basic_constraint}, {bad_cert, invalid_key_usage}</p>
+      <taglist>
+	<tag>unknown_ca</tag>
+	<item>No trusted CA was found in the trusted store. The trusted CA is
+	normally a so called ROOT CA that is a self-signed cert. Trust may
+	be claimed for an intermediat CA (trusted anchor does not have to be self signed
+	according to X-509) by using the option <c>partial_chain</c></item>
+
+	<tag>selfsigned_peer</tag>
+	<item>The chain consisted only of one self-signed certificate.</item>
+
+	<tag>PKIX X-509-path validation error</tag>
+	<item> Possible such reasons see <seealso
+	marker="public_key#pkix_path_validation-3"> public_key:pkix_path_validation/3 </seealso></item>
+      </taglist>
+
+      </item>
+
+      <tag>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | unknown_ca </tag>
+      <item>
+	Claim an intermediat CA in the chain as trusted. TLS will then perform the public_key:pkix_path_validation/3
+	with the selected CA as trusted anchor and the rest of the chain.
       </item>
 
       <tag>{versions, [protocol()]}</tag>
@@ -768,39 +788,45 @@ fun(srp, Username :: string(), UserState :: term()) ->
     </func>
     
     <func>
-      <name>ssl_accept(ListenSocket) -> </name>
-      <name>ssl_accept(ListenSocket, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Perform server-side SSL handshake</fsummary>
+      <name>ssl_accept(Socket) -> </name>
+      <name>ssl_accept(Socket, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Perform server-side SSL/TLS handshake</fsummary>
       <type>
-        <v>ListenSocket = sslsocket()</v>
+        <v>Socket = sslsocket()</v>
         <v>Timeout = integer()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <c>ssl_accept</c> function establish the SSL connection
-          on the server side. It should be called directly after
-          <c>transport_accept</c>, in the spawned server-loop.</p>
+        <p> Performs the SSL/TLS server-side handshake <c>Socket</c> is a socket as returned
+	by  <seealso
+        marker="#transport_accept-2">ssl:transport_accept/[1,2]</seealso>
+	</p>
       </desc>
     </func>
 
     <func>
-      <name>ssl_accept(ListenSocket, SslOptions) -> </name>
-      <name>ssl_accept(ListenSocket, SslOptions, Timeout) -> {ok, Socket} | {error, Reason}</name>
-      <fsummary>Perform server-side SSL handshake</fsummary>
+      <name>ssl_accept(Socket, SslOptions) -> </name>
+      <name>ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}</name>
+      <fsummary>Perform server-side SSL/TLS handshake</fsummary>
       <type>
-        <v>ListenSocket = socket()</v>
+        <v>Socket = socket() | sslsocket() </v>
 	<v>SslOptions = ssloptions()</v>
         <v>Timeout = integer()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p> Upgrades a gen_tcp, or
-	  equivalent, socket to an ssl socket i.e. performs the
-	ssl server-side handshake.</p>
+        <p> If <c>Socket</c> is a socket() - upgrades a gen_tcp, or equivalent, socket to an ssl socket
+        i.e. performs the SSL/TLS server-side handshake and returns the ssl socket.
+	</p>
+	
 	<warning><p>Note that the listen socket should be in {active, false} mode
 	before telling the client that the server is ready to upgrade
-	and calling this function, otherwise the upgrade may
+	by calling this function, otherwise the upgrade may
 	or may not succeed depending on timing.</p></warning>
+	
+	<p> If <c>Socket</c> is an sslsocket() - provides additional SSL/TLS options to those specified in <seealso
+        marker="#listen-2">ssl:listen/2 </seealso> and then performs the SSL/TLS handshake.
+	</p>
       </desc>
     </func>
     
@@ -842,33 +868,38 @@ fun(srp, Username :: string(), UserState :: term()) ->
     </func>
 
     <func>
-      <name>transport_accept(Socket) -></name>
-      <name>transport_accept(Socket, Timeout) ->
+      <name>transport_accept(ListenSocket) -></name>
+      <name>transport_accept(ListenSocket, Timeout) ->
 	{ok, NewSocket} | {error, Reason}</name>
       <fsummary>Accept an incoming connection and
 	prepare for <c>ssl_accept</c></fsummary>
       <type>
-        <v>Socket = NewSocket = sslsocket()</v>
+        <v>ListenSocket = NewSocket = sslsocket()</v>
         <v>Timeout = integer()</v>
         <v>Reason = reason()</v>
       </type>
       <desc>
         <p>Accepts an incoming connection request on a listen socket.
-          <c>ListenSocket</c> must be a socket returned from
-          <c>listen/2</c>.  The socket returned should be passed to
-          <c>ssl_accept</c> to complete ssl handshaking and
-          establishing the connection.</p>
+	<c>ListenSocket</c> must be a socket returned from
+	<seealso
+	    marker="#listen-2"> ssl:listen/2</seealso>.
+	The socket returned should be passed to
+	<seealso marker="#ssl_accept-2"> ssl:ssl_accept[2,3]</seealso>
+	to complete handshaking i.e
+	establishing the SSL/TLS connection.</p>
         <warning>
-          <p>The socket returned can only be used with <c>ssl_accept</c>,
-            no traffic can be sent or received before that call.</p>
+          <p>The socket returned can only be used with
+	  <seealso marker="#ssl_accept-2"> ssl:ssl_accept[2,3]</seealso>
+	  no traffic can be sent or received before that call.</p>
         </warning>
         <p>The accepted socket inherits the options set for
-          <c>ListenSocket</c> in <c>listen/2</c>.</p>
+	<c>ListenSocket</c> in <seealso
+	    marker="#listen-2"> ssl:listen/2</seealso>.</p>
 	<p>The default
-          value for <c>Timeout</c> is <c>infinity</c>. If
-          <c>Timeout</c> is specified, and no connection is accepted
-          within the given time, <c>{error, timeout}</c> is
-          returned.</p>
+	value for <c>Timeout</c> is <c>infinity</c>. If
+	<c>Timeout</c> is specified, and no connection is accepted
+	within the given time, <c>{error, timeout}</c> is
+	returned.</p>
       </desc>
     </func>