ssl: Editorial updates

1 files changed, 69 insertions, 57 deletions

diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml
index 80d9cc4ee8..79162389ae 100644
--- a/lib/ssl/doc/src/ssl_protocol.xml
+++ b/lib/ssl/doc/src/ssl_protocol.xml
@@ -21,33 +21,42 @@
       
     </legalnotice>
 
-    <title>Transport Layer Security (TLS) and its predecessor, Secure Socket Layer (SSL)</title>
+    <title>TLS and its Predecessor, SSL</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
     <file>ssl_protocol.xml</file>
   </header>
   
-  <p>The erlang SSL application currently implements the protocol SSL/TLS
-  for currently supported versions see <seealso marker="ssl">ssl(3)</seealso>
+  <p>The Erlang <c>ssl</c> application implements the SSL/TLS protocol
+  for the currently supported versions,  see the
+  <seealso marker="ssl">ssl(3)</seealso> manual page.
   </p>
 
-  <p>By default erlang SSL is run over the TCP/IP protocol even
-  though you could plug in any other reliable transport protocol
-  with the same API as gen_tcp.</p>
+  <p>By default <c>ssl</c> is run over the TCP/IP protocol even
+  though you can plug in any other reliable transport protocol
+  with the same Application Programming Interface (API) as the
+  <c>gen_tcp</c> module in <c>kernel</c>.</p>
   
-  <p>If a client and server wants to use an upgrade mechanism, such as
-  defined by RFC2817, to upgrade a regular TCP/IP connection to an SSL
-  connection the erlang SSL API supports this. This can be useful for
-  things such as supporting HTTP and HTTPS on the same port and
+  <p>If a client and a server wants to use an upgrade mechanism, such as
+  defined by RFC 2817, to upgrade a regular TCP/IP connection to an SSL
+  connection, this is supported by the Erlang <c>ssl</c> API. This can be 
+  useful for, for example, supporting HTTP and HTTPS on the same port and
   implementing virtual hosting.
   </p>
 
   <section>
-    <title>Security overview</title>
+    <title>Security Overview</title>
       
-   <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
-    key cryptographics and optionally authenticate each other with
+   <p>To achieve authentication and privacy, the client and server
+    perform a TLS handshake procedure before transmitting or receiving
+    any data. During the handshake, they agree on a protocol version and
+    cryptographic algorithms, generate shared secrets using public
+    key cryptographies, and optionally authenticate each other with
     digital certificates.</p>
   </section>
   
@@ -55,20 +64,21 @@
     <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 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
+    used for both encryption and decryption. These algorithms are fast,
+    compared to public key algorithms (using two keys, one public and one
+    private) and are therefore typically used for encrypting bulk
     data.
     </p>
     
     <p>The keys for the symmetric encryption are generated uniquely
     for each connection and are based on a secret negotiated
-    in the TLS handshake. </p>
+    in the TLS handshake.</p>
     
-   <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
+    <p>The TLS handshake protocol and data transfer is run on top of
+    the TLS Record Protocol, which uses a keyed-hash Message
+    Authenticity Code (MAC), or a Hash-based MAC (HMAC),
+    to protect the message data
+    integrity. From the TLS RFC: "A Message Authentication Code is a
     one-way hash computed from a message and some secret data. It is
     difficult to forge without knowing the secret data. Its purpose is
     to detect if the message has been altered."
@@ -82,15 +92,14 @@
      passport. The holder of the certificate is called the
      <em>subject</em>. The certificate is signed 
      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 another certificate and so on until you reach the
-     so called root certificate that is self signed i.e. issued
+     of trust is built by having the issuer in its turn being
+     certified by another certificate, and so on, until you reach the
+     so called root certificate, which is self-signed, that is, issued
      by itself.</p>
      
-     <p>Certificates are issued by <em>certification
-     authorities</em> (<em>CA</em>s) only.  There are a handful of
-     top CAs in the world that issue root certificates. You can
-     examine the certificates of several of them by clicking
+     <p>Certificates are issued by Certification Authorities (CAs) only. 
+     A handful of top CAs in the world issue root certificates. You can
+     examine several of these certificates by clicking
      through the menus of your web browser.
      </p>
    </section>
@@ -99,23 +108,27 @@
      <title>Authentication of Sender</title>
       
      <p>Authentication of the sender is done by public key path
-     validation as defined in RFC 3280. Simplified that means that
-     each certificate in the certificate chain is issued by the one
-     before, the certificates attributes are valid ones, and the
-     root cert is a trusted cert that is present in the trusted
-     certs database kept by the peer.</p>
+     validation as defined in RFC 3280. This means basically 
+     the following:</p>
+     <list type="bulleted">
+       <item>Each certificate in the certificate chain is issued by the 
+       previous one.</item>
+       <item>The certificates attributes are valid.</item>
+       <item>The root certificate is a trusted certificate that is present 
+       in the trusted certificate database kept by the peer./</item>
+     </list>
      
-     <p>The server will always send a certificate chain as part of
-     the TLS handshake, but the client will only send one if
-     the server requests it. If the client does not have
-     an appropriate certificate it may send an "empty" certificate
+     <p>The server always sends a certificate chain as part of
+     the TLS handshake, but the client only sends one if requested
+     by the server. If the client does not have
+     an appropriate certificate, it can send an "empty" certificate
      to the server.</p>
      
-     <p>The client may choose to accept some path evaluation errors
-     for instance a web browser may ask the user if they want to
-     accept an unknown CA root certificate. The server, if it request
-     a certificate, will on the other hand not accept any path validation
-     errors. It is configurable if the server should accept
+     <p>The client can choose to accept some path evaluation errors,
+     for example, a web browser can ask the user whether to
+     accept an unknown CA root certificate. The server, if it requests
+     a certificate, does however not accept any path validation
+     errors. It is configurable if the server is to accept
      or reject an "empty" certificate as response to
      a certificate request.</p>
    </section>
@@ -123,25 +136,24 @@
    <section>
      <title>TLS Sessions</title>
      
-     <p>From the TLS RFC "A TLS session is an association between a
-     client and a server.  Sessions are created by the handshake
+     <p>From the TLS RFC: "A TLS session is an association between a
+     client and a server. Sessions are created by the handshake
      protocol. Sessions define a set of cryptographic security
      parameters, which can be shared among multiple
      connections. Sessions are used to avoid the expensive negotiation
      of new security parameters for each connection."</p>
 
-     <p>Session data is by default kept by the SSL application in a
-     memory storage hence session data will be lost at application
-     restart or takeover. Users may define their own callback module
+     <p>Session data is by default kept by the <c>ssl</c> application in a
+     memory storage, hence session data is lost at application
+     restart or takeover. Users can define their own callback module
      to handle session data storage if persistent data storage is
-     required. Session data will also be invalidated after 24 hours
-     from it was saved, for security reasons. It is of course
-     possible to configure the amount of time the session data should be
-     saved.</p>
+     required. Session data is also invalidated after 24 hours
+     from it was saved, for security reasons. The amount of time the 
+     session data is to be saved can be configured.</p>
 
-     <p>SSL clients will by default try to reuse an available session,
-     SSL servers will by default agree to reuse sessions when clients
-     ask to do so.</p>
+     <p>By default the SSL clients try to reuse an available session and 
+     by default the SSL servers agree to reuse sessions when clients
+     ask for it.</p>
 
    </section>
  </chapter>