<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2010</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
      
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
      
    </legalnotice>

    <title>Transport Layer Security (TLS) and its predecessor, Secure Socket Layer (SSL)</title>
    <file>ssl_protocol.xml</file>
  </header>
  
  <p>The erlang ssl application currently supports SSL 3.0 and TLS 1.0
  RFC 2246, and will in the future also support later versions of TLS.
  SSL 2.0 is not supported.
  </p>

  <p>By default erlang ssl is run over the TCP/IP protocol even
  though you could plug in an other reliable transport protocol
  with the same API as gen_tcp.</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 a 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
  implementing virtual hosting.
  </p>

  <section>
    <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
    digital certificates.</p>
  </section>
  
  <section>
    <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
    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>
    
   <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
    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."
    </p>
    
  </section>

   <section>
     <title>Digital Certificates</title>
     <p>A certificate is similar to a driver's license, or a
     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 an other certificate and so on until you reach the
     so called root certificate that is self signed i.e. 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
     through the menus of your web browser.
     </p>
   </section>
	   
   <section>
     <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>
     
     <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
     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
     or reject an "empty" certificate as response to
     a certificate request.</p>
   </section>
  
   <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
     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
     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>

     <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>

   </section>
 </chapter>


