s2n_quic_core/crypto/initial.rs
1// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4use crate::crypto;
5use hex_literal::hex;
6
7/// Types for which are able to perform initial cryptography.
8///
9/// This marker trait ensures only Initial-level keys
10/// are used with Initial packets. Any key misuses are
11/// caught by the type system.
12pub trait InitialKey: crypto::Key + Sized {
13 type HeaderKey: crypto::HeaderKey;
14
15 fn new_server(connection_id: &[u8]) -> (Self, Self::HeaderKey);
16 fn new_client(connection_id: &[u8]) -> (Self, Self::HeaderKey);
17}
18
19/// Types for which are able to perform initial header cryptography.
20///
21/// This marker trait ensures only Initial-level header keys
22/// are used with Initial packets. Any key misuses are
23/// caught by the type system.
24pub trait InitialHeaderKey: crypto::HeaderKey {}
25
26//= https://www.rfc-editor.org/rfc/rfc9001#section-5.2
27//# initial_salt = 0x38762cf7f55934b34d179ae6a4c80cadccbb7f0a
28
29pub const INITIAL_SALT: [u8; 20] = hex!("38762cf7f55934b34d179ae6a4c80cadccbb7f0a");
30
31//= https://www.rfc-editor.org/rfc/rfc9001#section-5.2
32//# client_initial_secret = HKDF-Expand-Label(initial_secret,
33//# "client in", "",
34//# Hash.length)
35
36pub const INITIAL_CLIENT_LABEL: [u8; 9] = *b"client in";
37
38//= https://www.rfc-editor.org/rfc/rfc9001#section-5.2
39//# server_initial_secret = HKDF-Expand-Label(initial_secret,
40//# "server in", "",
41//# Hash.length)
42
43pub const INITIAL_SERVER_LABEL: [u8; 9] = *b"server in";
44
45//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A
46//# These packets use an 8-byte client-chosen Destination Connection ID
47//# of 0x8394c8f03e515708.
48
49pub const EXAMPLE_DCID: [u8; 8] = hex!("8394c8f03e515708");
50
51//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.1
52//# client_initial_secret
53//# = HKDF-Expand-Label(initial_secret, "client in", "", 32)
54//# = c00cf151ca5be075ed0ebfb5c80323c4
55//# 2d6b7db67881289af4008f1f6c357aea
56
57pub const EXAMPLE_CLIENT_INITIAL_SECRET: [u8; 32] = hex!(
58 "
59 c00cf151ca5be075ed0ebfb5c80323c4
60 2d6b7db67881289af4008f1f6c357aea
61 "
62);
63
64//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.1
65//# server_initial_secret
66//# = HKDF-Expand-Label(initial_secret, "server in", "", 32)
67//# = 3c199828fd139efd216c155ad844cc81
68//# fb82fa8d7446fa7d78be803acdda951b
69
70pub const EXAMPLE_SERVER_INITIAL_SECRET: [u8; 32] = hex!(
71 "
72 3c199828fd139efd216c155ad844cc81
73 fb82fa8d7446fa7d78be803acdda951b
74 "
75);
76
77//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.2
78//# The client sends an Initial packet. The unprotected payload of this
79//# packet contains the following CRYPTO frame, plus enough PADDING
80//# frames to make an 1162-byte payload:
81//#
82//# 060040f1010000ed0303ebf8fa56f129 39b9584a3896472ec40bb863cfd3e868
83//# 04fe3a47f06a2b69484c000004130113 02010000c000000010000e00000b6578
84//# 616d706c652e636f6dff01000100000a 00080006001d00170018001000070005
85//# 04616c706e0005000501000000000033 00260024001d00209370b2c9caa47fba
86//# baf4559fedba753de171fa71f50f1ce1 5d43e994ec74d748002b000302030400
87//# 0d0010000e0403050306030203080408 050806002d00020101001c0002400100
88//# 3900320408ffffffffffffffff050480 00ffff07048000ffff08011001048000
89//# 75300901100f088394c8f03e51570806 048000ffff
90
91/// Example payload from <https://www.rfc-editor.org/rfc/rfc9001#appendix-A.2>
92pub const EXAMPLE_CLIENT_INITIAL_PAYLOAD: [u8; 245] = hex!(
93 "
94 060040f1010000ed0303ebf8fa56f129 39b9584a3896472ec40bb863cfd3e868
95 04fe3a47f06a2b69484c000004130113 02010000c000000010000e00000b6578
96 616d706c652e636f6dff01000100000a 00080006001d00170018001000070005
97 04616c706e0005000501000000000033 00260024001d00209370b2c9caa47fba
98 baf4559fedba753de171fa71f50f1ce1 5d43e994ec74d748002b000302030400
99 0d0010000e0403050306030203080408 050806002d00020101001c0002400100
100 3900320408ffffffffffffffff050480 00ffff07048000ffff08011001048000
101 75300901100f088394c8f03e51570806 048000ffff
102 "
103);
104
105//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.2
106//# The unprotected header indicates a length of 1182 bytes: the 4-byte
107//# packet number, 1162 bytes of frames, and the 16-byte authentication
108//# tag. The header includes the connection ID and a packet number of 2:
109//#
110//# c300000001088394c8f03e5157080000449e00000002
111
112pub const EXAMPLE_CLIENT_INITIAL_HEADER: [u8; 22] =
113 hex!("c300000001088394c8f03e5157080000449e00000002");
114
115//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.2
116//# Protecting the payload produces output that is sampled for header
117//# protection. Because the header uses a 4-byte packet number encoding,
118//# the first 16 bytes of the protected payload is sampled and then
119//# applied to the header as follows:
120//#
121//# sample = d1b1c98dd7689fb8ec11d242b123dc9b
122//#
123//# mask = AES-ECB(hp, sample)[0..4]
124//# = 437b9aec36
125//#
126//# header[0] ^= mask[0] & 0x0f
127//# = c0
128//# header[18..21] ^= mask[1..4]
129//# = 7b9aec34
130//# header = c000000001088394c8f03e5157080000449e7b9aec34
131
132#[test]
133fn client_initial_protection_test() {
134 let mask = hex!("437b9aec36");
135 let unprotected_header = EXAMPLE_CLIENT_INITIAL_HEADER;
136 let protected_header = hex!("c000000001088394c8f03e5157080000449e7b9aec34");
137 let packet_tag = 0b11; // results in 4 byte packet number
138
139 header_protection_test_helper(mask, &unprotected_header, &protected_header, packet_tag);
140}
141
142//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.2
143//# The resulting protected packet is:
144//#
145//# c000000001088394c8f03e5157080000 449e7b9aec34d1b1c98dd7689fb8ec11
146//# d242b123dc9bd8bab936b47d92ec356c 0bab7df5976d27cd449f63300099f399
147//# 1c260ec4c60d17b31f8429157bb35a12 82a643a8d2262cad67500cadb8e7378c
148//# 8eb7539ec4d4905fed1bee1fc8aafba1 7c750e2c7ace01e6005f80fcb7df6212
149//# 30c83711b39343fa028cea7f7fb5ff89 eac2308249a02252155e2347b63d58c5
150//# 457afd84d05dfffdb20392844ae81215 4682e9cf012f9021a6f0be17ddd0c208
151//# 4dce25ff9b06cde535d0f920a2db1bf3 62c23e596d11a4f5a6cf3948838a3aec
152//# 4e15daf8500a6ef69ec4e3feb6b1d98e 610ac8b7ec3faf6ad760b7bad1db4ba3
153//# 485e8a94dc250ae3fdb41ed15fb6a8e5 eba0fc3dd60bc8e30c5c4287e53805db
154//# 059ae0648db2f64264ed5e39be2e20d8 2df566da8dd5998ccabdae053060ae6c
155//# 7b4378e846d29f37ed7b4ea9ec5d82e7 961b7f25a9323851f681d582363aa5f8
156//# 9937f5a67258bf63ad6f1a0b1d96dbd4 faddfcefc5266ba6611722395c906556
157//# be52afe3f565636ad1b17d508b73d874 3eeb524be22b3dcbc2c7468d54119c74
158//# 68449a13d8e3b95811a198f3491de3e7 fe942b330407abf82a4ed7c1b311663a
159//# c69890f4157015853d91e923037c227a 33cdd5ec281ca3f79c44546b9d90ca00
160//# f064c99e3dd97911d39fe9c5d0b23a22 9a234cb36186c4819e8b9c5927726632
161//# 291d6a418211cc2962e20fe47feb3edf 330f2c603a9d48c0fcb5699dbfe58964
162//# 25c5bac4aee82e57a85aaf4e2513e4f0 5796b07ba2ee47d80506f8d2c25e50fd
163//# 14de71e6c418559302f939b0e1abd576 f279c4b2e0feb85c1f28ff18f58891ff
164//# ef132eef2fa09346aee33c28eb130ff2 8f5b766953334113211996d20011a198
165//# e3fc433f9f2541010ae17c1bf202580f 6047472fb36857fe843b19f5984009dd
166//# c324044e847a4f4a0ab34f719595de37 252d6235365e9b84392b061085349d73
167//# 203a4a13e96f5432ec0fd4a1ee65accd d5e3904df54c1da510b0ff20dcc0c77f
168//# cb2c0e0eb605cb0504db87632cf3d8b4 dae6e705769d1de354270123cb11450e
169//# fc60ac47683d7b8d0f811365565fd98c 4c8eb936bcab8d069fc33bd801b03ade
170//# a2e1fbc5aa463d08ca19896d2bf59a07 1b851e6c239052172f296bfb5e724047
171//# 90a2181014f3b94a4e97d117b4381303 68cc39dbb2d198065ae3986547926cd2
172//# 162f40a29f0c3c8745c0f50fba3852e5 66d44575c29d39a03f0cda721984b6f4
173//# 40591f355e12d439ff150aab7613499d bd49adabc8676eef023b15b65bfc5ca0
174//# 6948109f23f350db82123535eb8a7433 bdabcb909271a6ecbcb58b936a88cd4e
175//# 8f2e6ff5800175f113253d8fa9ca8885 c2f552e657dc603f252e1a8e308f76f0
176//# be79e2fb8f5d5fbbe2e30ecadd220723 c8c0aea8078cdfcb3868263ff8f09400
177//# 54da48781893a7e49ad5aff4af300cd8 04a6b6279ab3ff3afb64491c85194aab
178//# 760d58a606654f9f4400e8b38591356f bf6425aca26dc85244259ff2b19c41b9
179//# f96f3ca9ec1dde434da7d2d392b905dd f3d1f9af93d1af5950bd493f5aa731b4
180//# 056df31bd267b6b90a079831aaf579be 0a39013137aac6d404f518cfd4684064
181//# 7e78bfe706ca4cf5e9c5453e9f7cfd2b 8b4c8d169a44e55c88d4a9a7f9474241
182//# e221af44860018ab0856972e194cd934
183
184/// <https://www.rfc-editor.org/rfc/rfc9001#appendix-A.2>
185pub const EXAMPLE_CLIENT_INITIAL_PROTECTED_PACKET: [u8; 1200] = hex!(
186 "
187 c000000001088394c8f03e5157080000 449e7b9aec34d1b1c98dd7689fb8ec11
188 d242b123dc9bd8bab936b47d92ec356c 0bab7df5976d27cd449f63300099f399
189 1c260ec4c60d17b31f8429157bb35a12 82a643a8d2262cad67500cadb8e7378c
190 8eb7539ec4d4905fed1bee1fc8aafba1 7c750e2c7ace01e6005f80fcb7df6212
191 30c83711b39343fa028cea7f7fb5ff89 eac2308249a02252155e2347b63d58c5
192 457afd84d05dfffdb20392844ae81215 4682e9cf012f9021a6f0be17ddd0c208
193 4dce25ff9b06cde535d0f920a2db1bf3 62c23e596d11a4f5a6cf3948838a3aec
194 4e15daf8500a6ef69ec4e3feb6b1d98e 610ac8b7ec3faf6ad760b7bad1db4ba3
195 485e8a94dc250ae3fdb41ed15fb6a8e5 eba0fc3dd60bc8e30c5c4287e53805db
196 059ae0648db2f64264ed5e39be2e20d8 2df566da8dd5998ccabdae053060ae6c
197 7b4378e846d29f37ed7b4ea9ec5d82e7 961b7f25a9323851f681d582363aa5f8
198 9937f5a67258bf63ad6f1a0b1d96dbd4 faddfcefc5266ba6611722395c906556
199 be52afe3f565636ad1b17d508b73d874 3eeb524be22b3dcbc2c7468d54119c74
200 68449a13d8e3b95811a198f3491de3e7 fe942b330407abf82a4ed7c1b311663a
201 c69890f4157015853d91e923037c227a 33cdd5ec281ca3f79c44546b9d90ca00
202 f064c99e3dd97911d39fe9c5d0b23a22 9a234cb36186c4819e8b9c5927726632
203 291d6a418211cc2962e20fe47feb3edf 330f2c603a9d48c0fcb5699dbfe58964
204 25c5bac4aee82e57a85aaf4e2513e4f0 5796b07ba2ee47d80506f8d2c25e50fd
205 14de71e6c418559302f939b0e1abd576 f279c4b2e0feb85c1f28ff18f58891ff
206 ef132eef2fa09346aee33c28eb130ff2 8f5b766953334113211996d20011a198
207 e3fc433f9f2541010ae17c1bf202580f 6047472fb36857fe843b19f5984009dd
208 c324044e847a4f4a0ab34f719595de37 252d6235365e9b84392b061085349d73
209 203a4a13e96f5432ec0fd4a1ee65accd d5e3904df54c1da510b0ff20dcc0c77f
210 cb2c0e0eb605cb0504db87632cf3d8b4 dae6e705769d1de354270123cb11450e
211 fc60ac47683d7b8d0f811365565fd98c 4c8eb936bcab8d069fc33bd801b03ade
212 a2e1fbc5aa463d08ca19896d2bf59a07 1b851e6c239052172f296bfb5e724047
213 90a2181014f3b94a4e97d117b4381303 68cc39dbb2d198065ae3986547926cd2
214 162f40a29f0c3c8745c0f50fba3852e5 66d44575c29d39a03f0cda721984b6f4
215 40591f355e12d439ff150aab7613499d bd49adabc8676eef023b15b65bfc5ca0
216 6948109f23f350db82123535eb8a7433 bdabcb909271a6ecbcb58b936a88cd4e
217 8f2e6ff5800175f113253d8fa9ca8885 c2f552e657dc603f252e1a8e308f76f0
218 be79e2fb8f5d5fbbe2e30ecadd220723 c8c0aea8078cdfcb3868263ff8f09400
219 54da48781893a7e49ad5aff4af300cd8 04a6b6279ab3ff3afb64491c85194aab
220 760d58a606654f9f4400e8b38591356f bf6425aca26dc85244259ff2b19c41b9
221 f96f3ca9ec1dde434da7d2d392b905dd f3d1f9af93d1af5950bd493f5aa731b4
222 056df31bd267b6b90a079831aaf579be 0a39013137aac6d404f518cfd4684064
223 7e78bfe706ca4cf5e9c5453e9f7cfd2b 8b4c8d169a44e55c88d4a9a7f9474241
224 e221af44860018ab0856972e194cd934
225 "
226);
227
228//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.3
229//# The server sends the following payload in response, including an ACK
230//# frame, a CRYPTO frame, and no PADDING frames:
231//#
232//# 02000000000600405a020000560303ee fce7f7b37ba1d1632e96677825ddf739
233//# 88cfc79825df566dc5430b9a045a1200 130100002e00330024001d00209d3c94
234//# 0d89690b84d08a60993c144eca684d10 81287c834d5311bcf32bb9da1a002b00
235//# 020304
236//#
237
238/// Example payload from <https://www.rfc-editor.org/rfc/rfc9001#appendix-A.3>
239pub const EXAMPLE_SERVER_INITIAL_PAYLOAD: [u8; 99] = hex!(
240 "
241 02000000000600405a020000560303ee fce7f7b37ba1d1632e96677825ddf739
242 88cfc79825df566dc5430b9a045a1200 130100002e00330024001d00209d3c94
243 0d89690b84d08a60993c144eca684d10 81287c834d5311bcf32bb9da1a002b00
244 020304
245 "
246);
247
248//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.3
249//# The header from the server includes a new connection ID and a 2-byte
250//# packet number encoding for a packet number of 1:
251//#
252//# c1000000010008f067a5502a4262b50040750001
253
254pub const EXAMPLE_SERVER_INITIAL_HEADER: [u8; 20] =
255 hex!("c1000000010008f067a5502a4262b50040750001");
256
257//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.3
258//# As a result, after protection, the header protection sample is taken
259//# starting from the third protected byte:
260//#
261//# sample = 2cd0991cd25b0aac406a5816b6394100
262//# mask = 2ec0d8356a
263//# header = cf000000010008f067a5502a4262b5004075c0d9
264
265#[test]
266fn server_initial_protection_test() {
267 let mask = hex!("2ec0d8356a");
268
269 let unprotected_header = EXAMPLE_SERVER_INITIAL_HEADER;
270 let protected_header = hex!("cf000000010008f067a5502a4262b5004075c0d9");
271 let packet_tag = 0b01; // results in a 2 byte packet number
272
273 header_protection_test_helper(mask, &unprotected_header, &protected_header, packet_tag);
274}
275
276//= https://www.rfc-editor.org/rfc/rfc9001#appendix-A.3
277//# The final protected packet is then:
278//#
279//# cf000000010008f067a5502a4262b500 4075c0d95a482cd0991cd25b0aac406a
280//# 5816b6394100f37a1c69797554780bb3 8cc5a99f5ede4cf73c3ec2493a1839b3
281//# dbcba3f6ea46c5b7684df3548e7ddeb9 c3bf9c73cc3f3bded74b562bfb19fb84
282//# 022f8ef4cdd93795d77d06edbb7aaf2f 58891850abbdca3d20398c276456cbc4
283//# 2158407dd074ee
284
285/// Example protected packet from
286/// <https://www.rfc-editor.org/rfc/rfc9001#appendix-A.3>
287pub const EXAMPLE_SERVER_INITIAL_PROTECTED_PACKET: [u8; 135] = hex!(
288 "
289 cf000000010008f067a5502a4262b500 4075c0d95a482cd0991cd25b0aac406a
290 5816b6394100f37a1c69797554780bb3 8cc5a99f5ede4cf73c3ec2493a1839b3
291 dbcba3f6ea46c5b7684df3548e7ddeb9 c3bf9c73cc3f3bded74b562bfb19fb84
292 022f8ef4cdd93795d77d06edbb7aaf2f 58891850abbdca3d20398c276456cbc4
293 2158407dd074ee
294 "
295);
296
297#[cfg(test)]
298fn header_protection_test_helper(
299 mask: crate::crypto::HeaderProtectionMask,
300 unprotected_header: &[u8],
301 protected_header: &[u8],
302 packet_tag: u8,
303) {
304 use crate::{
305 crypto::{
306 apply_header_protection, remove_header_protection, EncryptedPayload, ProtectedPayload,
307 },
308 packet::number::PacketNumberSpace,
309 };
310 let space = PacketNumberSpace::Initial;
311
312 let packet_number_len = space.new_packet_number_len(packet_tag);
313 let header_len = protected_header.len() - packet_number_len.bytesize();
314
315 let mut subject = protected_header.to_vec();
316
317 remove_header_protection(space, mask, ProtectedPayload::new(header_len, &mut subject)).unwrap();
318
319 assert_eq!(
320 unprotected_header,
321 &subject[..],
322 "packet protection removal failed"
323 );
324
325 apply_header_protection(
326 mask,
327 EncryptedPayload::new(header_len, packet_number_len, &mut subject),
328 );
329
330 assert_eq!(
331 protected_header,
332 &subject[..],
333 "packet protection application failed"
334 );
335}