diff options
Diffstat (limited to 'lib/ssl/doc/src/using_ssl.xml')
| -rw-r--r-- | lib/ssl/doc/src/using_ssl.xml | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml index 4a66bf9d90..7f45b72db9 100644 --- a/lib/ssl/doc/src/using_ssl.xml +++ b/lib/ssl/doc/src/using_ssl.xml @@ -559,6 +559,120 @@ ok </section> <section> + <title>Early Data in TLS 1.3</title> + <p>TLS 1.3 allows clients to send data on the first flight if the endpoints have + a shared crypographic secret (pre-shared key). This means that clients can send + early data if they have a valid session ticket received in a previous + successful handshake. For more information about session resumption see + <seeguide marker="ssl:using_ssl#session-tickets-and-session-resumption-in-tls-1.3"> + Session Tickets and Session Resumption in TLS 1.3</seeguide>. + </p> + <p>The security properties of Early Data are weaker than other kinds of TLS data. + This data is not forward secret, and it is vulnerable to replay attacks. For available + mitigation strategies see + <seeguide marker="ssl:using_ssl#anti-replay-protection-in-tls-1.3"> + Anti-Replay Protection in TLS 1.3</seeguide>.</p> + <p>In normal operation, clients will not know which, if any, of the available mitigation + strategies servers actually implement, and hence must only send early data which + they deem safe to be replayed. For example, idempotent HTTP operations, such as HEAD and + GET, can usually be regarded as safe but even they can be exploited by a large number of + replays causing resource limit exhaustion and other similar problems.</p> + <p>An example of sending early data with automatic and manual session ticket handling:</p> + <warning> + <p>The Early Data feature is experimental in this version of OTP. + </p> + </warning> + + <p><em>Server (with NSS key logging)</em></p> + <code type="none"> + early_data_server() -> + application:load(ssl), + {ok, _} = application:ensure_all_started(ssl), + Port = 11029, + LOpts = [{certfile, ?SERVER_CERT}, + {keyfile, ?SERVER_KEY}, + {reuseaddr, true}, + {versions, ['tlsv1.2','tlsv1.3']}, + {session_tickets, stateless}, + {early_data, enabled}, + {keep_secrets, true} %% Enable NSS key log (debug option) + ], + {ok, LSock} = ssl:listen(Port, LOpts), + %% Accept first connection + {ok, CSock0} = ssl:transport_accept(LSock), + {ok, _} = ssl:handshake(CSock0), + %% Accept second connection + {ok, CSock1} = ssl:transport_accept(LSock), + {ok, Sock} = ssl:handshake(CSock1), + Sock. + </code> + <p><em>Exporting the secrets (optional)</em></p> + <code type="none"> + {ok, [{keylog, KeylogItems}]} = ssl:connection_information(Sock, [keylog]). + file:write_file("key.log", [[KeylogItem,$\n] || KeylogItem <- KeylogItems]). + </code> + <p><em>Client (automatic ticket handling):</em></p> + <code type="erl"> + early_data_auto() -> + %% First handshake 1-RTT - get session tickets + application:load(ssl), + {ok, _} = application:ensure_all_started(ssl), + Port = 11029, + Data = <<"HEAD / HTTP/1.1\r\nHost: \r\nConnection: close\r\n">>, + COpts0 = [{cacertfile, ?CA_CERT}, + {versions, ['tlsv1.2', 'tlsv1.3']}, + {session_tickets, auto}], + {ok, Sock0} = ssl:connect("localhost", Port, COpts0), + + %% Wait for session tickets + timer:sleep(500), + %% Close socket if server cannot handle multiple connections e.g. openssl s_server + ssl:close(Sock0), + + %% Second handshake 0-RTT + COpts1 = [{cacertfile, ?CA_CERT}, + {versions, ['tlsv1.2', 'tlsv1.3']}, + {session_tickets, auto}, + {early_data, Data}], + {ok, Sock} = ssl:connect("localhost", Port, COpts1), + Sock. + </code> + <p><em>Client (manual ticket handling):</em></p> + <code type="erl"> + early_data_manual() -> + %% First handshake 1-RTT - get session tickets + application:load(ssl), + {ok, _} = application:ensure_all_started(ssl), + Port = 11029, + Data = <<"HEAD / HTTP/1.1\r\nHost: \r\nConnection: close\r\n">>, + COpts0 = [{cacertfile, ?CA_CERT}, + {versions, ['tlsv1.2', 'tlsv1.3']}, + {session_tickets, manual}], + {ok, Sock0} = ssl:connect("localhost", Port, COpts0), + + %% Wait for session tickets + Ticket = + receive + {ssl, session_ticket, Ticket0} -> + Ticket0 + end, + + %% Close socket if server cannot handle multiple connections + %% e.g. openssl s_server + ssl:close(Sock0), + + %% Second handshake 0-RTT + COpts1 = [{cacertfile, ?CA_CERT}, + {versions, ['tlsv1.2', 'tlsv1.3']}, + {session_tickets, manual}, + {use_ticket, [Ticket]}, + {early_data, Data}], + {ok, Sock} = ssl:connect("localhost", Port, COpts1), + Sock. + </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 |