iPXE
Data Structures | Defines | Enumerations | Functions
tls.h File Reference

Transport Layer Security Protocol. More...

#include <stdint.h>
#include <ipxe/refcnt.h>
#include <ipxe/interface.h>
#include <ipxe/process.h>
#include <ipxe/crypto.h>
#include <ipxe/md5.h>
#include <ipxe/sha1.h>
#include <ipxe/sha256.h>
#include <ipxe/x509.h>
#include <ipxe/pending.h>
#include <ipxe/iobuf.h>
#include <ipxe/tables.h>

Go to the source code of this file.

Data Structures

struct  tls_header
 A TLS header. More...
struct  tls_verify_data
 TLS verification data. More...
struct  tls_cipher_suite
 A TLS cipher suite. More...
struct  tls_cipherspec
 A TLS cipher specification. More...
struct  tls_signature_hash_id
 A TLS signature and hash algorithm identifier. More...
struct  tls_signature_hash_algorithm
 A TLS signature algorithm. More...
struct  tls_pre_master_secret
 TLS pre-master secret. More...
struct  tls_client_random
 TLS client random data. More...
struct  md5_sha1_context
 An MD5+SHA1 context. More...
struct  md5_sha1_digest
 An MD5+SHA1 digest. More...
struct  tls_connection
 A TLS connection. More...

Defines

#define TLS_VERSION_TLS_1_0   0x0301
 TLS version 1.0.
#define TLS_VERSION_TLS_1_1   0x0302
 TLS version 1.1.
#define TLS_VERSION_TLS_1_2   0x0303
 TLS version 1.2.
#define TLS_TYPE_CHANGE_CIPHER   20
 Change cipher content type.
#define TLS_TYPE_ALERT   21
 Alert content type.
#define TLS_TYPE_HANDSHAKE   22
 Handshake content type.
#define TLS_TYPE_DATA   23
 Application data content type.
#define TLS_HELLO_REQUEST   0
#define TLS_CLIENT_HELLO   1
#define TLS_SERVER_HELLO   2
#define TLS_CERTIFICATE   11
#define TLS_SERVER_KEY_EXCHANGE   12
#define TLS_CERTIFICATE_REQUEST   13
#define TLS_SERVER_HELLO_DONE   14
#define TLS_CERTIFICATE_VERIFY   15
#define TLS_CLIENT_KEY_EXCHANGE   16
#define TLS_FINISHED   20
#define TLS_ALERT_WARNING   1
#define TLS_ALERT_FATAL   2
#define TLS_RSA_WITH_NULL_MD5   0x0001
#define TLS_RSA_WITH_NULL_SHA   0x0002
#define TLS_RSA_WITH_AES_128_CBC_SHA   0x002f
#define TLS_RSA_WITH_AES_256_CBC_SHA   0x0035
#define TLS_RSA_WITH_AES_128_CBC_SHA256   0x003c
#define TLS_RSA_WITH_AES_256_CBC_SHA256   0x003d
#define TLS_MD5_ALGORITHM   1
#define TLS_SHA1_ALGORITHM   2
#define TLS_SHA224_ALGORITHM   3
#define TLS_SHA256_ALGORITHM   4
#define TLS_SHA384_ALGORITHM   5
#define TLS_SHA512_ALGORITHM   6
#define TLS_RSA_ALGORITHM   1
#define TLS_SERVER_NAME   0
#define TLS_SERVER_NAME_HOST_NAME   0
#define TLS_MAX_FRAGMENT_LENGTH   1
#define TLS_MAX_FRAGMENT_LENGTH_512   1
#define TLS_MAX_FRAGMENT_LENGTH_1024   2
#define TLS_MAX_FRAGMENT_LENGTH_2048   3
#define TLS_MAX_FRAGMENT_LENGTH_4096   4
#define TLS_SIGNATURE_ALGORITHMS   13
#define TLS_RENEGOTIATION_INFO   0xff01
#define TLS_CIPHER_SUITES   __table ( struct tls_cipher_suite, "tls_cipher_suites" )
 TLS cipher suite table.
#define __tls_cipher_suite(pref)   __table_entry ( TLS_CIPHER_SUITES, pref )
 Declare a TLS cipher suite.
#define TLS_SIG_HASH_ALGORITHMS
 TLS signature hash algorithm table.
#define __tls_sig_hash_algorithm   __table_entry ( TLS_SIG_HASH_ALGORITHMS, 01 )
 Declare a TLS signature hash algorithm.
#define MD5_SHA1_CTX_SIZE   sizeof ( struct md5_sha1_context )
 MD5+SHA1 context size.
#define MD5_SHA1_DIGEST_SIZE   sizeof ( struct md5_sha1_digest )
 MD5+SHA1 digest size.
#define TLS_RX_BUFSIZE   4096
 RX I/O buffer size.
#define TLS_RX_MIN_BUFSIZE   512
 Minimum RX I/O buffer size.
#define TLS_RX_ALIGN   16
 RX I/O buffer alignment.

Enumerations

enum  tls_rx_state { TLS_RX_HEADER = 0, TLS_RX_DATA }
 TLS RX state machine state. More...
enum  tls_tx_pending {
  TLS_TX_CLIENT_HELLO = 0x0001, TLS_TX_CERTIFICATE = 0x0002, TLS_TX_CLIENT_KEY_EXCHANGE = 0x0004, TLS_TX_CERTIFICATE_VERIFY = 0x0008,
  TLS_TX_CHANGE_CIPHER = 0x0010, TLS_TX_FINISHED = 0x0020
}
 TLS TX pending flags. More...

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
int add_tls (struct interface *xfer, const char *name, struct interface **next)

Detailed Description

Transport Layer Security Protocol.

Definition in file tls.h.


Define Documentation

#define TLS_VERSION_TLS_1_0   0x0301

TLS version 1.0.

Definition at line 42 of file tls.h.

Referenced by tls_new_server_hello().

#define TLS_VERSION_TLS_1_1   0x0302

TLS version 1.1.

Definition at line 45 of file tls.h.

Referenced by tls_assemble_block(), and tls_split_block().

#define TLS_VERSION_TLS_1_2   0x0303

TLS version 1.2.

Definition at line 48 of file tls.h.

Referenced by add_tls(), tls_new_server_hello(), tls_prf(), and tls_send_certificate_verify().

#define TLS_TYPE_CHANGE_CIPHER   20

Change cipher content type.

Definition at line 51 of file tls.h.

Referenced by tls_new_record(), and tls_send_change_cipher().

#define TLS_TYPE_ALERT   21

Alert content type.

Definition at line 54 of file tls.h.

Referenced by tls_new_record().

#define TLS_TYPE_HANDSHAKE   22

Handshake content type.

Definition at line 57 of file tls.h.

Referenced by tls_new_record(), and tls_send_handshake().

#define TLS_TYPE_DATA   23

Application data content type.

Definition at line 60 of file tls.h.

Referenced by tls_new_record(), and tls_plainstream_deliver().

#define TLS_HELLO_REQUEST   0

Definition at line 63 of file tls.h.

Referenced by tls_new_handshake().

#define TLS_CLIENT_HELLO   1

Definition at line 64 of file tls.h.

Referenced by tls_send_client_hello().

#define TLS_SERVER_HELLO   2

Definition at line 65 of file tls.h.

Referenced by tls_new_handshake().

#define TLS_CERTIFICATE   11

Definition at line 66 of file tls.h.

Referenced by tls_new_handshake(), and tls_send_certificate().

#define TLS_SERVER_KEY_EXCHANGE   12

Definition at line 67 of file tls.h.

#define TLS_CERTIFICATE_REQUEST   13

Definition at line 68 of file tls.h.

Referenced by tls_new_handshake().

#define TLS_SERVER_HELLO_DONE   14

Definition at line 69 of file tls.h.

Referenced by tls_new_handshake().

#define TLS_CERTIFICATE_VERIFY   15

Definition at line 70 of file tls.h.

Referenced by tls_send_certificate_verify().

#define TLS_CLIENT_KEY_EXCHANGE   16

Definition at line 71 of file tls.h.

Referenced by tls_send_client_key_exchange().

#define TLS_FINISHED   20

Definition at line 72 of file tls.h.

Referenced by tls_new_handshake(), and tls_send_finished().

#define TLS_ALERT_WARNING   1

Definition at line 75 of file tls.h.

Referenced by tls_new_alert().

#define TLS_ALERT_FATAL   2

Definition at line 76 of file tls.h.

Referenced by tls_new_alert().

#define TLS_RSA_WITH_NULL_MD5   0x0001

Definition at line 79 of file tls.h.

#define TLS_RSA_WITH_NULL_SHA   0x0002

Definition at line 80 of file tls.h.

#define TLS_RSA_WITH_AES_128_CBC_SHA   0x002f

Definition at line 81 of file tls.h.

#define TLS_RSA_WITH_AES_256_CBC_SHA   0x0035

Definition at line 82 of file tls.h.

#define TLS_RSA_WITH_AES_128_CBC_SHA256   0x003c

Definition at line 83 of file tls.h.

#define TLS_RSA_WITH_AES_256_CBC_SHA256   0x003d

Definition at line 84 of file tls.h.

#define TLS_MD5_ALGORITHM   1

Definition at line 87 of file tls.h.

#define TLS_SHA1_ALGORITHM   2

Definition at line 88 of file tls.h.

#define TLS_SHA224_ALGORITHM   3

Definition at line 89 of file tls.h.

#define TLS_SHA256_ALGORITHM   4

Definition at line 90 of file tls.h.

#define TLS_SHA384_ALGORITHM   5

Definition at line 91 of file tls.h.

#define TLS_SHA512_ALGORITHM   6

Definition at line 92 of file tls.h.

#define TLS_RSA_ALGORITHM   1

Definition at line 95 of file tls.h.

#define TLS_SERVER_NAME   0

Definition at line 98 of file tls.h.

Referenced by tls_send_client_hello().

#define TLS_SERVER_NAME_HOST_NAME   0

Definition at line 99 of file tls.h.

Referenced by tls_send_client_hello().

#define TLS_MAX_FRAGMENT_LENGTH   1

Definition at line 102 of file tls.h.

Referenced by tls_send_client_hello().

Definition at line 103 of file tls.h.

Definition at line 104 of file tls.h.

Definition at line 105 of file tls.h.

Definition at line 106 of file tls.h.

Referenced by tls_send_client_hello().

#define TLS_SIGNATURE_ALGORITHMS   13

Definition at line 109 of file tls.h.

Referenced by tls_send_client_hello().

#define TLS_RENEGOTIATION_INFO   0xff01

Definition at line 112 of file tls.h.

Referenced by tls_new_server_hello(), and tls_send_client_hello().

#define TLS_CIPHER_SUITES   __table ( struct tls_cipher_suite, "tls_cipher_suites" )

TLS cipher suite table.

Definition at line 153 of file tls.h.

Referenced by tls_find_cipher_suite(), and tls_send_client_hello().

#define __tls_cipher_suite (   pref)    __table_entry ( TLS_CIPHER_SUITES, pref )

Declare a TLS cipher suite.

Definition at line 157 of file tls.h.

Value:
__table ( struct tls_signature_hash_algorithm,                  \
                  "tls_sig_hash_algorithms" )

TLS signature hash algorithm table.

Note that the default (TLSv1.1 and earlier) algorithm using MD5+SHA1 is never explicitly specified.

Definition at line 199 of file tls.h.

Referenced by tls_send_client_hello(), and tls_signature_hash_algorithm().

Declare a TLS signature hash algorithm.

Definition at line 204 of file tls.h.

#define MD5_SHA1_CTX_SIZE   sizeof ( struct md5_sha1_context )

MD5+SHA1 context size.

Definition at line 232 of file tls.h.

#define MD5_SHA1_DIGEST_SIZE   sizeof ( struct md5_sha1_digest )

MD5+SHA1 digest size.

Definition at line 243 of file tls.h.

#define TLS_RX_BUFSIZE   4096

RX I/O buffer size.

The maximum fragment length extension is optional, and many common implementations (including OpenSSL) do not support it. We must therefore be prepared to receive records of up to 16kB in length. The chance of an allocation of this size failing is non-negligible, so we must split received data into smaller allocations.

Definition at line 327 of file tls.h.

Referenced by tls_newdata_process_header().

#define TLS_RX_MIN_BUFSIZE   512

Minimum RX I/O buffer size.

To simplify manipulations, we ensure that no RX I/O buffer is smaller than this size. This allows us to assume that the MAC and padding are entirely contained within the final I/O buffer.

Definition at line 335 of file tls.h.

Referenced by tls_newdata_process_header().

#define TLS_RX_ALIGN   16

RX I/O buffer alignment.

Definition at line 338 of file tls.h.

Referenced by tls_newdata_process_header().


Enumeration Type Documentation

TLS RX state machine state.

Enumerator:
TLS_RX_HEADER 
TLS_RX_DATA 

Definition at line 123 of file tls.h.

TLS TX pending flags.

Enumerator:
TLS_TX_CLIENT_HELLO 
TLS_TX_CERTIFICATE 
TLS_TX_CLIENT_KEY_EXCHANGE 
TLS_TX_CERTIFICATE_VERIFY 
TLS_TX_CHANGE_CIPHER 
TLS_TX_FINISHED 

Definition at line 129 of file tls.h.


Function Documentation

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )
int add_tls ( struct interface xfer,
const char *  name,
struct interface **  next 
)

Definition at line 2776 of file tls.c.

References tls_connection::cipherstream, tls_connection::client_random, ENOMEM, free_tls(), tls_client_random::gmt_unix_time, htons, INIT_LIST_HEAD, intf_init(), intf_plug_plug(), iob_populate(), malloc(), memset(), tls_connection::name, name, NULL, tls_connection::plainstream, tls_connection::pre_master_secret, tls_connection::process, process_init(), tls_pre_master_secret::random, tls_client_random::random, rc, ref_init, ref_put, tls_connection::refcnt, tls_connection::rx_cipherspec, tls_connection::rx_cipherspec_pending, tls_connection::rx_data, tls_connection::rx_header, tls_connection::rx_header_iobuf, time, tls_clear_cipher(), tls_generate_random(), tls_restart(), TLS_VERSION_TLS_1_2, tls_connection::tx_cipherspec, tls_connection::tx_cipherspec_pending, tls_connection::validator, tls_pre_master_secret::version, and tls_connection::version.

Referenced by apply_syslogs_settings().

                                        {
        struct tls_connection *tls;
        int rc;

        /* Allocate and initialise TLS structure */
        tls = malloc ( sizeof ( *tls ) );
        if ( ! tls ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
        memset ( tls, 0, sizeof ( *tls ) );
        ref_init ( &tls->refcnt, free_tls );
        tls->name = name;
        intf_init ( &tls->plainstream, &tls_plainstream_desc, &tls->refcnt );
        intf_init ( &tls->cipherstream, &tls_cipherstream_desc, &tls->refcnt );
        intf_init ( &tls->validator, &tls_validator_desc, &tls->refcnt );
        process_init ( &tls->process, &tls_process_desc, &tls->refcnt );
        tls->version = TLS_VERSION_TLS_1_2;
        tls_clear_cipher ( tls, &tls->tx_cipherspec );
        tls_clear_cipher ( tls, &tls->tx_cipherspec_pending );
        tls_clear_cipher ( tls, &tls->rx_cipherspec );
        tls_clear_cipher ( tls, &tls->rx_cipherspec_pending );
        tls->client_random.gmt_unix_time = time ( NULL );
        iob_populate ( &tls->rx_header_iobuf, &tls->rx_header, 0,
                       sizeof ( tls->rx_header ) );
        INIT_LIST_HEAD ( &tls->rx_data );
        if ( ( rc = tls_generate_random ( tls, &tls->client_random.random,
                          ( sizeof ( tls->client_random.random ) ) ) ) != 0 ) {
                goto err_random;
        }
        tls->pre_master_secret.version = htons ( tls->version );
        if ( ( rc = tls_generate_random ( tls, &tls->pre_master_secret.random,
                      ( sizeof ( tls->pre_master_secret.random ) ) ) ) != 0 ) {
                goto err_random;
        }

        /* Start negotiation */
        tls_restart ( tls );

        /* Attach to parent interface, mortalise self, and return */
        intf_plug_plug ( &tls->plainstream, xfer );
        *next = &tls->cipherstream;
        ref_put ( &tls->refcnt );
        return 0;

 err_random:
        ref_put ( &tls->refcnt );
 err_alloc:
        return rc;
}