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_CERTIFICATE 11 67 #define TLS_SERVER_KEY_EXCHANGE 12 68 #define TLS_CERTIFICATE_REQUEST 13 69 #define TLS_SERVER_HELLO_DONE 14 70 #define TLS_CERTIFICATE_VERIFY 15 71 #define TLS_CLIENT_KEY_EXCHANGE 16 72 #define TLS_FINISHED 20 73 74 /* TLS alert levels */ 75 #define TLS_ALERT_WARNING 1 76 #define TLS_ALERT_FATAL 2 77 78 /* TLS cipher specifications */ 79 #define TLS_RSA_WITH_NULL_MD5 0x0001 80 #define TLS_RSA_WITH_NULL_SHA 0x0002 81 #define TLS_RSA_WITH_AES_128_CBC_SHA 0x002f 82 #define TLS_RSA_WITH_AES_256_CBC_SHA 0x0035 83 #define TLS_RSA_WITH_AES_128_CBC_SHA256 0x003c 84 #define TLS_RSA_WITH_AES_256_CBC_SHA256 0x003d 85 86 /* TLS hash algorithm identifiers */ 87 #define TLS_MD5_ALGORITHM 1 88 #define TLS_SHA1_ALGORITHM 2 89 #define TLS_SHA224_ALGORITHM 3 90 #define TLS_SHA256_ALGORITHM 4 91 #define TLS_SHA384_ALGORITHM 5 92 #define TLS_SHA512_ALGORITHM 6 93 94 /* TLS signature algorithm identifiers */ 95 #define TLS_RSA_ALGORITHM 1 96 97 /* TLS server name extension */ 98 #define TLS_SERVER_NAME 0 99 #define TLS_SERVER_NAME_HOST_NAME 0 100 101 /* TLS maximum fragment length extension */ 102 #define TLS_MAX_FRAGMENT_LENGTH 1 103 #define TLS_MAX_FRAGMENT_LENGTH_512 1 104 #define TLS_MAX_FRAGMENT_LENGTH_1024 2 105 #define TLS_MAX_FRAGMENT_LENGTH_2048 3 106 #define TLS_MAX_FRAGMENT_LENGTH_4096 4 107 108 /* TLS signature algorithms extension */ 109 #define TLS_SIGNATURE_ALGORITHMS 13 110 111 /* TLS renegotiation information extension */ 112 #define TLS_RENEGOTIATION_INFO 0xff01 113 114 /** TLS verification data */ 115 struct tls_verify_data { 116 /** Client verification data */ 117 uint8_t client[12]; 118 /** Server verification data */ 119 uint8_t server[12]; 120 } __attribute__ (( packed )); 121 122 /** TLS RX state machine state */ 123 enum tls_rx_state { 124 TLS_RX_HEADER = 0, 125 TLS_RX_DATA, 126 }; 127 128 /** TLS TX pending flags */ 129 enum tls_tx_pending { 130 TLS_TX_CLIENT_HELLO = 0x0001, 131 TLS_TX_CERTIFICATE = 0x0002, 132 TLS_TX_CLIENT_KEY_EXCHANGE = 0x0004, 133 TLS_TX_CERTIFICATE_VERIFY = 0x0008, 134 TLS_TX_CHANGE_CIPHER = 0x0010, 135 TLS_TX_FINISHED = 0x0020, 136 }; 137 138 /** A TLS cipher suite */ 139 struct tls_cipher_suite { 140 /** Public-key encryption algorithm */ 141 struct pubkey_algorithm *pubkey; 142 /** Bulk encryption cipher algorithm */ 143 struct cipher_algorithm *cipher; 144 /** MAC digest algorithm */ 145 struct digest_algorithm *digest; 146 /** Key length */ 147 uint16_t key_len; 148 /** Numeric code (in network-endian order) */ 149 uint16_t code; 150 }; 151 152 /** TLS cipher suite table */ 153 #define TLS_CIPHER_SUITES \ 154 __table ( struct tls_cipher_suite, "tls_cipher_suites" ) 155 156 /** Declare a TLS cipher suite */ 157 #define __tls_cipher_suite( pref ) \ 158 __table_entry ( TLS_CIPHER_SUITES, pref ) 159 160 /** A TLS cipher specification */ 161 struct tls_cipherspec { 162 /** Cipher suite */ 163 struct tls_cipher_suite *suite; 164 /** Dynamically-allocated storage */ 165 void *dynamic; 166 /** Public key encryption context */ 167 void *pubkey_ctx; 168 /** Bulk encryption cipher context */ 169 void *cipher_ctx; 170 /** Next bulk encryption cipher context (TX only) */ 171 void *cipher_next_ctx; 172 /** MAC secret */ 173 void *mac_secret; 174 }; 175 176 /** A TLS signature and hash algorithm identifier */ 177 struct tls_signature_hash_id { 178 /** Hash algorithm */ 179 uint8_t hash; 180 /** Signature algorithm */ 181 uint8_t signature; 182 } __attribute__ (( packed )); 183 184 /** A TLS signature algorithm */ 185 struct tls_signature_hash_algorithm { 186 /** Digest algorithm */ 187 struct digest_algorithm *digest; 188 /** Public-key algorithm */ 189 struct pubkey_algorithm *pubkey; 190 /** Numeric code */ 191 struct tls_signature_hash_id code; 192 }; 193 194 /** TLS signature hash algorithm table 195 * 196 * Note that the default (TLSv1.1 and earlier) algorithm using 197 * MD5+SHA1 is never explicitly specified. 198 */ 199 #define TLS_SIG_HASH_ALGORITHMS \ 200 __table ( struct tls_signature_hash_algorithm, \ 201 "tls_sig_hash_algorithms" ) 202 203 /** Declare a TLS signature hash algorithm */ 204 #define __tls_sig_hash_algorithm \ 205 __table_entry ( TLS_SIG_HASH_ALGORITHMS, 01 ) 206 207 /** TLS pre-master secret */ 208 struct tls_pre_master_secret { 209 /** TLS version */ 210 uint16_t version; 211 /** Random data */ 212 uint8_t random[46]; 213 } __attribute__ (( packed )); 214 215 /** TLS client random data */ 216 struct tls_client_random { 217 /** GMT Unix time */ 218 uint32_t gmt_unix_time; 219 /** Random data */ 220 uint8_t random[28]; 221 } __attribute__ (( packed )); 222 223 /** An MD5+SHA1 context */ 224 struct md5_sha1_context { 225 /** MD5 context */ 226 uint8_t md5[MD5_CTX_SIZE]; 227 /** SHA-1 context */ 228 uint8_t sha1[SHA1_CTX_SIZE]; 229 } __attribute__ (( packed )); 230 231 /** MD5+SHA1 context size */ 232 #define MD5_SHA1_CTX_SIZE sizeof ( struct md5_sha1_context ) 233 234 /** An MD5+SHA1 digest */ 235 struct md5_sha1_digest { 236 /** MD5 digest */ 237 uint8_t md5[MD5_DIGEST_SIZE]; 238 /** SHA-1 digest */ 239 uint8_t sha1[SHA1_DIGEST_SIZE]; 240 } __attribute__ (( packed )); 241 242 /** MD5+SHA1 digest size */ 243 #define MD5_SHA1_DIGEST_SIZE sizeof ( struct md5_sha1_digest ) 244 245 /** A TLS session */ 246 struct tls_session { 247 /** Reference counter */ 248 struct refcnt refcnt; 249 250 /** Server name */ 251 const char *name; 252 /** Plaintext stream */ 253 struct interface plainstream; 254 /** Ciphertext stream */ 255 struct interface cipherstream; 256 257 /** Protocol version */ 258 uint16_t version; 259 /** Current TX cipher specification */ 260 struct tls_cipherspec tx_cipherspec; 261 /** Next TX cipher specification */ 262 struct tls_cipherspec tx_cipherspec_pending; 263 /** Current RX cipher specification */ 264 struct tls_cipherspec rx_cipherspec; 265 /** Next RX cipher specification */ 266 struct tls_cipherspec rx_cipherspec_pending; 267 /** Premaster secret */ 268 struct tls_pre_master_secret pre_master_secret; 269 /** Master secret */ 270 uint8_t master_secret[48]; 271 /** Server random bytes */ 272 uint8_t server_random[32]; 273 /** Client random bytes */ 274 struct tls_client_random client_random; 275 /** MD5+SHA1 context for handshake verification */ 276 uint8_t handshake_md5_sha1_ctx[MD5_SHA1_CTX_SIZE]; 277 /** SHA256 context for handshake verification */ 278 uint8_t handshake_sha256_ctx[SHA256_CTX_SIZE]; 279 /** Digest algorithm used for handshake verification */ 280 struct digest_algorithm *handshake_digest; 281 /** Digest algorithm context used for handshake verification */ 282 uint8_t *handshake_ctx; 283 /** Client certificate (if used) */ 284 struct x509_certificate *cert; 285 /** Secure renegotiation flag */ 286 int secure_renegotiation; 287 /** Verification data */ 288 struct tls_verify_data verify; 289 290 /** Server certificate chain */ 291 struct x509_chain *chain; 292 /** Certificate validator */ 293 struct interface validator; 294 295 /** Client security negotiation pending operation */ 296 struct pending_operation client_negotiation; 297 /** Server security negotiation pending operation */ 298 struct pending_operation server_negotiation; 299 300 /** TX sequence number */ 301 uint64_t tx_seq; 302 /** TX pending transmissions */ 303 unsigned int tx_pending; 304 /** TX process */ 305 struct process process; 306 307 /** RX sequence number */ 308 uint64_t rx_seq; 309 /** RX state */ 310 enum tls_rx_state rx_state; 311 /** Current received record header */ 312 struct tls_header rx_header; 313 /** Current received record header (static I/O buffer) */ 314 struct io_buffer rx_header_iobuf; 315 /** List of received data buffers */ 316 struct list_head rx_data; 317 }; 318 319 /** RX I/O buffer size 320 * 321 * The maximum fragment length extension is optional, and many common 322 * implementations (including OpenSSL) do not support it. We must 323 * therefore be prepared to receive records of up to 16kB in length. 324 * The chance of an allocation of this size failing is non-negligible, 325 * so we must split received data into smaller allocations. 326 */ 327 #define TLS_RX_BUFSIZE 4096 328 329 /** Minimum RX I/O buffer size 330 * 331 * To simplify manipulations, we ensure that no RX I/O buffer is 332 * smaller than this size. This allows us to assume that the MAC and 333 * padding are entirely contained within the final I/O buffer. 334 */ 335 #define TLS_RX_MIN_BUFSIZE 512 336 337 /** RX I/O buffer alignment */ 338 #define TLS_RX_ALIGN 16 339 340 extern int add_tls ( struct interface *xfer, const char *name, 341 struct interface **next ); 342 343 #endif /* _IPXE_TLS_H */ 344