iPXE
tls.h
Go to the documentation of this file.
00001 #ifndef _IPXE_TLS_H
00002 #define _IPXE_TLS_H
00003 
00004 /**
00005  * @file
00006  *
00007  * Transport Layer Security Protocol
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <stdint.h>
00013 #include <ipxe/refcnt.h>
00014 #include <ipxe/interface.h>
00015 #include <ipxe/process.h>
00016 #include <ipxe/crypto.h>
00017 #include <ipxe/md5.h>
00018 #include <ipxe/sha1.h>
00019 #include <ipxe/sha256.h>
00020 #include <ipxe/x509.h>
00021 #include <ipxe/pending.h>
00022 #include <ipxe/iobuf.h>
00023 #include <ipxe/tables.h>
00024 
00025 /** A TLS header */
00026 struct tls_header {
00027         /** Content type
00028          *
00029          * This is a TLS_TYPE_XXX constant
00030          */
00031         uint8_t type;
00032         /** Protocol version
00033          *
00034          * This is a TLS_VERSION_XXX constant
00035          */
00036         uint16_t version;
00037         /** Length of payload */
00038         uint16_t length;
00039 } __attribute__ (( packed ));
00040 
00041 /** TLS version 1.0 */
00042 #define TLS_VERSION_TLS_1_0 0x0301
00043 
00044 /** TLS version 1.1 */
00045 #define TLS_VERSION_TLS_1_1 0x0302
00046 
00047 /** TLS version 1.2 */
00048 #define TLS_VERSION_TLS_1_2 0x0303
00049 
00050 /** Change cipher content type */
00051 #define TLS_TYPE_CHANGE_CIPHER 20
00052 
00053 /** Alert content type */
00054 #define TLS_TYPE_ALERT 21
00055 
00056 /** Handshake content type */
00057 #define TLS_TYPE_HANDSHAKE 22
00058 
00059 /** Application data content type */
00060 #define TLS_TYPE_DATA 23
00061 
00062 /* Handshake message types */
00063 #define TLS_HELLO_REQUEST 0
00064 #define TLS_CLIENT_HELLO 1
00065 #define TLS_SERVER_HELLO 2
00066 #define TLS_NEW_SESSION_TICKET 4
00067 #define TLS_CERTIFICATE 11
00068 #define TLS_SERVER_KEY_EXCHANGE 12
00069 #define TLS_CERTIFICATE_REQUEST 13
00070 #define TLS_SERVER_HELLO_DONE 14
00071 #define TLS_CERTIFICATE_VERIFY 15
00072 #define TLS_CLIENT_KEY_EXCHANGE 16
00073 #define TLS_FINISHED 20
00074 
00075 /* TLS alert levels */
00076 #define TLS_ALERT_WARNING 1
00077 #define TLS_ALERT_FATAL 2
00078 
00079 /* TLS cipher specifications */
00080 #define TLS_RSA_WITH_NULL_MD5 0x0001
00081 #define TLS_RSA_WITH_NULL_SHA 0x0002
00082 #define TLS_RSA_WITH_AES_128_CBC_SHA 0x002f
00083 #define TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
00084 #define TLS_RSA_WITH_AES_128_CBC_SHA256 0x003c
00085 #define TLS_RSA_WITH_AES_256_CBC_SHA256 0x003d
00086 
00087 /* TLS hash algorithm identifiers */
00088 #define TLS_MD5_ALGORITHM 1
00089 #define TLS_SHA1_ALGORITHM 2
00090 #define TLS_SHA224_ALGORITHM 3
00091 #define TLS_SHA256_ALGORITHM 4
00092 #define TLS_SHA384_ALGORITHM 5
00093 #define TLS_SHA512_ALGORITHM 6
00094 
00095 /* TLS signature algorithm identifiers */
00096 #define TLS_RSA_ALGORITHM 1
00097 
00098 /* TLS server name extension */
00099 #define TLS_SERVER_NAME 0
00100 #define TLS_SERVER_NAME_HOST_NAME 0
00101 
00102 /* TLS maximum fragment length extension */
00103 #define TLS_MAX_FRAGMENT_LENGTH 1
00104 #define TLS_MAX_FRAGMENT_LENGTH_512 1
00105 #define TLS_MAX_FRAGMENT_LENGTH_1024 2
00106 #define TLS_MAX_FRAGMENT_LENGTH_2048 3
00107 #define TLS_MAX_FRAGMENT_LENGTH_4096 4
00108 
00109 /* TLS signature algorithms extension */
00110 #define TLS_SIGNATURE_ALGORITHMS 13
00111 
00112 /* TLS session ticket extension */
00113 #define TLS_SESSION_TICKET 35
00114 
00115 /* TLS renegotiation information extension */
00116 #define TLS_RENEGOTIATION_INFO 0xff01
00117 
00118 /** TLS verification data */
00119 struct tls_verify_data {
00120         /** Client verification data */
00121         uint8_t client[12];
00122         /** Server verification data */
00123         uint8_t server[12];
00124 } __attribute__ (( packed ));
00125 
00126 /** TLS RX state machine state */
00127 enum tls_rx_state {
00128         TLS_RX_HEADER = 0,
00129         TLS_RX_DATA,
00130 };
00131 
00132 /** TLS TX pending flags */
00133 enum tls_tx_pending {
00134         TLS_TX_CLIENT_HELLO = 0x0001,
00135         TLS_TX_CERTIFICATE = 0x0002,
00136         TLS_TX_CLIENT_KEY_EXCHANGE = 0x0004,
00137         TLS_TX_CERTIFICATE_VERIFY = 0x0008,
00138         TLS_TX_CHANGE_CIPHER = 0x0010,
00139         TLS_TX_FINISHED = 0x0020,
00140 };
00141 
00142 /** A TLS cipher suite */
00143 struct tls_cipher_suite {
00144         /** Public-key encryption algorithm */
00145         struct pubkey_algorithm *pubkey;
00146         /** Bulk encryption cipher algorithm */
00147         struct cipher_algorithm *cipher;
00148         /** MAC digest algorithm */
00149         struct digest_algorithm *digest;
00150         /** Key length */
00151         uint16_t key_len;
00152         /** Numeric code (in network-endian order) */
00153         uint16_t code;
00154 };
00155 
00156 /** TLS cipher suite table */
00157 #define TLS_CIPHER_SUITES                                               \
00158         __table ( struct tls_cipher_suite, "tls_cipher_suites" )
00159 
00160 /** Declare a TLS cipher suite */
00161 #define __tls_cipher_suite( pref )                                      \
00162         __table_entry ( TLS_CIPHER_SUITES, pref )
00163 
00164 /** A TLS cipher specification */
00165 struct tls_cipherspec {
00166         /** Cipher suite */
00167         struct tls_cipher_suite *suite;
00168         /** Dynamically-allocated storage */
00169         void *dynamic;
00170         /** Public key encryption context */
00171         void *pubkey_ctx;
00172         /** Bulk encryption cipher context */
00173         void *cipher_ctx;
00174         /** Next bulk encryption cipher context (TX only) */
00175         void *cipher_next_ctx;
00176         /** MAC secret */
00177         void *mac_secret;
00178 };
00179 
00180 /** A TLS signature and hash algorithm identifier */
00181 struct tls_signature_hash_id {
00182         /** Hash algorithm */
00183         uint8_t hash;
00184         /** Signature algorithm */
00185         uint8_t signature;
00186 } __attribute__ (( packed ));
00187 
00188 /** A TLS signature algorithm */
00189 struct tls_signature_hash_algorithm {
00190         /** Digest algorithm */
00191         struct digest_algorithm *digest;
00192         /** Public-key algorithm */
00193         struct pubkey_algorithm *pubkey;
00194         /** Numeric code */
00195         struct tls_signature_hash_id code;
00196 };
00197 
00198 /** TLS signature hash algorithm table
00199  *
00200  * Note that the default (TLSv1.1 and earlier) algorithm using
00201  * MD5+SHA1 is never explicitly specified.
00202  */
00203 #define TLS_SIG_HASH_ALGORITHMS                                         \
00204         __table ( struct tls_signature_hash_algorithm,                  \
00205                   "tls_sig_hash_algorithms" )
00206 
00207 /** Declare a TLS signature hash algorithm */
00208 #define __tls_sig_hash_algorithm                                        \
00209         __table_entry ( TLS_SIG_HASH_ALGORITHMS, 01 )
00210 
00211 /** TLS pre-master secret */
00212 struct tls_pre_master_secret {
00213         /** TLS version */
00214         uint16_t version;
00215         /** Random data */
00216         uint8_t random[46];
00217 } __attribute__ (( packed ));
00218 
00219 /** TLS client random data */
00220 struct tls_client_random {
00221         /** GMT Unix time */
00222         uint32_t gmt_unix_time;
00223         /** Random data */
00224         uint8_t random[28];
00225 } __attribute__ (( packed ));
00226 
00227 /** An MD5+SHA1 context */
00228 struct md5_sha1_context {
00229         /** MD5 context */
00230         uint8_t md5[MD5_CTX_SIZE];
00231         /** SHA-1 context */
00232         uint8_t sha1[SHA1_CTX_SIZE];
00233 } __attribute__ (( packed ));
00234 
00235 /** MD5+SHA1 context size */
00236 #define MD5_SHA1_CTX_SIZE sizeof ( struct md5_sha1_context )
00237 
00238 /** An MD5+SHA1 digest */
00239 struct md5_sha1_digest {
00240         /** MD5 digest */
00241         uint8_t md5[MD5_DIGEST_SIZE];
00242         /** SHA-1 digest */
00243         uint8_t sha1[SHA1_DIGEST_SIZE];
00244 } __attribute__ (( packed ));
00245 
00246 /** MD5+SHA1 digest size */
00247 #define MD5_SHA1_DIGEST_SIZE sizeof ( struct md5_sha1_digest )
00248 
00249 /** A TLS session */
00250 struct tls_session {
00251         /** Reference counter */
00252         struct refcnt refcnt;
00253         /** List of sessions */
00254         struct list_head list;
00255 
00256         /** Server name */
00257         const char *name;
00258         /** Session ID */
00259         uint8_t id[32];
00260         /** Length of session ID */
00261         size_t id_len;
00262         /** Session ticket */
00263         void *ticket;
00264         /** Length of session ticket */
00265         size_t ticket_len;
00266         /** Master secret */
00267         uint8_t master_secret[48];
00268 
00269         /** List of connections */
00270         struct list_head conn;
00271 };
00272 
00273 /** A TLS connection */
00274 struct tls_connection {
00275         /** Reference counter */
00276         struct refcnt refcnt;
00277 
00278         /** Session */
00279         struct tls_session *session;
00280         /** List of connections within the same session */
00281         struct list_head list;
00282         /** Session ID */
00283         uint8_t session_id[32];
00284         /** Length of session ID */
00285         size_t session_id_len;
00286         /** New session ticket */
00287         void *new_session_ticket;
00288         /** Length of new session ticket */
00289         size_t new_session_ticket_len;
00290 
00291         /** Plaintext stream */
00292         struct interface plainstream;
00293         /** Ciphertext stream */
00294         struct interface cipherstream;
00295 
00296         /** Protocol version */
00297         uint16_t version;
00298         /** Current TX cipher specification */
00299         struct tls_cipherspec tx_cipherspec;
00300         /** Next TX cipher specification */
00301         struct tls_cipherspec tx_cipherspec_pending;
00302         /** Current RX cipher specification */
00303         struct tls_cipherspec rx_cipherspec;
00304         /** Next RX cipher specification */
00305         struct tls_cipherspec rx_cipherspec_pending;
00306         /** Premaster secret */
00307         struct tls_pre_master_secret pre_master_secret;
00308         /** Master secret */
00309         uint8_t master_secret[48];
00310         /** Server random bytes */
00311         uint8_t server_random[32];
00312         /** Client random bytes */
00313         struct tls_client_random client_random;
00314         /** MD5+SHA1 context for handshake verification */
00315         uint8_t handshake_md5_sha1_ctx[MD5_SHA1_CTX_SIZE];
00316         /** SHA256 context for handshake verification */
00317         uint8_t handshake_sha256_ctx[SHA256_CTX_SIZE];
00318         /** Digest algorithm used for handshake verification */
00319         struct digest_algorithm *handshake_digest;
00320         /** Digest algorithm context used for handshake verification */
00321         uint8_t *handshake_ctx;
00322         /** Client certificate (if used) */
00323         struct x509_certificate *cert;
00324         /** Secure renegotiation flag */
00325         int secure_renegotiation;
00326         /** Verification data */
00327         struct tls_verify_data verify;
00328 
00329         /** Server certificate chain */
00330         struct x509_chain *chain;
00331         /** Certificate validator */
00332         struct interface validator;
00333 
00334         /** Client security negotiation pending operation */
00335         struct pending_operation client_negotiation;
00336         /** Server security negotiation pending operation */
00337         struct pending_operation server_negotiation;
00338         /** Certificate validation pending operation */
00339         struct pending_operation validation;
00340 
00341         /** TX sequence number */
00342         uint64_t tx_seq;
00343         /** TX pending transmissions */
00344         unsigned int tx_pending;
00345         /** TX process */
00346         struct process process;
00347 
00348         /** RX sequence number */
00349         uint64_t rx_seq;
00350         /** RX state */
00351         enum tls_rx_state rx_state;
00352         /** Current received record header */
00353         struct tls_header rx_header;
00354         /** Current received record header (static I/O buffer) */
00355         struct io_buffer rx_header_iobuf;
00356         /** List of received data buffers */
00357         struct list_head rx_data;
00358 };
00359 
00360 /** RX I/O buffer size
00361  *
00362  * The maximum fragment length extension is optional, and many common
00363  * implementations (including OpenSSL) do not support it.  We must
00364  * therefore be prepared to receive records of up to 16kB in length.
00365  * The chance of an allocation of this size failing is non-negligible,
00366  * so we must split received data into smaller allocations.
00367  */
00368 #define TLS_RX_BUFSIZE 4096
00369 
00370 /** Minimum RX I/O buffer size
00371  *
00372  * To simplify manipulations, we ensure that no RX I/O buffer is
00373  * smaller than this size.  This allows us to assume that the MAC and
00374  * padding are entirely contained within the final I/O buffer.
00375  */
00376 #define TLS_RX_MIN_BUFSIZE 512
00377 
00378 /** RX I/O buffer alignment */
00379 #define TLS_RX_ALIGN 16
00380 
00381 extern int add_tls ( struct interface *xfer, const char *name,
00382                      struct interface **next );
00383 
00384 #endif /* _IPXE_TLS_H */