File 4901-ssl-Doc-enhancement.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 4901-ssl-Doc-enhancement.patch of Package erlang

From d7467f9ecadd8fb585e2de0af22729484baa3a00 Mon Sep 17 00:00:00 2001
From: Ingela Anderton Andin <ingela@erlang.org>
Date: Thu, 23 Feb 2023 16:28:23 +0100
Subject: [PATCH] ssl: Doc enhancement

---
 lib/ssl/doc/src/using_ssl.xml | 66 ++++++++++++++++++++++-------------
 1 file changed, 42 insertions(+), 24 deletions(-)

diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml
index 5f730dada6..eb222615f9 100644
--- a/lib/ssl/doc/src/using_ssl.xml
+++ b/lib/ssl/doc/src/using_ssl.xml
@@ -342,6 +342,32 @@ ssl:connect("localhost", 9999,
 
 </section>
 
+ <section>
+ <title>NSS keylog </title>
+ The NSS keylog debug feature can be used by authorized users
+ to for instance enable wireshark to decrypt TLS packets.
+
+ Server (with NSS key logging)
+ <code type="none">
+ server() ->
+ application:load(ssl),
+ {ok, _} = application:ensure_all_started(ssl),
+ Port = 11029,
+ LOpts = [{certs_keys, [#{certfile => "cert.pem", keyfile => "key.pem"}]},
+ {reuseaddr, true},
+ {versions, ['tlsv1.2','tlsv1.3']},
+ {keep_secrets, true} %% Enable NSS key log (debug option)
+ ],
+ {ok, LSock} = ssl:listen(Port, LOpts),
+ {ok, ASock} = ssl:transport_accept(LSock),
+ {ok, CSock} = ssl:handshake(ASock).
+ </code>
+ Exporting the secrets
+ <code type="none">
+ {ok, [{keylog, KeylogItems}]} = ssl:connection_information(CSock, [keylog]).
+ file:write_file("key.log", [[KeylogItem,$\n] || KeylogItem &lt;- KeylogItems]).
+ </code>
+ </section>
 
 <section>
 <title>Session Reuse pre TLS 1.3</title>
@@ -553,7 +580,7 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 {versions, ['tlsv1.2','tlsv1.3']},
 {session_tickets, stateless}].
 {ok, LSock} = ssl:listen(8001, LOpts).
- {ok, CSock} = ssl:transport_accept(LSock).
+ {ok, ASock} = ssl:transport_accept(LSock).
 </code>
 
 Step 2 (client): Start the client and connect to server:
@@ -568,7 +595,7 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 
 Step 3 (server): Start the TLS handshake:
 <code type="erl">
- ssl:handshake(CSock).
+ {ok, CSocket} = ssl:handshake(ASock).
 </code>
 
 A connection is established using a full handshake.
@@ -590,7 +617,7 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 
 Step 4 (server): Accept a new connection on the server:
 <code type="erl">
- {ok, CSock2} = ssl:transport_accept(LSock).
+ {ok, ASock2} = ssl:transport_accept(LSock).
 </code>
 
 Step 5 (client): Make a new connection:
@@ -600,7 +627,7 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 
 Step 6 (server): Start the handshake:
 <code type="erl">
- ssl:handshake(CSock2).
+ {ok, CSock2} =ssl:handshake(ASock2).
 </code>
 
 The second connection is a session resumption using keying material
@@ -619,7 +646,7 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 
 Step 7 (server): Accept a new connection on the server:
 <code type="erl">
- {ok, CSock3} = ssl:transport_accept(LSock).
+ {ok, ASock3} = ssl:transport_accept(LSock).
 </code>
 
 Step 8 (client): Make a new connection to server:
@@ -634,7 +661,7 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 
 Step 9 (server): Start the handshake:
 <code type="erl">
- ssl:handshake(CSock3).
+ {ok, CSock3} = ssl:handshake(ASock3).
 </code>
 
 After the handshake is performed, the user process receives messages with the tickets
@@ -647,7 +674,7 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 
 Step 11 (server): Accept a new connection on the server:
 <code type="erl">
- {ok, CSock4} = ssl:transport_accept(LSock).
+ {ok, ASock4} = ssl:transport_accept(LSock).
 </code>
 
 Step 12 (client): Initiate a new connection to the server with the session ticket
@@ -664,12 +691,12 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 
 Step 13 (server): Start the handshake:
 <code type="erl">
- ssl:handshake(CSock3).
+ {ok, CSock4} = ssl:handshake(ASock4).
 </code>
 </section>
 
 <section>
- <title>Early Data in TLS 1.3</title>
+ <title>Early Data in TLS 1.3 </title>
 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
@@ -689,12 +716,8 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 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.
 An example of sending early data with automatic and manual session ticket handling:
- <warning>
- The Early Data feature is experimental in this version of OTP.
- 
- </warning>
 
- Server (with NSS key logging)
+ Server
 <code type="none">
 early_data_server() ->
 application:load(ssl),
@@ -705,22 +728,17 @@ ssl:connect("localhost", 9999, [{verify, verify_peer},
 {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),
+ {ok, ASock0} = ssl:transport_accept(LSock),
+ {ok, CSock0} = ssl:handshake(ASock0),
 %% Accept second connection
- {ok, CSock1} = ssl:transport_accept(LSock),
- {ok, Sock} = ssl:handshake(CSock1),
+ {ok, ASock1} = ssl:transport_accept(LSock),
+ {ok, CSock1} = ssl:handshake(ASock1),
 Sock.
 </code>
- Exporting the secrets (optional)
- <code type="none">
- {ok, [{keylog, KeylogItems}]} = ssl:connection_information(Sock, [keylog]).
- file:write_file("key.log", [[KeylogItem,$\n] || KeylogItem &lt;- KeylogItems]).
- </code>
+
 Client (automatic ticket handling):
 <code type="erl">
 early_data_auto() -&gt;
-- 
2.35.3

Places

File 4901-ssl-Doc-enhancement.patch of Package erlang

Places