[tls] Support stateless session resumption
[ipxe.git] / src / include / ipxe / tls.h
1 #ifndef _IPXE_TLS_H
2 #define _IPXE_TLS_H
3
4 /**
5 * @file
6 *
7 * Transport Layer Security Protocol
8 */
9
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11
12 #include <stdint.h>
13 #include <ipxe/refcnt.h>
14 #include <ipxe/interface.h>
15 #include <ipxe/process.h>
16 #include <ipxe/crypto.h>
17 #include <ipxe/md5.h>
18 #include <ipxe/sha1.h>
19 #include <ipxe/sha256.h>
20 #include <ipxe/x509.h>
21 #include <ipxe/pending.h>
22 #include <ipxe/iobuf.h>
23 #include <ipxe/tables.h>
24
25 /** A TLS header */
26 struct tls_header {
27 /** Content type
28 *
29 * This is a TLS_TYPE_XXX constant
30 */
31 uint8_t type;
32 /** Protocol version
33 *
34 * This is a TLS_VERSION_XXX constant
35 */
36 uint16_t version;
37 /** Length of payload */
38 uint16_t length;
39 } __attribute__ (( packed ));
40
41 /** TLS version 1.0 */
42 #define TLS_VERSION_TLS_1_0 0x0301
43
44 /** TLS version 1.1 */
45 #define TLS_VERSION_TLS_1_1 0x0302
46
47 /** TLS version 1.2 */
48 #define TLS_VERSION_TLS_1_2 0x0303
49
50 /** Change cipher content type */
51 #define TLS_TYPE_CHANGE_CIPHER 20
52
53 /** Alert content type */
54 #define TLS_TYPE_ALERT 21
55
56 /** Handshake content type */
57 #define TLS_TYPE_HANDSHAKE 22
58
59 /** Application data content type */
60 #define TLS_TYPE_DATA 23
61
62 /* Handshake message types */
63 #define TLS_HELLO_REQUEST 0
64 #define TLS_CLIENT_HELLO 1
65 #define TLS_SERVER_HELLO 2
66 #define TLS_NEW_SESSION_TICKET 4
67 #define TLS_CERTIFICATE 11
68 #define TLS_SERVER_KEY_EXCHANGE 12
69 #define TLS_CERTIFICATE_REQUEST 13
70 #define TLS_SERVER_HELLO_DONE 14
71 #define TLS_CERTIFICATE_VERIFY 15
72 #define TLS_CLIENT_KEY_EXCHANGE 16
73 #define TLS_FINISHED 20
74
75 /* TLS alert levels */
76 #define TLS_ALERT_WARNING 1
77 #define TLS_ALERT_FATAL 2
78
79 /* TLS cipher specifications */
80 #define TLS_RSA_WITH_NULL_MD5 0x0001
81 #define TLS_RSA_WITH_NULL_SHA 0x0002
82 #define TLS_RSA_WITH_AES_128_CBC_SHA 0x002f
83 #define TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
84 #define TLS_RSA_WITH_AES_128_CBC_SHA256 0x003c
85 #define TLS_RSA_WITH_AES_256_CBC_SHA256 0x003d
86
87 /* TLS hash algorithm identifiers */
88 #define TLS_MD5_ALGORITHM 1
89 #define TLS_SHA1_ALGORITHM 2
90 #define TLS_SHA224_ALGORITHM 3
91 #define TLS_SHA256_ALGORITHM 4
92 #define TLS_SHA384_ALGORITHM 5
93 #define TLS_SHA512_ALGORITHM 6
94
95 /* TLS signature algorithm identifiers */
96 #define TLS_RSA_ALGORITHM 1
97
98 /* TLS server name extension */
99 #define TLS_SERVER_NAME 0
100 #define TLS_SERVER_NAME_HOST_NAME 0
101
102 /* TLS maximum fragment length extension */
103 #define TLS_MAX_FRAGMENT_LENGTH 1
104 #define TLS_MAX_FRAGMENT_LENGTH_512 1
105 #define TLS_MAX_FRAGMENT_LENGTH_1024 2
106 #define TLS_MAX_FRAGMENT_LENGTH_2048 3
107 #define TLS_MAX_FRAGMENT_LENGTH_4096 4
108
109 /* TLS signature algorithms extension */
110 #define TLS_SIGNATURE_ALGORITHMS 13
111
112 /* TLS session ticket extension */
113 #define TLS_SESSION_TICKET 35
114
115 /* TLS renegotiation information extension */
116 #define TLS_RENEGOTIATION_INFO 0xff01
117
118 /** TLS verification data */
119 struct tls_verify_data {
120 /** Client verification data */
121 uint8_t client[12];
122 /** Server verification data */
123 uint8_t server[12];
124 } __attribute__ (( packed ));
125
126 /** TLS RX state machine state */
127 enum tls_rx_state {
128 TLS_RX_HEADER = 0,
129 TLS_RX_DATA,
130 };
131
132 /** TLS TX pending flags */
133 enum tls_tx_pending {
134 TLS_TX_CLIENT_HELLO = 0x0001,
135 TLS_TX_CERTIFICATE = 0x0002,
136 TLS_TX_CLIENT_KEY_EXCHANGE = 0x0004,
137 TLS_TX_CERTIFICATE_VERIFY = 0x0008,
138 TLS_TX_CHANGE_CIPHER = 0x0010,
139 TLS_TX_FINISHED = 0x0020,
140 };
141
142 /** A TLS cipher suite */
143 struct tls_cipher_suite {
144 /** Public-key encryption algorithm */
145 struct pubkey_algorithm *pubkey;
146 /** Bulk encryption cipher algorithm */
147 struct cipher_algorithm *cipher;
148 /** MAC digest algorithm */
149 struct digest_algorithm *digest;
150 /** Key length */
151 uint16_t key_len;
152 /** Numeric code (in network-endian order) */
153 uint16_t code;
154 };
155
156 /** TLS cipher suite table */
157 #define TLS_CIPHER_SUITES \
158 __table ( struct tls_cipher_suite, "tls_cipher_suites" )
159
160 /** Declare a TLS cipher suite */
161 #define __tls_cipher_suite( pref ) \
162 __table_entry ( TLS_CIPHER_SUITES, pref )
163
164 /** A TLS cipher specification */
165 struct tls_cipherspec {
166 /** Cipher suite */
167 struct tls_cipher_suite *suite;
168 /** Dynamically-allocated storage */
169 void *dynamic;
170 /** Public key encryption context */
171 void *pubkey_ctx;
172 /** Bulk encryption cipher context */
173 void *cipher_ctx;
174 /** Next bulk encryption cipher context (TX only) */
175 void *cipher_next_ctx;
176 /** MAC secret */
177 void *mac_secret;
178 };
179
180 /** A TLS signature and hash algorithm identifier */
181 struct tls_signature_hash_id {
182 /** Hash algorithm */
183 uint8_t hash;
184 /** Signature algorithm */
185 uint8_t signature;
186 } __attribute__ (( packed ));
187
188 /** A TLS signature algorithm */
189 struct tls_signature_hash_algorithm {
190 /** Digest algorithm */
191 struct digest_algorithm *digest;
192 /** Public-key algorithm */
193 struct pubkey_algorithm *pubkey;
194 /** Numeric code */
195 struct tls_signature_hash_id code;
196 };
197
198 /** TLS signature hash algorithm table
199 *
200 * Note that the default (TLSv1.1 and earlier) algorithm using
201 * MD5+SHA1 is never explicitly specified.
202 */
203 #define TLS_SIG_HASH_ALGORITHMS \
204 __table ( struct tls_signature_hash_algorithm, \
205 "tls_sig_hash_algorithms" )
206
207 /** Declare a TLS signature hash algorithm */
208 #define __tls_sig_hash_algorithm \
209 __table_entry ( TLS_SIG_HASH_ALGORITHMS, 01 )
210
211 /** TLS pre-master secret */
212 struct tls_pre_master_secret {
213 /** TLS version */
214 uint16_t version;
215 /** Random data */
216 uint8_t random[46];
217 } __attribute__ (( packed ));
218
219 /** TLS client random data */
220 struct tls_client_random {
221 /** GMT Unix time */
222 uint32_t gmt_unix_time;
223 /** Random data */
224 uint8_t random[28];
225 } __attribute__ (( packed ));
226
227 /** An MD5+SHA1 context */
228 struct md5_sha1_context {
229 /** MD5 context */
230 uint8_t md5[MD5_CTX_SIZE];
231 /** SHA-1 context */
232 uint8_t sha1[SHA1_CTX_SIZE];
233 } __attribute__ (( packed ));
234
235 /** MD5+SHA1 context size */
236 #define MD5_SHA1_CTX_SIZE sizeof ( struct md5_sha1_context )
237
238 /** An MD5+SHA1 digest */
239 struct md5_sha1_digest {
240 /** MD5 digest */
241 uint8_t md5[MD5_DIGEST_SIZE];
242 /** SHA-1 digest */
243 uint8_t sha1[SHA1_DIGEST_SIZE];
244 } __attribute__ (( packed ));
245
246 /** MD5+SHA1 digest size */
247 #define MD5_SHA1_DIGEST_SIZE sizeof ( struct md5_sha1_digest )
248
249 /** A TLS session */
250 struct tls_session {
251 /** Reference counter */
252 struct refcnt refcnt;
253 /** List of sessions */
254 struct list_head list;
255
256 /** Server name */
257 const char *name;
258 /** Session ID */
259 uint8_t id[32];
260 /** Length of session ID */
261 size_t id_len;
262 /** Session ticket */
263 void *ticket;
264 /** Length of session ticket */
265 size_t ticket_len;
266 /** Master secret */
267 uint8_t master_secret[48];
268
269 /** List of connections */
270 struct list_head conn;
271 };
272
273 /** A TLS connection */
274 struct tls_connection {
275 /** Reference counter */
276 struct refcnt refcnt;
277
278 /** Session */
279 struct tls_session *session;
280 /** List of connections within the same session */
281 struct list_head list;
282 /** Session ID */
283 uint8_t session_id[32];
284 /** Length of session ID */
285 size_t session_id_len;
286 /** New session ticket */
287 void *new_session_ticket;
288 /** Length of new session ticket */
289 size_t new_session_ticket_len;
290
291 /** Plaintext stream */
292 struct interface plainstream;
293 /** Ciphertext stream */
294 struct interface cipherstream;
295
296 /** Protocol version */
297 uint16_t version;
298 /** Current TX cipher specification */
299 struct tls_cipherspec tx_cipherspec;
300 /** Next TX cipher specification */
301 struct tls_cipherspec tx_cipherspec_pending;
302 /** Current RX cipher specification */
303 struct tls_cipherspec rx_cipherspec;
304 /** Next RX cipher specification */
305 struct tls_cipherspec rx_cipherspec_pending;
306 /** Premaster secret */
307 struct tls_pre_master_secret pre_master_secret;
308 /** Master secret */
309 uint8_t master_secret[48];
310 /** Server random bytes */
311 uint8_t server_random[32];
312 /** Client random bytes */
313 struct tls_client_random client_random;
314 /** MD5+SHA1 context for handshake verification */
315 uint8_t handshake_md5_sha1_ctx[MD5_SHA1_CTX_SIZE];
316 /** SHA256 context for handshake verification */
317 uint8_t handshake_sha256_ctx[SHA256_CTX_SIZE];
318 /** Digest algorithm used for handshake verification */
319 struct digest_algorithm *handshake_digest;
320 /** Digest algorithm context used for handshake verification */
321 uint8_t *handshake_ctx;
322 /** Client certificate (if used) */
323 struct x509_certificate *cert;
324 /** Secure renegotiation flag */
325 int secure_renegotiation;
326 /** Verification data */
327 struct tls_verify_data verify;
328
329 /** Server certificate chain */
330 struct x509_chain *chain;
331 /** Certificate validator */
332 struct interface validator;
333
334 /** Client security negotiation pending operation */
335 struct pending_operation client_negotiation;
336 /** Server security negotiation pending operation */
337 struct pending_operation server_negotiation;
338
339 /** TX sequence number */
340 uint64_t tx_seq;
341 /** TX pending transmissions */
342 unsigned int tx_pending;
343 /** TX process */
344 struct process process;
345
346 /** RX sequence number */
347 uint64_t rx_seq;
348 /** RX state */
349 enum tls_rx_state rx_state;
350 /** Current received record header */
351 struct tls_header rx_header;
352 /** Current received record header (static I/O buffer) */
353 struct io_buffer rx_header_iobuf;
354 /** List of received data buffers */
355 struct list_head rx_data;
356 };
357
358 /** RX I/O buffer size
359 *
360 * The maximum fragment length extension is optional, and many common
361 * implementations (including OpenSSL) do not support it. We must
362 * therefore be prepared to receive records of up to 16kB in length.
363 * The chance of an allocation of this size failing is non-negligible,
364 * so we must split received data into smaller allocations.
365 */
366 #define TLS_RX_BUFSIZE 4096
367
368 /** Minimum RX I/O buffer size
369 *
370 * To simplify manipulations, we ensure that no RX I/O buffer is
371 * smaller than this size. This allows us to assume that the MAC and
372 * padding are entirely contained within the final I/O buffer.
373 */
374 #define TLS_RX_MIN_BUFSIZE 512
375
376 /** RX I/O buffer alignment */
377 #define TLS_RX_ALIGN 16
378
379 extern int add_tls ( struct interface *xfer, const char *name,
380 struct interface **next );
381
382 #endif /* _IPXE_TLS_H */