Merge branch 'ia/ssl-4.0.1/documentation' into dev

* ia/ssl-4.0.1/documentation:
  Updated documentation for ssl-4.0.1

4 files changed, 200 insertions, 127 deletions

diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index def61bcf03..0f3054aec3 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
@@ -69,10 +69,13 @@
     </p>
     
     <p> <c>ssloption() = {verify, verify_type()} |
+      {verify_fun, {fun(), term()}} |
       {fail_if_no_peer_cert, boolean()}
       {depth, integer()} |
-      {certfile, path()} | {keyfile, path()} | {password, string()} |
-      {cacertfile, path()} | {dhfile, path()} | {ciphers, ciphers()} |
+      {cert, der_bin()}| {certfile, path()} |
+      {key, der_bin()} | {keyfile, path()} | {password, string()} |
+      {cacerts, [der_bin()]} | {cacertfile, path()} |
+      |{dh, der_bin()} | {dhfile, path()} | {ciphers, ciphers()} |
       {ssl_imp, ssl_imp()} | {reuse_sessions, boolean()} | {reuse_session, fun()} 
     </c></p>
 
@@ -91,6 +94,8 @@
     <p><c>verify_type() = verify_none | verify_peer</c></p>
     
     <p><c>path() = string() - representing a file path.</c></p>
+
+    <p><c>der_bin() = binary() -Asn1 DER encoded entity as an erlang binary.</c></p>
     
     <p><c>host() = hostname() | ipaddress()</c></p>
         
@@ -121,115 +126,52 @@
     <p><c>ssl_imp() = new | old - default is new.</c></p>
     
   </section>
-  
-<section>
-    <title>SSL OPTION DESCRIPTIONS</title>
+
+  <section>
+    <title>SSL OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT</title>
+
+    <p>Options described here are options that are have the same
+    meaning in the client and the server.
+    </p>
     
     <taglist>
-      <tag>{verify, verify_type()}</tag>
-      <item> If <c>verify_none</c> is specified x509-certificate
-      path validation errors at the client side
-      will not  automatically cause the connection to fail, as
-      it will if the verify type is <c>verify_peer</c>. See also
-      the option verify_fun.
-      Servers only do the path validation if <c>verify_peer</c> is set to
-      true, as it then will 
-      send a certificate request to
-      the client (this message is not sent if the verify option is
-      <c>verify_none</c>) and you may then also want to specify
-      the option <c>fail_if_no_peer_cert</c>.
-      </item>
 
-      <tag>{fail_if_no_peer_cert, boolean()}</tag>
-      <item>Used together with {verify, verify_peer} by a ssl server.
-      If set to true,
-      the server will fail if the client does not have a certificate
-      to send, e.i sends a empty certificate, if set to false it will
-      only fail if the client sends a invalid certificate (an empty
-      certificate is considered valid).
-      </item>
+      <tag>{cert, der_bin()}</tag>
+      <item> The DER encoded users certificate. If this option
+      is supplied it will override the certfile option.</item>
       
-      <tag>{verify_fun, fun(ErrorList) -> boolean()}</tag>
-      <item>Used by the ssl client to determine if 
-	x509-certificate path validations errors are acceptable or
-	if the connection should fail. Defaults to:
-       
-<code>
-fun(ErrorList) ->
-	case lists:foldl(fun({bad_cert,unknown_ca}, Acc) ->
-						  Acc;
-			    (Other, Acc) ->
-				 [Other | Acc]
-			 end, [], ErrorList) of
-	    [] ->
-		true;
-	    [_|_] ->
-		false
-	end
-end
-</code>
-       I.e. by default if the only error found was that the CA-certificate
-       holder was unknown this will be accepted.
-
-       Possible errors in the error list are: 
-       {bad_cert, cert_expired}, {bad_cert, invalid_issuer},
-       {bad_cert, invalid_signature}, {bad_cert, name_not_permitted},
-       {bad_cert, unknown_ca},
-       {bad_cert, cert_expired}, {bad_cert, invalid_issuer},
-       {bad_cert, invalid_signature}, {bad_cert, name_not_permitted},
-       {bad_cert, cert_revoked} (not implemented yet),
-       {bad_cert, unknown_critical_extension} or {bad_cert, term()}
-      </item>
-
+      <tag>{certfile, path()}</tag>
+      <item>Path to a file containing the user's certificate.</item>
       
-      <tag>{validate_extensions_fun, fun()}</tag>
-      <item>
-	This options makes it possible to supply a fun to validate
-	possible application specific certificate extensions
-	during the certificat path validation. This option
-	will be better documented onec the public_key API is more
-	mature.
-      </item>
+      <tag>{key, der_bin()}</tag>
+      <item> The DER encoded users private key. If this option
+      is supplied it will override the keyfile option.</item>
       
-      <tag>{depth, integer()}</tag>
-      <item>Specifies the maximum
-      verification depth, i.e. how far in a chain of certificates the
-      verification process can proceed before the verification is
-      considered to fail. Peer certificate = 0, CA certificate = 1,
-      higher level CA certificate = 2, etc.  The value 2 thus means
-      that a chain can at most contain peer cert, CA cert, next CA
-      cert, and an additional CA cert. The default value is 1.
-      </item>
-
-      <tag>{certfile, path()}</tag>
-      <item>Path to a file containing the
-          user's certificate. Optional for clients but note
-      that some servers requires that the client can certify
-      itself. </item>
       <tag>{keyfile, path()}</tag>
       <item>Path to file containing user's
       private PEM encoded key. As PEM-files may contain several
       entries this option defaults to the same file as given by
       certfile option.</item>
+
       <tag>{password, string()}</tag>
       <item>String containing the user's password.
 	Only used if the private keyfile is password protected.
       </item>
+
+      <tag>{cacerts, [der_bin()]}</tag>
+      <item> The DER encoded trusted certificates. If this option
+      is supplied it will override the cacertfile option.</item>
+
       <tag>{cacertfile, path()}</tag>
       <item>Path to file containing PEM encoded
       CA certificates (trusted certificates used for verifying a peer
       certificate). May be omitted if you do not want to verify
       the peer.</item>
 
-      <tag>{dhfile, path()}</tag>
-      <item>Path to file containing PEM encoded Diffie Hellman parameters,
-      for the server to use if a cipher suite using Diffie Hellman key exchange
-      is negotiated. If not specified hardcode parameters will be used.
-      </item>
-      
       <tag>{ciphers, ciphers()}</tag>
-      <item>The function <c>ciphers_suites/0</c> can
-	be used to find all available ciphers.
+      <item>The cipher suites that should be supported. The function
+      <c>ciphers_suites/0</c> can be used to find all available
+      ciphers.
       </item>
 
       <tag>{ssl_imp, ssl_imp()}</tag>
@@ -237,13 +179,152 @@ end
       new.
       </item>
 
+      <tag>{secure_renegotiate, boolean()}</tag>
+      <item>Specifies if to reject renegotiation attempt that does
+      not live up to RFC 5746. By default secure_renegotiate is
+      set to false i.e. secure renegotiation will be used if possible
+      but it will fallback to unsecure renegotiation if the peer
+      does not support RFC 5746.
+      </item>
+
+      <tag>{depth, integer()}</tag>
+      <item>Specifies the maximum
+      verification depth, i.e. how far in a chain of certificates the
+      verification process can proceed before the verification is
+      considered to fail. Peer certificate = 0, CA certificate = 1,
+      higher level CA certificate = 2, etc.  The value 2 thus means
+      that a chain can at most contain peer cert, CA cert, next CA
+      cert, and an additional CA cert. The default value is 1.
+      </item>
+
+      <tag>{verify_fun, {Verifyfun :: fun(), InitialUserState :: term()}}</tag>
+      <item>
+	<p>The verification fun should be defined as:</p>
+
+	<code>
+	  fun(OtpCert :: #'OtpCertificate'{},
+	      Event :: {bad_cert, Reason :: atom()} |
+	      {extension, #'Extension'{}}, InitialUserState :: term()) ->
+	          {valid, UserState :: term()} | {fail, Reason :: term()} |
+	          {unknown, UserState :: term()}.
+	</code>
+
+	<p>The verify fun will be called during the X509-path
+	validation when an error or an extension unknown to the ssl
+	application is encountered. See
+	<seealso marker="public_key:application">public_key(3)</seealso>
+	for definition of #'OtpCertificate'{} and #'Extension'{}.</p>
+
+	<p>If the verify callback fun returns {fail, Reason}, the
+	verification process is immediately stopped and an alert is
+	sent to the peer and the TLS/SSL handshake is terminated. If
+	the verify callback fun returns {valid, UserState}, the
+	verification process is continued.  If the verify callback fun
+	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
+	{unknown, UserState} should be used.</p>
+
+	<p>The default verify_fun option in verify_peer mode:</p>
+
+      <code>
+	{fun(_,{bad_cert, _} = Reason, _) ->
+		 {fail, Reason};
+	    (_,{extension, _}, UserState) ->
+		 {unknown, UserState}
+	 end, []}
+      </code>
+
+      <p>The default verify_fun option in verify_none mode:</p>
+
+       <code>
+	{fun(_,{bad_cert, unknown_ca}, UserState) ->
+		 {valid, UserState};
+	    (_,{bad_cert, _} = Reason, _) ->
+		 {fail, Reason};
+	    (_,{extension, _}, UserState) ->
+		 {unknown, UserState}
+	 end, []}
+      </code>
+
+      <p> Possible path validation errors:
+       {bad_cert, cert_expired},
+       {bad_cert, invalid_issuer},
+       {bad_cert, invalid_signature},
+       {bad_cert, unknown_ca},
+       {bad_cert, name_not_permitted},
+       {bad_cert, missing_basic_constraint},
+       {bad_cert, invalid_key_usage},
+       {bad_cert, invalid_subject_altname}</p>
+      </item>
+
+    </taglist>
+
+  </section>
+
+   <section>
+    <title>SSL OPTION DESCRIPTIONS - CLIENT SIDE</title>
+
+    <p>Option described here are client specific or has a slightly different
+    meaning in the client than in the server.</p>
+
+    <taglist>
+      <tag>{verify, verify_type()}</tag>
+      <item> In verify_none mode the x509-path validation error {bad_cert, unknown_ca}
+      will automatically be accepted. See also the verify_fun option.
+      </item>
+      <tag>{reuse_sessions, boolean()}</tag>
+      <item>Specifies if client should try to reuse sessions
+      when possible.
+      </item>
+
+    </taglist>
+  </section>
+
+  <section>
+    <title>SSL OPTION DESCRIPTIONS - SERVER SIDE</title>
+
+    <p>Option described here are server specific or has a slightly different
+    meaning in the server than in the client.</p>
+
+    <taglist>
+
+      <tag>{dh, der_bin()}</tag>
+      <item>The DER encoded Diffie Hellman parameters. If this option
+      is supplied it will override the dhfile option.
+      </item>
+
+      <tag>{dhfile, path()}</tag>
+      <item>Path to file containing PEM encoded Diffie Hellman parameters,
+      for the server to use if a cipher suite using Diffie Hellman key exchange
+      is negotiated. If not specified default parameters will be used.
+      </item>
+
+      <tag>{verify, verify_type()}</tag>
+      <item>Servers only do the x509-path validation in verify_peer
+      mode, as it then will send a certificate request to the client
+      (this message is not sent if the verify option is verify_none)
+      and you may then also want to specify the option
+      fail_if_no_peer_cert.
+      </item>
+
+      <tag>{fail_if_no_peer_cert, boolean()}</tag>
+      <item>Used together with {verify, verify_peer} by a ssl server.
+      If set to true, the server will fail if the client does not have
+      a certificate to send, i.e. sends a empty certificate, if set to
+      false it will only fail if the client sends a invalid
+      certificate (an empty certificate is considered valid).
+      </item>
+
       <tag>{reuse_sessions, boolean()}</tag>
-      <item>Specifies if ssl sessions should be reused
-	when possible.
+      <item>Specifies if the server should agree to reuse sessions
+      when the clients request to do so. See also the reuse_session
+      option.
       </item>
 
-       <tag>{reuse_session, fun(SuggestedSessionId,
-       PeerCert, Compression, CipherSuite) -> boolean()}</tag>
+      <tag>{reuse_session, fun(SuggestedSessionId,
+      PeerCert, Compression, CipherSuite) -> boolean()}</tag>
       <item>Enables the ssl server to have a local policy
       for deciding if a session should be reused or not,
       only meaning full if <c>reuse_sessions</c> is set to true.
@@ -252,14 +333,6 @@ end
       and CipherSuite of type ciphersuite().      
       </item>
 
-      <tag>{secure_renegotiate, boolean()}</tag>
-      <item>Specifies if to reject renegotiation attempt that does
-      not live up to RFC 5746. By default secure_renegotiate is
-      set to false e.i. secure renegotiation will be used if possible
-      but it will fallback to unsecure renegotiation if the peer
-      does not support  RFC 5746.
-      </item>
-
     </taglist>
   </section>
   
@@ -316,7 +389,7 @@ end
 	<v>Reason = term()</v>
       </type>
       <desc> <p>Upgrades a gen_tcp, or equivalent,
-	  connected socket to a ssl socket e.i performs the
+	  connected socket to a ssl socket i.e. performs the
 	  client-side ssl handshake.</p>
     </desc>
     </func>
@@ -559,12 +632,12 @@ end
       </type>
       <desc>
         <p> Upgrades a gen_tcp, or
-	  equivalent, socket to a ssl socket e.i performs the
+	  equivalent, socket to a ssl socket i.e. performs the
 	ssl server-side handshake.</p>
-	<p><note>Note that the listen socket should be in {active, false} mode
+	<p><warning>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
-	or may not succeed depending on timing.</note></p>
+	or may not succeed depending on timing.</warning></p>
       </desc>
     </func>
     
diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml
index 4067fb8a22..7bcc12eb5f 100644
--- a/lib/ssl/doc/src/ssl_distribution.xml
+++ b/lib/ssl/doc/src/ssl_distribution.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE chapter SYSTEM "chapter.dtd">
 
 <chapter>
   <header>
     <copyright>
-      <year>2000</year><year>2009</year>
+      <year>2000</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -36,7 +36,7 @@
 
     <note><p>Note this
     documentation is written for the old ssl implementation and
-    will be updated for the new one once this functionallity is
+    will be updated for the new one once this functionality is
     supported by the new implementation.</p></note>
   </p>
 
@@ -55,7 +55,7 @@
       all participating Erlang nodes in a distributed system must use
       this distribution module.</p>
     <p>The security depends on how the connections are set up, one can
-      use key files or certificates to just get a crypted
+      use key files or certificates to just get a encrypted
       connection. One can also make the SSL package verify the
       certificates of other nodes to get additional security. 
       Cookies are however always used as they can be used to
@@ -179,7 +179,7 @@ Eshell V5.0  (abort with ^G)
       <c>certfile</c> can (and usually needs to) be specified as
       <c>client_certfile</c> and <c>server_certfile</c>. The
       <c>client_certfile</c> is used when the distribution initiates a
-      connection to another node and the <c>server_cerfile</c> is used
+      connection to another node and the <c>server_certfile</c> is used
       when accepting a connection from a remote node. </p>
     <p>The command line argument for specifying the SSL options is named 
       <c>-ssl_dist_opt</c> and should be followed by an even number of
diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml
index 726b9a4eeb..6936408881 100644
--- a/lib/ssl/doc/src/ssl_protocol.xml
+++ b/lib/ssl/doc/src/ssl_protocol.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE chapter SYSTEM "chapter.dtd">
 
 <chapter>
   <header>
     <copyright>
-      <year>2003</year><year>2009</year>
+      <year>2003</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -44,7 +44,7 @@
   <section>
     <title>Security overview</title>
       
-    <p>To achive authentication and privacy the client and server will
+   <p>To achieve authentication and privacy the client and server will
     perform a TLS Handshake procedure before transmitting or receiving
     any data. During the handshake they agree on a protocol version and
     cryptographic algorithms, they generate shared secrets using public
@@ -56,7 +56,7 @@
     <title>Data Privacy and Integrity</title>
     
     <p>A <em>symmetric key</em> algorithm has one key only. The key is
-    used for both encryption and decryption. These algoritms are fast
+    used for both encryption and decryption. These algorithms are fast
     compared to public key algorithms (using two keys, a public and a
     private one) and are therefore typically used for encrypting bulk
     data.
@@ -66,7 +66,7 @@
     for each connection and are based on a secret negotiated
     in the TLS handshake. </p>
     
-    <p>The TLS handsake protocol and data transfer is run on top of
+   <p>The TLS handshake protocol and data transfer is run on top of
     the TLS Record Protocol that uses a keyed-hash MAC (Message
     Authenticity Code), or HMAC, to protect the message's data
     integrity. From the TLS RFC "A Message Authentication Code is a
@@ -85,7 +85,7 @@
      with the private key of the issuer of the certificate. A chain
      of trust is build by having the issuer in its turn being
      certified by an other certificate and so on until you reach the
-     so called root certificate that is self signed e.i. issued
+     so called root certificate that is self signed i.e. issued
      by itself.</p>
      
      <p>Certificates are issued by <em>certification
diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml
index 7b70c6cf34..e0b07961fb 100644
--- a/lib/ssl/doc/src/ssl_session_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_session_cache_api.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
@@ -25,7 +25,7 @@
   </header>
   <module>ssl_session_cache_api</module>
   <modulesummary>Defines the API for the TLS session cache so
-    that the datastorge scheme can be replaced by
+    that the data storage scheme can be replaced by
     defining a new callback module implementing this API.</modulesummary>
 
   <section>
@@ -56,7 +56,7 @@
 	<v> Key  = key()</v>
       </type>
       <desc>
-	<p> Delets a cache entry. Will only be called from the cache
+	<p> Deletes a cache entry. Will only be called from the cache
 	handling process.
 	</p>
       </desc>
@@ -85,10 +85,10 @@
 	<v></v>
       </type>
       <desc>
-	<p>Performes possible initializations of the cache and returns
+	<p>Performs possible initializations of the cache and returns
 	a reference to it that will be used as parameter to the other
 	api functions. Will be called by the cache handling processes
-	init function, hence puting the same requierments on it as
+	init function, hence putting the same requirements on it as
 	a normal process init function.
 	</p>
       </desc>
@@ -96,16 +96,16 @@
 
     <func>
       <name>lookup(Cache, Key) -> Entry</name>
-      <fsummary> Looks up a cach entry.</fsummary>
+      <fsummary> Looks up a cache entry.</fsummary>
       <type>
 	<v> Cache = cache_ref()</v>
 	<v> Key  = key()</v>
 	<v> Entry = session() | undefined </v>
       </type>
       <desc>
-	<p>Looks up a cach entry. Should be callable from any
-	process.
-	</p>
+	<p>Looks up a cache entry. Should be callable from any
+         process.
+         </p>
       </desc>
     </func>
     
@@ -127,7 +127,7 @@
     <func>
       <name>terminate(Cache) -> _</name>
       <fsummary>Called by the process that handles the cache when it
-      is aboute to terminat.</fsummary>
+      is about to terminate.</fsummary>
       <type>
 	<v>Cache = term()  - as returned by init/0</v>
       </type>