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