path: root/lib/ssl/doc/src/using_ssl.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2020</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>Using SSL application API</title>
    <prepared></prepared>
    <responsible></responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date></date>
    <rev></rev>
    <file>using_ssl.xml</file>
  </header>
  <p>To see relevant version information for ssl, call
  <seemfa marker="ssl:ssl#versions/0"><c>ssl:versions/0</c></seemfa>
  .</p>
    
  <p>To see all supported cipher suites, call  <seemfa marker="ssl:ssl#cipher_suites/1"><c>ssl:cipher_suites(all)</c> </seemfa>. 
  The available cipher suites for a connection depend on your certificate. 
  Specific cipher suites that you want your connection to use can also be 
  specified. Default is to use the strongest available.</p>
  
  <section>
    <title>Setting up Connections</title>
    
    <p>This section shows a small example of how to set up client/server connections
    using the Erlang shell. The returned value of the <c>sslsocket</c> is abbreviated
    with <c>[...]</c> as it can be fairly large and is opaque.</p>
    
    <section>
      <title>Minimal Example</title>
      
      <note><p> The minimal setup is not the most secure setup of TLS/DTLS.</p>    
      </note>

      <p>To set up client/server connections:</p>

      <p><em>Step 1:</em> Start the server side:</p>
      <code type="erl">1 server> ssl:start().
ok</code>
      
      <p><em>Step 2:</em> Create a TLS listen socket: (To run DTLS add the option {protocol, dtls})</p>
      <code type="erl">2 server> {ok, ListenSocket} =
ssl:listen(9999, [{certfile, "cert.pem"}, {keyfile, "key.pem"},{reuseaddr, true}]).
{ok,{sslsocket, [...]}}</code>
      
      <p><em>Step 3:</em> Do a transport accept on the TLS listen socket:</p>
      <code type="erl">3 server> {ok, TLSTransportSocket} = ssl:transport_accept(ListenSocket).
{ok,{sslsocket, [...]}}</code>

      <p><em>Step 4:</em> Start the client side: </p>
      <code type="erl">1 client> ssl:start().
ok</code>
      <p> To run DTLS add the option {protocol, dtls} to third argument.</p>
      <code type="erl">2 client> {ok, Socket} = ssl:connect("localhost", 9999,  [], infinity).
{ok,{sslsocket, [...]}}</code>
      
      <p><em>Step 5:</em> Do the TLS handshake:</p>
      <code type="erl">4 server> {ok, Socket} = ssl:handshake(TLSTransportSocket).
ok</code>
      
      <p><em>Step 6:</em> Send a message over TLS:</p>
      <code type="erl">5 server> ssl:send(Socket, "foo").
ok</code>
      
      <p><em>Step 7:</em> Flush the shell message queue to see that the message
      was sent on the server side:</p>
      <code type="erl">3 client> flush().
Shell got {ssl,{sslsocket,[...]},"foo"}
ok</code>
    </section>
    
    <section>
      <title>Upgrade Example - TLS only </title>
      
      <note><p>To upgrade a TCP/IP connection to a TLS connection, the
      client and server must agree to do so. The agreement
      can be accomplished by using a protocol, for example, the one used by HTTP
      specified in RFC 2817.</p></note>

      <p>To upgrade to a TLS connection:</p>
      
      <p><em>Step 1:</em> Start the server side:</p>
      <code type="erl">1 server> ssl:start().
ok</code>
      
      <p><em>Step 2:</em> Create a normal TCP listen socket:</p>
      <code type="erl">2 server> {ok, ListenSocket} = gen_tcp:listen(9999, [{reuseaddr, true}]).
{ok, #Port&lt;0.475&gt;}</code>
      
      <p><em>Step 3:</em> Accept client connection:</p>
      <code type="erl">3 server> {ok, Socket} = gen_tcp:accept(ListenSocket).
{ok, #Port&lt;0.476&gt;}</code>
      
      <p><em>Step 4:</em> Start the client side:</p>
      <code type="erl">1 client> ssl:start().
ok</code>
      
      <code type="erl">2 client> {ok, Socket} = gen_tcp:connect("localhost", 9999,  [], infinity).</code>
      
      <p><em>Step 5:</em> Ensure <c>active</c> is set to <c>false</c> before trying
      to upgrade a connection to a TLS connection, otherwise
      TLS handshake messages can be delivered to the wrong process:</p>
      <code type="erl">4 server> inet:setopts(Socket, [{active, false}]).
ok</code>
      
      <p><em>Step 6:</em> Do the TLS handshake:</p>
      <code type="erl">5 server> {ok, TLSSocket} = ssl:handshake(Socket, [{cacertfile, "cacerts.pem"},
{certfile, "cert.pem"}, {keyfile, "key.pem"}]).
{ok,{sslsocket,[...]}}</code>
      
      <p><em>Step 7:</em> Upgrade to a TLS connection. The client and server
      must agree upon the upgrade. The server must call
      <c>ssl:handshake/2</c> before the client calls <c>ssl:connect/3.</c></p>
      <code type="erl">3 client>{ok, TLSSocket} = ssl:connect(Socket, [{cacertfile, "cacerts.pem"},
{certfile, "cert.pem"}, {keyfile, "key.pem"}], infinity).
{ok,{sslsocket,[...]}}</code>
      
      <p><em>Step 8:</em> Send a message over TLS:</p>
      <code type="erl">4 client> ssl:send(TLSSocket, "foo").
ok</code>
      
      <p><em>Step 9:</em> Set <c>active true</c> on the TLS socket:</p>
      <code type="erl">4 server> ssl:setopts(TLSSocket, [{active, true}]).
ok</code>
      
      <p><em>Step 10:</em> Flush the shell message queue to see that the message
      was sent on the client side:</p>
      <code type="erl">5 server> flush().
Shell got {ssl,{sslsocket,[...]},"foo"}
ok</code>
    </section>
  </section>

  <section>
    <title>Customizing cipher suits</title>

    <p>Fetch default cipher suite list for a TLS/DTLS version. Change default
    to all to get all possible cipher suites.</p>
    <code type="erl">1>  Default = ssl:cipher_suites(default, 'tlsv1.2').
    [#{cipher => aes_256_gcm,key_exchange => ecdhe_ecdsa,
    mac => aead,prf => sha384}, ....]
</code>

    <p>In OTP 20 it is desirable to remove all cipher suites
    that uses rsa kexchange (removed from default in 21) </p>
    <code type="erl">2> NoRSA =
    ssl:filter_cipher_suites(Default,
                            [{key_exchange, fun(rsa) -> false;
			                       (_) -> true end}]).
    [...]
    </code>

    <p> Pick just a few suites </p>
    <code type="erl"> 3> Suites =
    ssl:filter_cipher_suites(Default,
                            [{key_exchange, fun(ecdh_ecdsa) -> true;
			                       (_) -> false end},
                             {cipher, fun(aes_128_cbc) ->true;
			                  (_) ->false end}]).
    [#{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,
     mac => sha256,prf => sha256},
     #{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,mac => sha,
     prf => default_prf}]
    </code>
    
    <p> Make some particular suites the most preferred, or least
    preferred by changing prepend to append.</p>
    <code type="erl"> 4>ssl:prepend_cipher_suites(Suites, Default).
  [#{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,
     mac => sha256,prf => sha256},
   #{cipher => aes_128_cbc,key_exchange => ecdh_ecdsa,mac => sha,
     prf => default_prf},
   #{cipher => aes_256_cbc,key_exchange => ecdhe_ecdsa,
     mac => sha384,prf => sha384}, ...]
    </code>
  </section>      

  <section>
    <title>Using an Engine Stored Key</title>
    
    <p>Erlang ssl application is able to use private keys provided
    by OpenSSL engines using the following mechanism:</p>
    
    <code type="erl">1> ssl:start().
ok</code>

    <p>Load a crypto engine, should be done once per engine used. For example
    dynamically load the engine called <c>MyEngine</c>:
    </p>
    <code type="erl">2> {ok, EngineRef} =
crypto:engine_load(&lt;&lt;"dynamic">>,
                   [{&lt;&lt;"SO_PATH">>, "/tmp/user/engines/MyEngine"},&lt;&lt;"LOAD">>],[]).
{ok,#Ref&lt;0.2399045421.3028942852.173962>}
    </code>
    
    <p>Create a map with the engine information and the algorithm used by the engine:</p>
    <code type="erl">3> PrivKey =
 #{algorithm => rsa,
   engine => EngineRef,
   key_id => "id of the private key in Engine"}.
    </code>
    <p>Use the map in the ssl key option:</p>
    <code type="erl">4> {ok, SSLSocket} =
ssl:connect("localhost", 9999,
            [{cacertfile, "cacerts.pem"},
             {certfile, "cert.pem"},
             {key, PrivKey}], infinity).
    </code>

    <p>See also <seeguide marker="crypto:engine_load#engine_load"> crypto documentation</seeguide> </p>
    
  </section>

  <section>
    <title>Session Tickets and Session Resumption in TLS 1.3</title>

    <p>
    TLS 1.3 introduces a new secure way of resuming sessions by using session tickets.
    A session ticket is an opaque data structure that is sent in the pre_shared_key extension of
    a ClientHello, when a client attempts to resume a session with keying material from a
    previous successful handshake.</p>
    <p>Session tickets can be stateful or stateless. A stateful session ticket is a database reference
    (session ticket store) and used with stateful servers, while a stateless ticket
    is a self-encrypted and self-authenticated data structure with cryptographic keying material and
    state data, enabling session resumption with stateless servers.</p>
    <p>The choice between stateful or stateless depends on the server requirements as the session tickets
    are opaque for the clients. Generally, stateful tickets are smaller and the server can guarantee
    that tickets are only used once. Stateless tickets contain additional data, require less storage
    on the server side, but they offer different guarantees against anti-replay. See also
    <seeguide marker="ssl:using_ssl#anti-replay-protection-in-tls-1.3">
    Anti-Replay Protection in TLS 1.3</seeguide>
    </p>
    <p>Session tickets are sent by servers on newly estalished TLS connections.
    The number of tickets sent and their lifetime are configurable by application variables. See also
    <seeapp marker="ssl:ssl_app#configuration"> SSL's configuration</seeapp>.</p>
    <p>Session tickets are protected by application traffic keys, and in stateless
    tickets, the opaque data structure itself is self-encrypted.</p>

    <p>An example with automatic and manual session resumption:</p>

    <p><em>Step 1 (server):</em> Start the server:</p>
    <code type="erl">
      {ok, _} = application:ensure_all_started(ssl).
      LOpts = [{certfile, "cert.pem"},
               {keyfile, "key.pem"},
               {versions, ['tlsv1.2','tlsv1.3']},
               {session_tickets, stateless}].
      {ok, LSock} = ssl:listen(8001, LOpts).
      {ok, CSock} = ssl:transport_accept(LSock).
    </code>

    <p><em>Step 2 (client):</em> Start the client and connect to server:</p>
    <code type="erl">
      {ok, _} = application:ensure_all_started(ssl).
      COpts = [{cacertfile, "cert.pem"},
               {versions, ['tlsv1.2','tlsv1.3']},
               {log_level, debug},
               {session_tickets, auto}].
      ssl:connect("localhost", 8001, COpts).
    </code>

    <p><em>Step 3 (server):</em> Start the TLS handshake:</p>
    <code type="erl">
      ssl:handshake(CSock).
    </code>

    <p>A connection is established using a full handshake.
    Below is a summary of the exchanged messages:</p>
    <code type="erl">
      <![CDATA[>>>]]> TLS 1.3 Handshake, ClientHello ...
      <![CDATA[<<<]]> TLS 1.3 Handshake, ServerHello ...
      <![CDATA[<<<]]> Handshake, EncryptedExtensions ...
      <![CDATA[<<<]]> Handshake, Certificate ...
      <![CDATA[<<<]]> Handshake, CertificateVerify ...
      <![CDATA[<<<]]> Handshake, Finished ...
      <![CDATA[>>>]]> Handshake, Finished ...
      <![CDATA[<<<]]> Post-Handshake, NewSessionTicket ...
    </code>

    <p>At this point the client has stored the received session tickets and ready to use them when
    establishing new connections to the same server.</p>

    <p><em>Step 4 (server):</em> Accept a new connection on the server:</p>
    <code type="erl">
      {ok, CSock2} = ssl:transport_accept(LSock).
    </code>

    <p><em>Step 5 (client):</em> Make a new connection:</p>
    <code type="erl">
      ssl:connect("localhost", 8001, COpts).
    </code>

    <p><em>Step 6 (server):</em> Start the handshake:</p>
    <code type="erl">
      ssl:handshake(CSock2).
    </code>

    <p>The second connection is a session resumption using keying material
    from the previous handshake:</p>
    <code type="erl">
      <![CDATA[>>>]]> TLS 1.3 Handshake, ClientHello ...
      <![CDATA[<<<]]> TLS 1.3 Handshake, ServerHello ...
      <![CDATA[<<<]]> Handshake, EncryptedExtensions ...
      <![CDATA[<<<]]> Handshake, Finished ...
      <![CDATA[>>>]]> Handshake, Finished ...
      <![CDATA[<<<]]> Post-Handshake, NewSessionTicket ...
    </code>

    <p>Manual handling of session tickets is also supported. In manual mode, it is the
    responsibility of the client to handle received session tickets.</p>

    <p><em>Step 7 (server):</em> Accept a new connection on the server:</p>
    <code type="erl">
      {ok, CSock3} = ssl:transport_accept(LSock).
    </code>

    <p><em>Step 8 (client):</em> Make a new connection to server:</p>
    <code type="erl">
      {ok, _} = application:ensure_all_started(ssl).
      COpts2 = [{cacertfile, "cert.pem"},
                {versions, ['tlsv1.2','tlsv1.3']},
                {log_level, debug},
                {session_tickets, manual}].
      ssl:connect("localhost", 8001, COpts).
    </code>

    <p><em>Step 9 (server):</em> Start the handshake:</p>
    <code type="erl">
      ssl:handshake(CSock3).
    </code>

    <p>After the handshake is performed, the user process receives messages with the tickets
    sent by the server.</p>

    <p><em>Step 10 (client):</em> Receive a new session ticket:</p>
    <code type="erl">
      Ticket = receive {ssl, session_ticket, {_, TicketData}} -> TicketData end.
    </code>

    <p><em>Step 11 (server):</em> Accept a new connection on the server:</p>
    <code type="erl">
      {ok, CSock4} = ssl:transport_accept(LSock).
    </code>

    <p><em>Step 12 (client):</em> Initiate a new connection to the server with the session ticket
    received in Step 10:</p>
    <code type="erl">
      {ok, _} = application:ensure_all_started(ssl).
      COpts2 = [{cacertfile, "cert.pem"},
                {versions, ['tlsv1.2','tlsv1.3']},
                {log_level, debug},
                {session_tickets, manual},
                {use_ticket, [Ticket]}].
      ssl:connect("localhost", 8001, COpts).
    </code>

    <p><em>Step 13 (server):</em> Start the handshake:</p>
    <code type="erl">
      ssl:handshake(CSock3).
    </code>
  </section>

  <section>
    <title>Anti-Replay Protection in TLS 1.3</title>

    <p>The TLS 1.3 protocol does not provide inherent protection for replay of 0-RTT data but
    describes mechanisms that SHOULD be implemented by compliant server implementations.
    The implementation of TLS 1.3 in the SSL application employs all standard methods
    to prevent potential threats.
    </p>
    <p><em>Single-use tickets</em></p>
    <p>This mechanism is available with stateful session tickets. Session tickets can
    only be used once, subsequent use of the same ticket results in a full handshake.
    Stateful servers enforce this rule by maintaining a database of outstanding valid
    tickets.</p>

    <p><em>Client Hello Recording</em></p>
    <p>This mechanism is available with stateless session tickets. The server records
    a unique value derived from the ClientHello (PSK binder) in a given time window. The
    ticket's age is verified by using both the "obsfuscated_ticket_age" and an additional
    timestamp encrypted in the ticket data. As the used datastore allows false positives,
    apparent replays will be answered by doing a full 1-RTT handshake.</p>

    <p><em>Freshness Checks</em></p>
    <p>This mechanism is available with the stateless session tickets. As the ticket data
    has an embedded timestamp, the server can determine if a ClientHello was sent reasonably
    recently and accept the 0-RTT handshake, otherwise if falls back to a full 1-RTT
    handshake. This mechanism is tightly coupled with the previous one, it prevents storing an
    unlimited number of ClientHellos.</p>

    <p>The current implementation uses a pair of Bloom filters to implement the last two mechanisms.
    Bloom filters are fast, memory-efficient, probabilistic data structures that can tell
    if an element may be in a set or if it is definitely not in the set.</p>

    <p>If the option <seetype marker="ssl:ssl#anti_replay">anti_replay</seetype>
    is defined in the server, a pair of Bloom filters (<em>current</em> and
    <em>old</em>) are used to record incoming ClientHello messages (it is the unique
    binder value that is actually stored).
    The <em>current</em> Bloom filter is used for <c>WindowSize</c> seconds to store new
    elements. At the end of the time window the Bloom filters are rotated
    (the <em>current</em> Bloom filter becomes the <em>old</em> and an empty Bloom filter
    is set as <em>current</em>.
    </p>

    <p>The Anti-Replay protection feature in statless servers executes in the following steps
    when a new ClientHello is received:</p>
    <list type="bulleted">
      <item><p>Reported ticket age (obfuscated ticket age) shall be
      less than ticket lifetime.</p></item>
      <item><p>Actual ticket age shall be less than the ticket lifetime (statless session
      tickets contain the servers timestamp when the ticket was issued).</p></item>
      <item><p>Ticket shall be used within specified time window (freshness checks).</p></item>
      <item><p>If all above checks passed both <em>current</em> and <em>old</em> Bloom filters
      are checked to detect if binder was already seen. Being a probabilistic data structure,
      false positives can occur and they trigger a full handshake.</p></item>
      <item><p>If the binder is not seen, the binder is validated. If the binder is valid,
      the server proceeds with the 0-RTT handshake.</p></item>
    </list>

  </section>
 </chapter>