<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2003</year><year>2015</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>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 <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 <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 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>
<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>
<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, 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>
<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."
</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 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 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>
<section>
<title>Peer Authentication</title>
<p>Authentication of the peer is done by public key path
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 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 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>
<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 <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 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>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>
