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/x509.h>
20 #include <ipxe/privkey.h>
21 #include <ipxe/pending.h>
22 #include <ipxe/iobuf.h>
23 #include <ipxe/tables.h>
24 
25 struct tls_connection;
26 
27 /** A TLS header */
28 struct tls_header {
29  /** Content type
30  *
31  * This is a TLS_TYPE_XXX constant
32  */
34  /** Protocol version
35  *
36  * This is a TLS_VERSION_XXX constant
37  */
39  /** Length of payload */
41 } __attribute__ (( packed ));
42 
43 /** TLS version 1.1 */
44 #define TLS_VERSION_TLS_1_1 0x0302
45 
46 /** TLS version 1.2 */
47 #define TLS_VERSION_TLS_1_2 0x0303
48 
49 /** Maximum supported TLS version */
50 #define TLS_VERSION_MAX TLS_VERSION_TLS_1_2
51 
52 /** Change cipher content type */
53 #define TLS_TYPE_CHANGE_CIPHER 20
54 
55 /** Alert content type */
56 #define TLS_TYPE_ALERT 21
57 
58 /** Handshake content type */
59 #define TLS_TYPE_HANDSHAKE 22
60 
61 /** Application data content type */
62 #define TLS_TYPE_DATA 23
63 
64 /* Handshake message types */
65 #define TLS_HELLO_REQUEST 0
66 #define TLS_CLIENT_HELLO 1
67 #define TLS_SERVER_HELLO 2
68 #define TLS_NEW_SESSION_TICKET 4
69 #define TLS_CERTIFICATE 11
70 #define TLS_SERVER_KEY_EXCHANGE 12
71 #define TLS_CERTIFICATE_REQUEST 13
72 #define TLS_SERVER_HELLO_DONE 14
73 #define TLS_CERTIFICATE_VERIFY 15
74 #define TLS_CLIENT_KEY_EXCHANGE 16
75 #define TLS_FINISHED 20
76 
77 /* TLS alert levels */
78 #define TLS_ALERT_WARNING 1
79 #define TLS_ALERT_FATAL 2
80 
81 /* TLS cipher specifications */
82 #define TLS_RSA_WITH_NULL_MD5 0x0001
83 #define TLS_RSA_WITH_NULL_SHA 0x0002
84 #define TLS_RSA_WITH_AES_128_CBC_SHA 0x002f
85 #define TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x0033
86 #define TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
87 #define TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0039
88 #define TLS_RSA_WITH_AES_128_CBC_SHA256 0x003c
89 #define TLS_RSA_WITH_AES_256_CBC_SHA256 0x003d
90 #define TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x0067
91 #define TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x006b
92 #define TLS_RSA_WITH_AES_128_GCM_SHA256 0x009c
93 #define TLS_RSA_WITH_AES_256_GCM_SHA384 0x009d
94 #define TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x009e
95 #define TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x009f
96 
97 /* TLS hash algorithm identifiers */
98 #define TLS_MD5_ALGORITHM 1
99 #define TLS_SHA1_ALGORITHM 2
100 #define TLS_SHA224_ALGORITHM 3
101 #define TLS_SHA256_ALGORITHM 4
102 #define TLS_SHA384_ALGORITHM 5
103 #define TLS_SHA512_ALGORITHM 6
104 
105 /* TLS signature algorithm identifiers */
106 #define TLS_RSA_ALGORITHM 1
107 
108 /* TLS server name extension */
109 #define TLS_SERVER_NAME 0
110 #define TLS_SERVER_NAME_HOST_NAME 0
111 
112 /* TLS maximum fragment length extension */
113 #define TLS_MAX_FRAGMENT_LENGTH 1
114 #define TLS_MAX_FRAGMENT_LENGTH_512 1
115 #define TLS_MAX_FRAGMENT_LENGTH_1024 2
116 #define TLS_MAX_FRAGMENT_LENGTH_2048 3
117 #define TLS_MAX_FRAGMENT_LENGTH_4096 4
118 
119 /* TLS signature algorithms extension */
120 #define TLS_SIGNATURE_ALGORITHMS 13
121 
122 /* TLS session ticket extension */
123 #define TLS_SESSION_TICKET 35
124 
125 /* TLS renegotiation information extension */
126 #define TLS_RENEGOTIATION_INFO 0xff01
127 
128 /** TLS authentication header */
130  /** Sequence number */
132  /** TLS header */
134 } __attribute__ (( packed ));
135 
136 /** TLS verification data */
138  /** Client verification data */
140  /** Server verification data */
142 } __attribute__ (( packed ));
143 
144 /** TLS RX state machine state */
148 };
149 
150 /** TLS TX pending flags */
157  TLS_TX_FINISHED = 0x0020,
158 };
159 
160 /** A TLS key exchange algorithm */
162  /** Algorithm name */
163  const char *name;
164  /**
165  * Transmit Client Key Exchange record
166  *
167  * @v tls TLS connection
168  * @ret rc Return status code
169  */
170  int ( * exchange ) ( struct tls_connection *tls );
171 };
172 
173 /** A TLS cipher suite */
175  /** Key exchange algorithm */
177  /** Public-key encryption algorithm */
179  /** Bulk encryption cipher algorithm */
181  /** MAC digest algorithm */
183  /** Handshake digest algorithm (for TLSv1.2 and above) */
185  /** Numeric code (in network-endian order) */
187  /** Key length */
189  /** Fixed initialisation vector length */
191  /** Record initialisation vector length */
193  /** MAC length */
195 };
196 
197 /** TLS cipher suite table */
198 #define TLS_CIPHER_SUITES \
199  __table ( struct tls_cipher_suite, "tls_cipher_suites" )
200 
201 /** Declare a TLS cipher suite */
202 #define __tls_cipher_suite( pref ) \
203  __table_entry ( TLS_CIPHER_SUITES, pref )
204 
205 /** A TLS cipher specification */
207  /** Cipher suite */
209  /** Dynamically-allocated storage */
210  void *dynamic;
211  /** Public key encryption context */
212  void *pubkey_ctx;
213  /** Bulk encryption cipher context */
214  void *cipher_ctx;
215  /** MAC secret */
216  void *mac_secret;
217  /** Fixed initialisation vector */
218  void *fixed_iv;
219 };
220 
221 /** A TLS signature and hash algorithm identifier */
223  /** Hash algorithm */
225  /** Signature algorithm */
227 } __attribute__ (( packed ));
228 
229 /** A TLS signature algorithm */
231  /** Digest algorithm */
233  /** Public-key algorithm */
235  /** Numeric code */
237 };
238 
239 /** TLS signature hash algorithm table
240  *
241  * Note that the default (TLSv1.1 and earlier) algorithm using
242  * MD5+SHA1 is never explicitly specified.
243  */
244 #define TLS_SIG_HASH_ALGORITHMS \
245  __table ( struct tls_signature_hash_algorithm, \
246  "tls_sig_hash_algorithms" )
247 
248 /** Declare a TLS signature hash algorithm */
249 #define __tls_sig_hash_algorithm \
250  __table_entry ( TLS_SIG_HASH_ALGORITHMS, 01 )
251 
252 /** TLS client random data */
254  /** GMT Unix time */
256  /** Random data */
258 } __attribute__ (( packed ));
259 
260 /** An MD5+SHA1 context */
262  /** MD5 context */
264  /** SHA-1 context */
266 } __attribute__ (( packed ));
267 
268 /** MD5+SHA1 context size */
269 #define MD5_SHA1_CTX_SIZE sizeof ( struct md5_sha1_context )
270 
271 /** An MD5+SHA1 digest */
273  /** MD5 digest */
275  /** SHA-1 digest */
277 } __attribute__ (( packed ));
278 
279 /** MD5+SHA1 digest size */
280 #define MD5_SHA1_DIGEST_SIZE sizeof ( struct md5_sha1_digest )
281 
282 /** A TLS session */
283 struct tls_session {
284  /** Reference counter */
285  struct refcnt refcnt;
286  /** List of sessions */
287  struct list_head list;
288 
289  /** Server name */
290  const char *name;
291  /** Root of trust */
292  struct x509_root *root;
293  /** Private key */
294  struct private_key *key;
295 
296  /** Session ID */
297  uint8_t id[32];
298  /** Length of session ID */
299  size_t id_len;
300  /** Session ticket */
301  void *ticket;
302  /** Length of session ticket */
303  size_t ticket_len;
304  /** Master secret */
306 
307  /** List of connections */
308  struct list_head conn;
309 };
310 
311 /** A TLS connection */
313  /** Reference counter */
314  struct refcnt refcnt;
315 
316  /** Session */
318  /** List of connections within the same session */
319  struct list_head list;
320  /** Session ID */
322  /** Length of session ID */
324  /** New session ticket */
326  /** Length of new session ticket */
328 
329  /** Plaintext stream */
331  /** Ciphertext stream */
333 
334  /** Protocol version */
336  /** Current TX cipher specification */
338  /** Next TX cipher specification */
340  /** Current RX cipher specification */
342  /** Next RX cipher specification */
344  /** Master secret */
346  /** Server random bytes */
348  /** Client random bytes */
350  /** Server Key Exchange record (if any) */
351  void *server_key;
352  /** Server Key Exchange record length */
354  /** Digest algorithm used for handshake verification */
356  /** Digest algorithm context used for handshake verification */
358  /** Private key */
359  struct private_key *key;
360  /** Client certificate chain (if used) */
361  struct x509_chain *certs;
362  /** Secure renegotiation flag */
364  /** Verification data */
366 
367  /** Root of trust */
368  struct x509_root *root;
369  /** Server certificate chain */
370  struct x509_chain *chain;
371  /** Certificate validator */
373 
374  /** Client security negotiation pending operation */
376  /** Server security negotiation pending operation */
378  /** Certificate validation pending operation */
380 
381  /** TX sequence number */
383  /** TX pending transmissions */
384  unsigned int tx_pending;
385  /** TX process */
386  struct process process;
387 
388  /** RX sequence number */
390  /** RX state */
392  /** Current received record header */
394  /** Current received record header (static I/O buffer) */
396  /** List of received data buffers */
398 };
399 
400 /** RX I/O buffer size
401  *
402  * The maximum fragment length extension is optional, and many common
403  * implementations (including OpenSSL) do not support it. We must
404  * therefore be prepared to receive records of up to 16kB in length.
405  * The chance of an allocation of this size failing is non-negligible,
406  * so we must split received data into smaller allocations.
407  */
408 #define TLS_RX_BUFSIZE 4096
409 
410 /** Minimum RX I/O buffer size
411  *
412  * To simplify manipulations, we ensure that no RX I/O buffer is
413  * smaller than this size. This allows us to assume that the MAC and
414  * padding are entirely contained within the final I/O buffer.
415  */
416 #define TLS_RX_MIN_BUFSIZE 512
417 
418 /** RX I/O buffer alignment */
419 #define TLS_RX_ALIGN 16
420 
423 
424 extern int add_tls ( struct interface *xfer, const char *name,
425  struct x509_root *root, struct private_key *key );
426 
427 #endif /* _IPXE_TLS_H */
struct tls_verify_data verify
Verification data.
Definition: tls.h:365
A process.
Definition: process.h:17
#define __attribute__(x)
Definition: compiler.h:10
struct digest_algorithm * digest
Digest algorithm.
Definition: tls.h:232
uint64_t seq
Sequence number.
Definition: tls.h:131
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:370
An MD5+SHA1 context.
Definition: tls.h:261
uint8_t sha1[SHA1_DIGEST_SIZE]
SHA-1 digest.
Definition: tls.h:276
struct pending_operation client_negotiation
Client security negotiation pending operation.
Definition: tls.h:375
struct tls_session * session
Session.
Definition: tls.h:317
uint8_t master_secret[48]
Master secret.
Definition: tls.h:305
struct tls_key_exchange_algorithm * exchange
Key exchange algorithm.
Definition: tls.h:176
uint8_t md5[MD5_DIGEST_SIZE]
MD5 digest.
Definition: tls.h:274
struct io_buffer rx_header_iobuf
Current received record header (static I/O buffer)
Definition: tls.h:395
uint8_t record_iv_len
Record initialisation vector length.
Definition: tls.h:192
struct stp_switch root
Root switch.
Definition: stp.h:26
uint64_t rx_seq
RX sequence number.
Definition: tls.h:389
uint8_t type
Content type.
Definition: tls.h:33
I/O buffers.
Definition: b44.h:369
struct tls_key_exchange_algorithm tls_dhe_exchange_algorithm
Ephemeral Diffie-Hellman key exchange algorithm.
Definition: tls.c:1569
size_t new_session_ticket_len
Length of new session ticket.
Definition: tls.h:327
uint8_t server_random[32]
Server random bytes.
Definition: tls.h:347
uint8_t session_id[32]
Session ID.
Definition: tls.h:321
struct tls_key_exchange_algorithm tls_pubkey_exchange_algorithm
Public key exchange algorithm.
Definition: tls.c:1370
uint16_t length
Length of payload.
Definition: tls.h:40
struct x509_root * root
Root of trust.
Definition: tls.h:368
unsigned long long uint64_t
Definition: stdint.h:13
Cryptographic API.
TLS authentication header.
Definition: tls.h:129
A TLS cipher specification.
Definition: tls.h:206
const char * name
Algorithm name.
Definition: tls.h:163
struct pubkey_algorithm * pubkey
Public-key encryption algorithm.
Definition: tls.h:178
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
Private key.
enum tls_rx_state rx_state
RX state.
Definition: tls.h:391
An X.509 certificate chain.
Definition: x509.h:177
uint8_t * handshake_ctx
Digest algorithm context used for handshake verification.
Definition: tls.h:357
struct tls_cipherspec tx_cipherspec
Current TX cipher specification.
Definition: tls.h:337
int(* exchange)(struct tls_connection *tls)
Transmit Client Key Exchange record.
Definition: tls.h:170
size_t id_len
Length of session ID.
Definition: tls.h:299
An object interface.
Definition: interface.h:124
void * new_session_ticket
New session ticket.
Definition: tls.h:325
void * cipher_ctx
Bulk encryption cipher context.
Definition: tls.h:214
tls_tx_pending
TLS TX pending flags.
Definition: tls.h:151
Object interfaces.
struct tls_cipher_suite * suite
Cipher suite.
Definition: tls.h:208
struct x509_chain * certs
Client certificate chain (if used)
Definition: tls.h:361
TLS verification data.
Definition: tls.h:137
struct digest_algorithm * digest
MAC digest algorithm.
Definition: tls.h:182
struct pending_operation validation
Certificate validation pending operation.
Definition: tls.h:379
struct list_head list
List of connections within the same session.
Definition: tls.h:319
uint32_t gmt_unix_time
GMT Unix time.
Definition: tls.h:255
uint8_t fixed_iv_len
Fixed initialisation vector length.
Definition: tls.h:190
A TLS cipher suite.
Definition: tls.h:174
A TLS signature algorithm.
Definition: tls.h:230
size_t ticket_len
Length of session ticket.
Definition: tls.h:303
uint8_t master_secret[48]
Master secret.
Definition: tls.h:345
struct list_head list
List of sessions.
Definition: tls.h:287
struct tls_header header
TLS header.
Definition: tls.h:133
struct tls_client_random client_random
Client random bytes.
Definition: tls.h:349
struct interface cipherstream
Ciphertext stream.
Definition: tls.h:332
void * server_key
Server Key Exchange record (if any)
Definition: tls.h:351
uint8_t hash
Hash algorithm.
Definition: tls.h:224
void * ticket
Session ticket.
Definition: tls.h:301
#define MD5_CTX_SIZE
MD5 context size.
Definition: md5.h:66
uint8_t mac_len
MAC length.
Definition: tls.h:194
void * pubkey_ctx
Public key encryption context.
Definition: tls.h:212
Processes.
unsigned char uint8_t
Definition: stdint.h:10
uint8_t signature
Signature algorithm.
Definition: tls.h:226
struct private_key * key
Private key.
Definition: tls.h:359
X.509 certificates.
unsigned int uint32_t
Definition: stdint.h:12
struct tls_cipherspec rx_cipherspec
Current RX cipher specification.
Definition: tls.h:341
int add_tls(struct interface *xfer, const char *name, struct x509_root *root, struct private_key *key)
Add TLS on an interface.
Definition: tls.c:3531
struct tls_signature_hash_id code
Numeric code.
Definition: tls.h:236
struct tls_cipherspec tx_cipherspec_pending
Next TX cipher specification.
Definition: tls.h:339
uint8_t client[12]
Client verification data.
Definition: tls.h:139
struct pending_operation server_negotiation
Server security negotiation pending operation.
Definition: tls.h:377
An MD5+SHA1 digest.
Definition: tls.h:272
An X.509 root certificate list.
Definition: x509.h:344
A TLS header.
Definition: tls.h:28
Pending operations.
struct list_head rx_data
List of received data buffers.
Definition: tls.h:397
unsigned int tx_pending
TX pending transmissions.
Definition: tls.h:384
struct digest_algorithm * handshake_digest
Digest algorithm used for handshake verification.
Definition: tls.h:355
uint8_t random[28]
Random data.
Definition: tls.h:257
A TLS session.
Definition: tls.h:283
#define SHA1_DIGEST_SIZE
Definition: Tpm20.h:32
SHA-1 algorithm.
uint8_t sha1[SHA1_CTX_SIZE]
SHA-1 context.
Definition: tls.h:265
struct digest_algorithm * handshake
Handshake digest algorithm (for TLSv1.2 and above)
Definition: tls.h:184
struct tls_cipherspec rx_cipherspec_pending
Next RX cipher specification.
Definition: tls.h:343
tls_rx_state
TLS RX state machine state.
Definition: tls.h:145
#define SHA1_CTX_SIZE
SHA-1 context size.
Definition: sha1.h:66
uint16_t version
Protocol version.
Definition: tls.h:38
A message digest algorithm.
Definition: crypto.h:17
Reference counting.
uint16_t version
Protocol version.
Definition: tls.h:335
A cipher algorithm.
Definition: crypto.h:49
A private key.
Definition: privkey.h:16
uint8_t server[12]
Server verification data.
Definition: tls.h:141
Linker tables.
A TLS key exchange algorithm.
Definition: tls.h:161
struct x509_root * root
Root of trust.
Definition: tls.h:292
A TLS connection.
Definition: tls.h:312
struct private_key * key
Private key.
Definition: tls.h:294
#define MD5_DIGEST_SIZE
MD5 digest size.
Definition: md5.h:72
A pending operation.
Definition: pending.h:13
uint8_t md5[MD5_CTX_SIZE]
MD5 context.
Definition: tls.h:263
struct cipher_algorithm * cipher
Bulk encryption cipher algorithm.
Definition: tls.h:180
struct list_head conn
List of connections.
Definition: tls.h:308
int secure_renegotiation
Secure renegotiation flag.
Definition: tls.h:363
struct pubkey_algorithm * pubkey
Public-key algorithm.
Definition: tls.h:234
void * dynamic
Dynamically-allocated storage.
Definition: tls.h:210
const char * name
Server name.
Definition: tls.h:290
A TLS signature and hash algorithm identifier.
Definition: tls.h:222
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
size_t session_id_len
Length of session ID.
Definition: tls.h:323
struct interface plainstream
Plaintext stream.
Definition: tls.h:330
MD5 algorithm.
TLS client random data.
Definition: tls.h:253
A public key algorithm.
Definition: crypto.h:120
void * fixed_iv
Fixed initialisation vector.
Definition: tls.h:218
union @382 key
Sense key.
Definition: scsi.h:18
uint16_t code
Numeric code (in network-endian order)
Definition: tls.h:186
void * mac_secret
MAC secret.
Definition: tls.h:216
uint64_t tx_seq
TX sequence number.
Definition: tls.h:382
size_t server_key_len
Server Key Exchange record length.
Definition: tls.h:353
A persistent I/O buffer.
Definition: iobuf.h:33
uint8_t key_len
Key length.
Definition: tls.h:188