User's Guide
Reference Manual
Release Notes
PDF
Top

Secure Socket Layer
User's Guide
Version 5.1

Expand All
Contract All

Chapters

- Transport Layer Security (TLS) and its predecessor, Secure Socket Layer (SSL)
  - Top of chapter
  - Security overview
  - Data Privacy and Integrity
  - Digital Certificates
  - Authentication of Sender
  - TLS Sessions
- Using the SSL API
  - Top of chapter
  - General information
  - Setting up connections
- Using SSL for Erlang Distribution
  - Top of chapter
  - Introduction
  - Building boot scripts including the SSL application
  - Specifying distribution module for net_kernel
  - Specifying SSL options
  - Setting up environment to always use SSL

# 1 Transport Layer Security (TLS) and its predecessor, Secure Socket Layer (SSL)

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.

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.

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 implementing virtual hosting.

### 1.1 Security overview

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.

### 1.2 Data Privacy and Integrity

A symmetric key 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.

The keys for the symmetric encryption are generated uniquely for each connection and are based on a secret negotiated in the TLS handshake.

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

### 1.3 Digital Certificates

A certificate is similar to a driver's license, or a passport. The holder of the certificate is called the subject. 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.

Certificates are issued by certification authorities (CAs) 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.

### 1.4 Authentication of Sender

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.

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.

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.

### 1.5 TLS Sessions

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

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.

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.