syncsynchalt/illustrated-tls13

The Illustrated TLS 1.3 Connection: Every byte explained

The Illustrated TLS Connection

Published at https://tls13.xargs.org

• site/: page source for the finished product
• server/main.c: server code
• client/main.c: client code
• archive/: previous version of this site, which was based on a pre-production BoringSSL patch
• openssl/: patch of OpenSSL that removes any random aspects of the documented connection
• captures/: PCAP and keylog files

See also https://github.com/syncsynchalt/illustrated-tls for a TLS 1.2 version of this project.

Build instructions

If you'd like a working example that reproduces the exact handshake documented on the site:

git clone https://github.com/syncsynchalt/illustrated-tls13.git
cd illustrated-tls13/
cd openssl/
make
cd ../server/
make
cd ../client/
make

Then open two terminals and run ./server in the server/ subdir and ./client in the client/ subdir.

This has been shown to work on MacOS 10.14 and various Linuxes and only has a few easy-to-find dependencies: gcc or clang, golang, cmake, make, patch.

illustrated-tls13's Issues

Server Handshake Keys Calculation Extra Bytes

I am trying to implement the derived_secret part of the server handshake key calculation, but I do not understand where some of the bytes for the HkdfLabel come from.

early_secret = HKDF-Extract(salt: 00, key: 00...)
empty_hash = SHA384("")
derived_secret = HKDF-Expand-Label(key: early_secret, label: "derived", ctx: empty_hash, len: 48)

In Section 7.1 of RFC8446 it defines:

HKDF-Expand-Label(Secret, Label, Context, Length) =
    HKDF-Expand(Secret, HkdfLabel, Length)

Where HkdfLabel is specified as:

struct {
    uint16 length = Length;
    opaque label<7..255> = "tls13 " + Label;
    opaque context<0..255> = Context;
} HkdfLabel;

When using the hkdf-384 tool provided the label that gets passed in is 0x00 + 0x30 + 0x0d + "tls13 derived" + 0x30 + empty_hash. From what I see from the document it should only be 0x00 + 0x30 + "tls13 derived" + empty_hash.

Where do the extra 0x0d and 0x30 bytes come from?

Client Auth

Firstly - this site is absolutely awesome. I've read a ton of different sources on TLS handshakes and none even come close to being as effective as this. I wish I'd found it days ago. Thank you!!!

Secondly - it would be great if you could extend it to include optional Client Authentication, i.e. mTLS, for both TLSv1.3 and v1.2!

Question regarding the Request Context in the TLS 1.3 Certificate Server part

Hi!

First, thanks a LOT for this excellent peice of work !

I have a question on the Request Context byte in the Certificate Request message. You have it set to 0x00, but when I decode some TLS 1.3 HandShake, I don't see this byte at all. Here is what I typically get:

Server certificate:
-------------------
0B 
00 03 85 	        certificate payload
00 03 82 		certificates length
00 03 7F 		certificate length
...

compared to what's in your document:

Server certificate:
-------------------
0b 
00 03 2e  	        certificate payload
00                           request context <<-------------
00 03 82 		certificates length
00 03 7F 		certificate length
...

In the RFC (https://datatracker.ietf.org/doc/html/rfc8446#section-4.3.2), it says:

certificate_request_context:
An opaque string which identifies the certificate request and which will be echoed in the client's Certificate message. The certificate_request_context MUST be unique within the scope of this connection (thus preventing replay of client CertificateVerify messages). This field SHALL be zero length unless used for the post-handshake authentication exchanges described in Section 4.6.2.
`

Do you have any insight about that ?

Many thanks!

It would be even better if you could provide detailed explanations for "HelloRetryRequest" and "NewSessionTicket".

It would be even better if you could provide detailed explanations for "HelloRetryRequest" and "NewSessionTicket".

"pre-shared-key" extension in ServerHello

Hello!
First, many thanks for the great article. It's absolutely the best thing about https in the whole international segment of internet. I reproduced every steps in tls 1.3 archieve. So, I bought domain, static IP, SSL-certificate, my client side was Mozilla Firefox and after several weeks I've done it. I've written a C-program (Server) which sends html pages in response to Mozilla GET-requests.

But I have a question about session ticket. I sent "Server New Session Ticket 2" from the tls 1.3 archieve, Mozilla accepted this ticket. When I start a new connection, Mozilla sends this ticket in the end of ClientHello to my server and waiting for the response. But I don't understand what I should send back in my ServerHello.

Dumping the last 207 bytes Client Hello (pre-shared-key extension):

00160  .. .. .. .. .. .. .. ..  .. 00 29 00 cb 00 a6 00  |.......@..).....|
00170  a0 01 06 09 11 16 19 21  26 29 31 36 39 41 46 49  |.......!&)169AFI|
00180  51 03 06 09 13 16 19 23  26 29 33 36 39 43 46 49  |Q......#&)369CFI|
00190  53 f7 00 29 ec f2 c4 a4  41 fc 30 17 2e 9f 7c a8  |S..)....A.0...|.|
001a0  af 4f 69 19 7b 80 48 84  c2 df 76 0c f4 be 7b 8b  |.Oi.{.H...v...{.|
001b0  6d fb 71 73 e9 90 52 ef  4b 50 18 2f c0 74 43 ed  |m.qs..R.KP./.tC.|
001c0  10 a9 f5 07 05 67 05 3a  2a e8 f2 18 17 9c 11 f1  |.....g.:*.......|
001d0  f1 3e c9 d1 85 7f 8e 01  b4 99 ff 24 82 c6 2a f7  |.>.........$..*.|
001e0  4e 1c 86 a9 fc ca d9 84  c9 ab ec 40 de 80 03 a8  |N..........@....|
001f0  16 4f fc a6 8f 92 5f 25  f3 be 18 41 66 17 2b fb  |.O...._%...Af.+.|
00200  ef 66 4b 0a 5d 6f 94 cc  ed c7 c2 2f 64 29 a3 18  |.fK.]o...../d...|
00210  5f 09 08 4a ca 00 21 20  88 35 66 99 ec 06 18 0e  |...J..! .5f.....|
00220  b7 11 26 de b2 9c 48 81  90 78 e8 31 95 29 da 1b  |..&...H..x.1.)..|
00230  da 22 5e 1b 28 0f 0d b1                           |."^.(...|

I understand that:

• bytes 00 29 00 cb 00 a6 00 a0; 00 29 - pre-shared-key extension, 00 cb - length of extension, 00 a6 - length of session ticket and 4 strange bytes 09 08 4a ca from position 211-214, 00 a0 - length of session ticket
• 01 06 ... 18 5f - is session ticket

I don't understand:

• bytes 09 08 4a ca, extension 00 21 after these 4 bytes, okay 20 is a length
• the meaning and calculation of the last 32 bytes 88 35 ... 0d b1

I've read RFC-8446, 4.2.11, but only found that:

selected_identity: The server's chosen identity expressed as a
(0-based) index into the identities in the client's list.

It doesn't help me to understand and to write ServerHello.

Can you help me, please? Two questions

1. What should I write in pre-shared-key extension in my ServerHello to make Mozilla accept my ServerHello message? After accepting Mozilla should send me encrypted Application data with GET-request
2. The meaning and calculation of 09 08 4a ca, 00 21 and 88 35 ... 0d b1