iPXE
tls.h
Go to the documentation of this file.
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  */
32  /** Protocol version
33  *
34  * This is a TLS_VERSION_XXX constant
35  */
37  /** Length of payload */
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 */
120  /** Client verification data */
122  /** Server verification data */
124 } __attribute__ (( packed ));
125 
126 /** TLS RX state machine state */
130 };
131 
132 /** TLS TX pending flags */
139  TLS_TX_FINISHED = 0x0020,
140 };
141 
142 /** A TLS cipher suite */
144  /** Public-key encryption algorithm */
146  /** Bulk encryption cipher algorithm */
148  /** MAC digest algorithm */
150  /** Key length */
152  /** Numeric code (in network-endian order) */
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 */
166  /** Cipher 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) */
176  /** MAC secret */
177  void *mac_secret;
178 };
179 
180 /** A TLS signature and hash algorithm identifier */
182  /** Hash algorithm */
184  /** Signature algorithm */
186 } __attribute__ (( packed ));
187 
188 /** A TLS signature algorithm */
190  /** Digest algorithm */
192  /** Public-key algorithm */
194  /** Numeric 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 */
213  /** TLS version */
215  /** Random data */
217 } __attribute__ (( packed ));
218 
219 /** TLS client random data */
221  /** GMT Unix time */
223  /** Random data */
225 } __attribute__ (( packed ));
226 
227 /** An MD5+SHA1 context */
229  /** MD5 context */
231  /** SHA-1 context */
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 */
240  /** MD5 digest */
242  /** SHA-1 digest */
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 */
268 
269  /** List of connections */
270  struct list_head conn;
271 };
272 
273 /** A TLS connection */
275  /** Reference counter */
276  struct refcnt refcnt;
277 
278  /** Session */
280  /** List of connections within the same session */
281  struct list_head list;
282  /** Session ID */
284  /** Length of session ID */
286  /** New session ticket */
288  /** Length of new session ticket */
290 
291  /** Plaintext stream */
293  /** Ciphertext stream */
295 
296  /** Protocol version */
298  /** Current TX cipher specification */
300  /** Next TX cipher specification */
302  /** Current RX cipher specification */
304  /** Next RX cipher specification */
306  /** Premaster secret */
308  /** Master secret */
310  /** Server random bytes */
312  /** Client random bytes */
314  /** MD5+SHA1 context for handshake verification */
316  /** SHA256 context for handshake verification */
318  /** Digest algorithm used for handshake verification */
320  /** Digest algorithm context used for handshake verification */
322  /** Client certificate (if used) */
324  /** Secure renegotiation flag */
326  /** Verification data */
328 
329  /** Server certificate chain */
330  struct x509_chain *chain;
331  /** Certificate validator */
333 
334  /** Client security negotiation pending operation */
336  /** Server security negotiation pending operation */
338  /** Certificate validation pending operation */
340 
341  /** TX sequence number */
343  /** TX pending transmissions */
344  unsigned int tx_pending;
345  /** TX process */
346  struct process process;
347 
348  /** RX sequence number */
350  /** RX state */
352  /** Current received record header */
354  /** Current received record header (static I/O buffer) */
356  /** List of received data buffers */
358 };
359 
360 /** RX I/O buffer size
361  *
362  * The maximum fragment length extension is optional, and many common
363  * implementations (including OpenSSL) do not support it. We must
364  * therefore be prepared to receive records of up to 16kB in length.
365  * The chance of an allocation of this size failing is non-negligible,
366  * so we must split received data into smaller allocations.
367  */
368 #define TLS_RX_BUFSIZE 4096
369 
370 /** Minimum RX I/O buffer size
371  *
372  * To simplify manipulations, we ensure that no RX I/O buffer is
373  * smaller than this size. This allows us to assume that the MAC and
374  * padding are entirely contained within the final I/O buffer.
375  */
376 #define TLS_RX_MIN_BUFSIZE 512
377 
378 /** RX I/O buffer alignment */
379 #define TLS_RX_ALIGN 16
380 
381 extern int add_tls ( struct interface *xfer, const char *name,
382  struct interface **next );
383 
384 #endif /* _IPXE_TLS_H */
struct tls_verify_data verify
Verification data.
Definition: tls.h:327
A process.
Definition: process.h:17
#define __attribute__(x)
Definition: compiler.h:10
struct digest_algorithm * digest
Digest algorithm.
Definition: tls.h:191
const char * name
Definition: ath9k_hw.c:1984
unsigned short uint16_t
Definition: stdint.h:11
struct x509_chain * chain
Server certificate chain.
Definition: tls.h:330
An MD5+SHA1 context.
Definition: tls.h:228
uint8_t sha1[SHA1_DIGEST_SIZE]
SHA-1 digest.
Definition: tls.h:243
struct pending_operation client_negotiation
Client security negotiation pending operation.
Definition: tls.h:335
struct tls_session * session
Session.
Definition: tls.h:279
uint8_t master_secret[48]
Master secret.
Definition: tls.h:267
uint8_t md5[MD5_DIGEST_SIZE]
MD5 digest.
Definition: tls.h:241
struct io_buffer rx_header_iobuf
Current received record header (static I/O buffer)
Definition: tls.h:355
uint32_t next
Next descriptor address.
Definition: myson.h:18
#define SHA256_CTX_SIZE
SHA-256 context size.
Definition: sha256.h:71
uint64_t rx_seq
RX sequence number.
Definition: tls.h:349
uint8_t type
Content type.
Definition: tls.h:31
I/O buffers.
Definition: b44.h:369
uint8_t handshake_md5_sha1_ctx[MD5_SHA1_CTX_SIZE]
MD5+SHA1 context for handshake verification.
Definition: tls.h:315
size_t new_session_ticket_len
Length of new session ticket.
Definition: tls.h:289
uint8_t server_random[32]
Server random bytes.
Definition: tls.h:311
uint8_t session_id[32]
Session ID.
Definition: tls.h:283
uint16_t length
Length of payload.
Definition: tls.h:38
unsigned long long uint64_t
Definition: stdint.h:13
Cryptographic API.
A TLS cipher specification.
Definition: tls.h:165
struct pubkey_algorithm * pubkey
Public-key encryption algorithm.
Definition: tls.h:145
A doubly-linked list entry (or list head)
Definition: list.h:18
A reference counter.
Definition: refcnt.h:26
A certificate validator.
Definition: validator.c:65
enum tls_rx_state rx_state
RX state.
Definition: tls.h:351
An X.509 certificate chain.
Definition: x509.h:177
uint8_t * handshake_ctx
Digest algorithm context used for handshake verification.
Definition: tls.h:321
struct tls_cipherspec tx_cipherspec
Current TX cipher specification.
Definition: tls.h:299
size_t id_len
Length of session ID.
Definition: tls.h:261
An object interface.
Definition: interface.h:109
void * new_session_ticket
New session ticket.
Definition: tls.h:287
void * cipher_ctx
Bulk encryption cipher context.
Definition: tls.h:173
tls_tx_pending
TLS TX pending flags.
Definition: tls.h:133
Object interfaces.
struct tls_cipher_suite * suite
Cipher suite.
Definition: tls.h:167
TLS verification data.
Definition: tls.h:119
struct digest_algorithm * digest
MAC digest algorithm.
Definition: tls.h:149
struct pending_operation validation
Certificate validation pending operation.
Definition: tls.h:339
struct list_head list
List of connections within the same session.
Definition: tls.h:281
uint32_t gmt_unix_time
GMT Unix time.
Definition: tls.h:222
A TLS cipher suite.
Definition: tls.h:143
A TLS signature algorithm.
Definition: tls.h:189
size_t ticket_len
Length of session ticket.
Definition: tls.h:265
uint8_t master_secret[48]
Master secret.
Definition: tls.h:309
struct list_head list
List of sessions.
Definition: tls.h:254
struct tls_client_random client_random
Client random bytes.
Definition: tls.h:313
An X.509 certificate.
Definition: x509.h:185
uint16_t key_len
Key length.
Definition: tls.h:151
struct interface cipherstream
Ciphertext stream.
Definition: tls.h:294
uint8_t hash
Hash algorithm.
Definition: tls.h:183
void * ticket
Session ticket.
Definition: tls.h:263
int add_tls(struct interface *xfer, const char *name, struct interface **next)
Definition: tls.c:3073
#define MD5_CTX_SIZE
MD5 context size.
Definition: md5.h:66
void * pubkey_ctx
Public key encryption context.
Definition: tls.h:171
#define MD5_SHA1_CTX_SIZE
MD5+SHA1 context size.
Definition: tls.h:236
Processes.
unsigned char uint8_t
Definition: stdint.h:10
uint8_t signature
Signature algorithm.
Definition: tls.h:185
X.509 certificates.
unsigned int uint32_t
Definition: stdint.h:12
struct tls_cipherspec rx_cipherspec
Current RX cipher specification.
Definition: tls.h:303
struct tls_signature_hash_id code
Numeric code.
Definition: tls.h:195
struct tls_cipherspec tx_cipherspec_pending
Next TX cipher specification.
Definition: tls.h:301
struct tls_pre_master_secret pre_master_secret
Premaster secret.
Definition: tls.h:307
uint8_t client[12]
Client verification data.
Definition: tls.h:121
struct pending_operation server_negotiation
Server security negotiation pending operation.
Definition: tls.h:337
An MD5+SHA1 digest.
Definition: tls.h:239
A TLS header.
Definition: tls.h:26
uint8_t random[46]
Random data.
Definition: tls.h:216
Pending operations.
struct list_head rx_data
List of received data buffers.
Definition: tls.h:357
unsigned int tx_pending
TX pending transmissions.
Definition: tls.h:344
struct digest_algorithm * handshake_digest
Digest algorithm used for handshake verification.
Definition: tls.h:319
uint8_t random[28]
Random data.
Definition: tls.h:224
A TLS session.
Definition: tls.h:250
#define SHA1_DIGEST_SIZE
Definition: Tpm20.h:32
uint8_t handshake_sha256_ctx[SHA256_CTX_SIZE]
SHA256 context for handshake verification.
Definition: tls.h:317
SHA-1 algorithm.
uint8_t sha1[SHA1_CTX_SIZE]
SHA-1 context.
Definition: tls.h:232
struct tls_cipherspec rx_cipherspec_pending
Next RX cipher specification.
Definition: tls.h:305
tls_rx_state
TLS RX state machine state.
Definition: tls.h:127
#define SHA1_CTX_SIZE
SHA-1 context size.
Definition: sha1.h:66
uint16_t version
Protocol version.
Definition: tls.h:36
A message digest algorithm.
Definition: crypto.h:16
Reference counting.
uint16_t version
Protocol version.
Definition: tls.h:297
A cipher algorithm.
Definition: crypto.h:48
uint8_t server[12]
Server verification data.
Definition: tls.h:123
Linker tables.
A TLS connection.
Definition: tls.h:274
#define MD5_DIGEST_SIZE
MD5 digest size.
Definition: md5.h:69
A pending operation.
Definition: pending.h:13
uint8_t md5[MD5_CTX_SIZE]
MD5 context.
Definition: tls.h:230
struct cipher_algorithm * cipher
Bulk encryption cipher algorithm.
Definition: tls.h:147
struct list_head conn
List of connections.
Definition: tls.h:270
int secure_renegotiation
Secure renegotiation flag.
Definition: tls.h:325
struct pubkey_algorithm * pubkey
Public-key algorithm.
Definition: tls.h:193
void * dynamic
Dynamically-allocated storage.
Definition: tls.h:169
const char * name
Server name.
Definition: tls.h:257
A TLS signature and hash algorithm identifier.
Definition: tls.h:181
TLS pre-master secret.
Definition: tls.h:212
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
size_t session_id_len
Length of session ID.
Definition: tls.h:285
struct interface plainstream
Plaintext stream.
Definition: tls.h:292
MD5 algorithm.
SHA-256 algorithm.
TLS client random data.
Definition: tls.h:220
A public key algorithm.
Definition: crypto.h:94
struct x509_certificate * cert
Client certificate (if used)
Definition: tls.h:323
uint16_t code
Numeric code (in network-endian order)
Definition: tls.h:153
void * mac_secret
MAC secret.
Definition: tls.h:177
uint64_t tx_seq
TX sequence number.
Definition: tls.h:342
uint16_t version
TLS version.
Definition: tls.h:214
A persistent I/O buffer.
Definition: iobuf.h:32
void * cipher_next_ctx
Next bulk encryption cipher context (TX only)
Definition: tls.h:175