TLS key schedules. More...

#include <stdint.h>
#include <ipxe/crypto.h>

Data Structures
struct	tls_endpoint
	A TLS endpoint. More...
struct	tls_random
	TLS client or server random bytes. More...
struct	tls_transcript
	A TLS running handshake transcript digest. More...
struct	tls_kdf_secret
	A TLS key derivation function secret. More...
struct	tls_traffic_secret
	A TLS traffic secret. More...
struct	tls_key_schedule
	A TLS key schedule. More...
struct	tls_preshared_key
	A TLS pre-shared key. More...
struct	tls_key_schedule_operations
	TLS key schedule operations. More...

Macros
#define	TLS_CLIENT 0
	Client endpoint index.
#define	TLS_SERVER 1
	Server endpoint index.
#define	TLS_RANDOM_LEN 32
	Number of random bytes.
#define	TLSKEY_TSF_NONCED 0x0001
	Transcript digest includes a Hello record containing the local nonce.
#define	TLSKEY_TSF_FINISHED 0x0002
	Transcript digest includes a Finished record.
#define	TLSKEY_KDF_KEYED 0x0001
	Key derivation function has key material.
#define	TLSKEY_KDF_MASTER 0x0002
	Key derivation function has a master secret.
#define	TLSKEY_KDF_EMS 0x0004
	Key derivation function has an extended master secret.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
static int	tlskey_is_accumulating (struct tls_key_schedule *tlskey)
	Check if key schedule accumulates shared secrets.
int	tlskey_start (struct tls_key_schedule tlskey, const struct tls_key_schedule_operations op, struct digest_algorithm digest, const struct tls_random random)
	Start key schedule.
void	tlskey_stop (struct tls_key_schedule *tlskey)
	Stop key schedule.
void	tlskey_digest (struct tls_key_schedule tlskey, const void data, size_t len)
	Add handshake to running transcript digest.
void	tlskey_reset (struct tls_key_schedule *tlskey)
	Reset key schedule.
int	tlskey_apply (struct tls_key_schedule tlskey, const void shared, size_t shared_len)
	Apply a new shared secret.
int	tlskey_master (struct tls_key_schedule *tlskey, int ems)
	Generate master secret.
int	tlskey_verify (struct tls_key_schedule tlskey, const struct tls_endpoint end, void *verify, size_t verify_len)
	Generate verification data.
int	tlskey_traffic (struct tls_key_schedule tlskey, const struct tls_endpoint writer, const struct tls_phase *phase)
	Generate traffic secret.
int	tlskey_cipher (struct tls_key_schedule tlskey, const struct tls_endpoint writer, void key, size_t key_len, void iv, size_t iv_len, void *mac, size_t mac_len)
	Generate cipher key material.
int	tlskey_tbshash (struct tls_key_schedule tlskey, const struct tls_endpoint end, struct digest_algorithm digest, const void data, size_t len, void *tbs)
	Generate signable digest value.
int	tlskey_save (struct tls_key_schedule tlskey, const void nonce, size_t nonce_len, struct tls_preshared_key *psk)
	Save pre-shared key.
int	tlskey_load (struct tls_key_schedule tlskey, int ems, const struct tls_preshared_key psk)
	Load pre-shared key.
int	tlskey_bind (const struct tls_preshared_key psk, const void prefix, size_t prefix_len, void *binder, size_t binder_len)
	Generate pre-shared key binder value.

Variables
const struct tls_endpoint	tls_client
	Client endpoint.
const struct tls_endpoint	tls_server
	Server endpoint.
const struct tls_phase	tls_early
	Early traffic phase.
const struct tls_phase	tls_handshake
	Handshake traffic phase.
const struct tls_phase	tls_application
	Application traffic phase.
const struct tls_key_schedule_operations	tlskey_hkdf
	TLS key schedule based on HKDF.
const struct tls_key_schedule_operations	tlskey_hash
	TLS key schedule based on P_Hash().
const struct tls_key_schedule_operations	tlskey_md5_sha1
	TLS key schedule based on P_MD5()+P_SHA1().

Detailed Description

TLS key schedules.

Definition in file tlskey.h.

Macro Definition Documentation

◆ TLS_CLIENT

#define TLS_CLIENT 0

Client endpoint index.

Definition at line 27 of file tlskey.h.

Referenced by rfc8448_resumed_test(), rfc8448_simple_test(), tlskey_handshake(), tlskey_hash_cipher(), tlskey_hash_reset(), tlskey_hash_tbshash(), tlskey_hkdf_reset(), and tlskey_reset().

◆ TLS_SERVER

#define TLS_SERVER 1

Server endpoint index.

Definition at line 30 of file tlskey.h.

Referenced by rfc8448_resumed_test(), rfc8448_simple_test(), tlskey_handshake(), tlskey_hash_cipher(), tlskey_hash_reset(), tlskey_hkdf_reset(), and tlskey_reset().

◆ TLS_RANDOM_LEN

#define TLS_RANDOM_LEN 32

Number of random bytes.

Definition at line 33 of file tlskey.h.

◆ TLSKEY_TSF_NONCED

#define TLSKEY_TSF_NONCED 0x0001

Transcript digest includes a Hello record containing the local nonce.

Definition at line 69 of file tlskey.h.

Referenced by tlskey_hash_master(), tlskey_hello(), tlskey_tbshash(), and tlskey_verify().

◆ TLSKEY_TSF_FINISHED

#define TLSKEY_TSF_FINISHED 0x0002

Transcript digest includes a Finished record.

Definition at line 72 of file tlskey.h.

Referenced by tlskey_digest(), and tlskey_finished().

◆ TLSKEY_KDF_KEYED

#define TLSKEY_KDF_KEYED 0x0001

Key derivation function has key material.

Definition at line 83 of file tlskey.h.

Referenced by tlskey_apply(), tlskey_master(), and tlskey_traffic().

◆ TLSKEY_KDF_MASTER

#define TLSKEY_KDF_MASTER 0x0002

Key derivation function has a master secret.

Definition at line 86 of file tlskey.h.

Referenced by tlskey_apply(), tlskey_hash_verify(), tlskey_load(), tlskey_master(), and tlskey_save().

◆ TLSKEY_KDF_EMS

#define TLSKEY_KDF_EMS 0x0004

Key derivation function has an extended master secret.

Definition at line 89 of file tlskey.h.

Referenced by tlskey_load(), and tlskey_master().

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL )

◆ FILE_SECBOOT()

FILE_SECBOOT ( PERMITTED )

◆ tlskey_is_accumulating()

int tlskey_is_accumulating ( struct tls_key_schedule * tlskey )

inlinestatic

Check if key schedule accumulates shared secrets.

Parameters

tlskey Key schedule

Return values

is_accumulating Key schedule accumulates all shared secrets

Definition at line 329 of file tlskey.h.

                                                           {
        const struct tls_key_schedule_operations *op = tlskey->op;
 
        return ( op && op->accumulates );
}

References op, and tls_key_schedule::op.

Referenced by tls_channel_apply().

◆ tlskey_start()

int tlskey_start	(	struct tls_key_schedule *	tlskey,
		const struct tls_key_schedule_operations *	op,
		struct digest_algorithm *	digest,
		const struct tls_random *	nonce )

extern

Start key schedule.

Parameters

tlskey	Key schedule
op	Key schedule operations
digest	Digest algorithm
nonce	Local endpoint random bytes

Return values

rc	Return status code

The random bytes must be the random bytes that the local endpoint will subsequently incorporate within its own ClientHello (or ServerHello, if acting as a server). The caller must guarantee that these are fresh and are unpredictable by the peer. A freshly generated secure channel ephemeral secret can be used to fulfil this requirement.

Definition at line 180 of file tlskey.c.

                                                    {
        size_t digestsize = digest->digestsize;
        size_t ctxsize = digest->ctxsize;
        size_t secretsize;
        size_t total;
        void *dynamic;
        int rc;
 
        /* Stop any existing running key schedule */
        tlskey_stop ( tlskey );
 
        /* Sanity check */
        if ( ! digestsize ) {
                rc = -ENOTTY;
                goto err_sanity;
        }
 
        /* Determine required sizes */
        secretsize = op->secretsize ( digest );
        if ( ! secretsize ) {
                DBGC ( tlskey, "TLSKEY %p cannot use %s with %s\n",
                       tlskey, op->name, digest->name );
                rc = -ENOTSUP;
                goto err_secretsize;
        }
        total = ( secretsize +  /* secret */
                  ctxsize +     /* transcript.ctx */
                  digestsize +  /* transcript.running */
                  digestsize    /* transcript.finishing */ );
 
        /* Allocate dynamic storage */
        dynamic = zalloc ( total );
        if ( ! dynamic ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
 
        /* Initialise schedule */
        tlskey->op = op;
        tlskey->digest = digest;
        tlskey->secretsize = secretsize;
        DBGC ( tlskey, "TLSKEY %p using %s with %s\n",
               tlskey, tlskey->op->name, tlskey->digest->name );
 
        /* Assign dynamic storage */
        tlskey->dynamic = dynamic;
        tlskey->secret = dynamic;               dynamic += secretsize;
        tlskey->transcript.ctx = dynamic;       dynamic += ctxsize;
        tlskey->transcript.running = dynamic;   dynamic += digestsize;
        tlskey->transcript.finishing = dynamic; dynamic += digestsize;
        assert ( dynamic == ( tlskey->dynamic + total ) );
 
        /* Initialise transcript digest */
        digest_init ( digest, tlskey->transcript.ctx );
        tlskey_digest ( tlskey, NULL, 0 );
        memcpy ( &tlskey->nonce, nonce, sizeof ( tlskey->nonce ) );
        DBGC ( tlskey, "TLSKEY %p local nonce:\n", tlskey );
        DBGC_HDA ( tlskey, 0, &tlskey->nonce, sizeof ( tlskey->nonce ) );
 
        /* Reset key schedule */
        tlskey_reset ( tlskey );
 
        return 0;
 
        tlskey_stop ( tlskey );
 err_alloc:
 err_secretsize:
 err_sanity:
        return rc;
}

References assert, tls_transcript::ctx, digest_algorithm::ctxsize, DBGC, DBGC_HDA, tls_key_schedule::digest, digest_init(), digest_algorithm::digestsize, digestsize, tls_key_schedule::dynamic, ENOMEM, ENOTSUP, ENOTTY, tls_transcript::finishing, memcpy(), digest_algorithm::name, tls_key_schedule_operations::name, nonce, tls_key_schedule::nonce, NULL, op, tls_key_schedule::op, rc, tls_transcript::running, tls_key_schedule::secret, tls_key_schedule::secretsize, tlskey_digest(), tlskey_reset(), tlskey_stop(), tls_key_schedule::transcript, and zalloc().

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), and tls_set_digest().

◆ tlskey_stop()

void tlskey_stop ( struct tls_key_schedule * tlskey )

extern

Stop key schedule.

Parameters

tlskey Key schedule

Definition at line 259 of file tlskey.c.

                                                     {
 
        /* Clear and free any dynamic storage */
        zfree ( tlskey->dynamic );
 
        /* Clear key schedule contents */
        memset ( tlskey, 0, sizeof ( *tlskey ) );
 
        /* Set null digest algorithm */
        tlskey->digest = &digest_null;
}

References tls_key_schedule::digest, digest_null, tls_key_schedule::dynamic, memset(), and zfree().

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), tls_clear_digest(), and tlskey_start().

◆ tlskey_digest()

void tlskey_digest	(	struct tls_key_schedule *	tlskey,
		const void *	data,
		size_t	len )

extern

Add handshake to running transcript digest.

Parameters

tlskey	Key schedule
data	Handshake record
len	Length of handshake record

Definition at line 416 of file tlskey.c.

                                  {
        struct tls_transcript *transcript = &tlskey->transcript;
        struct digest_algorithm *digest = tlskey->digest;
        size_t digestsize = digest->digestsize;
        size_t ctxsize = digest->ctxsize;
        unsigned int flags;
        struct {
                uint8_t ctx[ctxsize];
        } tmp;
 
        /* Append to running transcript digest */
        digest_update ( digest, transcript->ctx, data, len );
 
        /* Update running transcript digest output */
        memcpy ( tmp.ctx, transcript->ctx, ctxsize );
        digest_final ( digest, tmp.ctx, transcript->running );
 
        /* Process digested handshake record */
        flags = tlskey_handshake ( tlskey, data, len );
        transcript->flags |= flags;
 
        /* Update the finishing digest value, if applicable */
        if ( ! ( ( transcript->flags ^ flags ) & TLSKEY_TSF_FINISHED ) ) {
                memcpy ( transcript->finishing, transcript->running,
                         digestsize );
        }
 
        /* Clear temporary secrets */
        memset ( &tmp, 0, sizeof ( tmp ) );
}

References ctx, tls_transcript::ctx, digest_algorithm::ctxsize, data, tls_key_schedule::digest, digest_final(), digest_update(), digest_algorithm::digestsize, digestsize, tls_transcript::finishing, flags, tls_transcript::flags, len, memcpy(), memset(), tls_transcript::running, tlskey_handshake(), TLSKEY_TSF_FINISHED, tmp, and tls_key_schedule::transcript.

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), tls_add_handshake(), and tlskey_start().

◆ tlskey_reset()

void tlskey_reset ( struct tls_key_schedule * tlskey )

extern

Reset key schedule.

Parameters

tlskey Key schedule

It is safe to reset a key schedule that has been stopped, or that has not yet been started.

Definition at line 492 of file tlskey.c.

                                                      {
        const struct tls_key_schedule_operations *op = tlskey->op;
 
        /* Do nothing if key schedule is stopped */
        if ( ! op ) {
                assert ( tlskey->secretsize == 0 );
                assert ( tlskey->kdf.flags == 0 );
                assert ( tlskey->traffic[TLS_CLIENT].phase == NULL );
                assert ( tlskey->traffic[TLS_SERVER].phase == NULL );
                return;
        }
 
        /* Clear secrets, flags, and traffic phases */
        memset ( tlskey->secret, 0, tlskey->secretsize );
        tlskey->kdf.flags = 0;
        tlskey->traffic[TLS_CLIENT].phase = NULL;
        tlskey->traffic[TLS_SERVER].phase = NULL;
 
        /* Reset key schedule */
        op->reset ( tlskey );
}

References assert, tls_kdf_secret::flags, tls_key_schedule::kdf, memset(), NULL, op, tls_key_schedule::op, tls_traffic_secret::phase, tls_key_schedule::secret, tls_key_schedule::secretsize, TLS_CLIENT, TLS_SERVER, and tls_key_schedule::traffic.

Referenced by tls_channel_reset(), tlskey_load(), and tlskey_start().

◆ tlskey_apply()

int tlskey_apply	(	struct tls_key_schedule *	tlskey,
		const void *	shared,
		size_t	shared_len )

extern

Apply a new shared secret.

Parameters

tlskey	Key schedule
shared	New shared secret
shared_len	Length of new shared secret

Return values

rc	Return status code

Definition at line 522 of file tlskey.c.

                                       {
        const struct tls_key_schedule_operations *op = tlskey->op;
        int rc;
 
        /* Sanity check */
        if ( ! op )
                return -ENOTTY;
 
        /* All schedules define the master secret as immutable */
        if ( tlskey->kdf.flags & TLSKEY_KDF_MASTER ) {
                DBGC ( tlskey, "TLSKEY %p cannot apply a new shared secret "
                       "after generating master secret\n", tlskey );
                return -EPROTO;
        }
 
        /* Apply new shared secret */
        DBGC ( tlskey, "TLSKEY %p applying secret:\n", tlskey );
        DBGC_HDA ( tlskey, 0, shared, shared_len );
        if ( ( rc = op->apply ( tlskey, shared, shared_len ) ) != 0 )
                return rc;
 
        /* Mark key schedule as containing key material */
        tlskey->kdf.flags |= TLSKEY_KDF_KEYED;
 
        return 0;
}

References DBGC, DBGC_HDA, ENOTTY, EPROTO, tls_kdf_secret::flags, tls_key_schedule::kdf, op, tls_key_schedule::op, rc, TLSKEY_KDF_KEYED, and TLSKEY_KDF_MASTER.

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), tls_channel_apply(), tlskey_hash_load(), tlskey_hash_master(), and tlskey_hkdf_master().

◆ tlskey_master()

int tlskey_master	(	struct tls_key_schedule *	tlskey,
		int	ems )

extern

Generate master secret.

Parameters

tlskey	Key schedule
ems	Extended master secret extension is enabled

Return values

rc	Return status code

Definition at line 557 of file tlskey.c.

                                                               {
        const struct tls_key_schedule_operations *op = tlskey->op;
        int rc;
 
        /* Sanity check */
        if ( ! op )
                return -ENOTTY;
 
        /* Any conceivable schedule requires key material */
        if ( ! ( tlskey->kdf.flags & TLSKEY_KDF_KEYED ) ) {
                DBGC ( tlskey, "TLSKEY %p cannot generate master secret "
                       "without key material\n", tlskey );
                return -EPROTO;
        }
 
        /* All schedules define the master secret as immutable */
        if ( tlskey->kdf.flags & TLSKEY_KDF_MASTER ) {
                DBGC ( tlskey, "TLSKEY %p cannot regenerate master secret\n",
                       tlskey );
                return -EPROTO;
        }
 
        /* Generate master secret */
        DBGC ( tlskey, "TLSKEY %p generating %smaster secret\n",
               tlskey, ( ems ? "extended " : "" ) );
        if ( ( rc = op->master ( tlskey, ems ) ) != 0 )
                return rc;
 
        /* Mark key schedule as containing master secret */
        tlskey->kdf.flags |= TLSKEY_KDF_MASTER;
        if ( ems )
                tlskey->kdf.flags |= TLSKEY_KDF_EMS;
 
        return 0;
}

References DBGC, ENOTTY, EPROTO, tls_kdf_secret::flags, tls_key_schedule::kdf, op, tls_key_schedule::op, rc, TLSKEY_KDF_EMS, TLSKEY_KDF_KEYED, and TLSKEY_KDF_MASTER.

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), and tls_send_client_key_exchange().

◆ tlskey_verify()

int tlskey_verify	(	struct tls_key_schedule *	tlskey,
		const struct tls_endpoint *	end,
		void *	verify,
		size_t	verify_len )

extern

Generate verification data.

Parameters

tlskey	Key schedule
end	Verification endpoint
verify	Verification data to fill in
verify_len	Length of verification data

Return values

rc	Return status code

Definition at line 602 of file tlskey.c.

                                                      {
        const struct tls_key_schedule_operations *op = tlskey->op;
        int rc;
 
        /* Sanity check */
        if ( ! op )
                return -ENOTTY;
 
        /* Verification data must be non-replayable */
        if ( ! ( tlskey->transcript.flags & TLSKEY_TSF_NONCED ) ) {
                DBGC ( tlskey, "TLSKEY %p cannot generate verification data "
                       "without a digested nonce\n", tlskey );
                return -EPROTO;
        }
 
        /* Generate verification data */
        DBGC2 ( tlskey, "TLSKEY %p generating %s verification data\n",
                tlskey, end->name );
        if ( ( rc = op->verify ( tlskey, end, verify, verify_len ) ) != 0 )
                return rc;
        DBGC ( tlskey, "TLSKEY %p %s verification data:\n",
               tlskey, end->name );
        DBGC_HDA ( tlskey, 0, verify, verify_len );
 
        return 0;
}

References DBGC, DBGC2, DBGC_HDA, end, ENOTTY, EPROTO, tls_transcript::flags, op, tls_key_schedule::op, rc, TLSKEY_TSF_NONCED, tls_key_schedule::transcript, and tls_key_schedule_operations::verify.

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), tls_channel_verify(), and tls_send_finished().

◆ tlskey_traffic()

int tlskey_traffic	(	struct tls_key_schedule *	tlskey,
		const struct tls_endpoint *	writer,
		const struct tls_phase *	phase )

extern

Generate traffic secret.

Parameters

tlskey	Key schedule
writer	Writer endpoint
phase	Traffic phase

Return values

rc	Return status code

Definition at line 639 of file tlskey.c.

                                                     {
        const struct tls_key_schedule_operations *op = tlskey->op;
        struct tls_traffic_secret *traffic = &tlskey->traffic[writer->index];
        unsigned int missing;
        int rc;
 
        /* Sanity check */
        if ( ! op )
                return -ENOTTY;
 
        /* Check flags required for this traffic phase */
        assert ( phase->flags & TLSKEY_KDF_KEYED );
        missing = ( ( tlskey->kdf.flags ^ phase->flags ) & phase->flags );
        if ( missing ) {
                DBGC ( tlskey, "TLSKEY %p cannot generate %s %s traffic "
                       "secrets (missing KDF flags %#04x)\n",
                       tlskey, writer->name, phase->name, missing );
                return -EPROTO;
        }
 
        /* Generate traffic secret */
        DBGC2 ( tlskey, "TLSKEY %p generating %s %s traffic secret\n",
                tlskey, writer->name, phase->name );
        if ( ( rc = op->traffic ( tlskey, writer, phase ) ) != 0 )
                return rc;
 
        /* Record phase */
        traffic->phase = phase;
 
        return 0;
}

References assert, DBGC, DBGC2, ENOTTY, EPROTO, tls_kdf_secret::flags, tls_phase::flags, tls_endpoint::index, tls_key_schedule::kdf, tls_endpoint::name, tls_phase::name, op, tls_key_schedule::op, tls_traffic_secret::phase, rc, TLSKEY_KDF_KEYED, and tls_key_schedule::traffic.

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), and tls_change_cipher().

◆ tlskey_cipher()

int tlskey_cipher	(	struct tls_key_schedule *	tlskey,
		const struct tls_endpoint *	writer,
		void *	key,
		size_t	key_len,
		void *	iv,
		size_t	iv_len,
		void *	mac,
		size_t	mac_len )

extern

Generate cipher key material.

Parameters

tlskey	Key schedule
writer	Writer endpoint
key	Cipher key to fill in
key_len	Length of cipher key
iv	Fixed portion of initialisation vector to fill in
iv_len	Length of fixed portion of initialisation vector
mac	MAC secret to fill in
mac_len	Length of MAC secret

Return values

rc	Return status code

For key schedules that include a ratchet mechanism, each call consumes the current generation of traffic secret and replaces it with the next generation. Repeated calls may therefore be used to obtain multiple generations of the cipher key material.

Definition at line 691 of file tlskey.c.

                                                {
        const struct tls_key_schedule_operations *op = tlskey->op;
        struct tls_traffic_secret *traffic = &tlskey->traffic[writer->index];
        int rc;
 
        /* Sanity check */
        if ( ! op )
                return -ENOTTY;
 
        /* Ensure that traffic secret has actually been generated */
        if ( ! traffic->phase ) {
                DBGC ( tlskey, "TLSKEY %p cannot generate cipher key "
                       "material without traffic secrets\n", tlskey );
                return -EPROTO;
        }
 
        /* Generate cipher key material */
        DBGC2 ( tlskey, "TLSKEY %p generating %s %s cipher key material\n",
                tlskey, writer->name, traffic->phase->name );
        if ( ( rc = op->cipher ( tlskey, writer, key, key_len, iv, iv_len,
                                 mac, mac_len ) ) != 0 ) {
                return rc;
        }
        if ( key_len ) {
                DBGC ( tlskey, "TLSKEY %p %s key:\n", tlskey, writer->name );
                DBGC_HDA ( tlskey, 0, key, key_len );
        }
        if ( iv_len ) {
                DBGC ( tlskey, "TLSKEY %p %s IV:\n", tlskey, writer->name );
                DBGC_HDA ( tlskey, 0, iv, iv_len );
        }
        if ( mac_len ) {
                DBGC ( tlskey, "TLSKEY %p %s MAC:\n", tlskey, writer->name );
                DBGC_HDA ( tlskey, 0, mac, mac_len );
        }
 
        return 0;
}

References DBGC, DBGC2, DBGC_HDA, ENOTTY, EPROTO, tls_endpoint::index, iv, key, mac, tls_endpoint::name, tls_phase::name, op, tls_key_schedule::op, tls_traffic_secret::phase, rc, and tls_key_schedule::traffic.

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), and tls_change_cipher().

◆ tlskey_tbshash()

int tlskey_tbshash	(	struct tls_key_schedule *	tlskey,
		const struct tls_endpoint *	end,
		struct digest_algorithm *	digest,
		const void *	data,
		size_t	len,
		void *	tbs )

extern

Generate signable digest value.

Parameters

tlskey	Key schedule
end	Endpoint
digest	Signature digest algorithm
data	Additional data
len	Length of additional data
tbs	Signable digest value to fill in

Return values

rc	Return status code

Definition at line 744 of file tlskey.c.

                                                               {
        const struct tls_key_schedule_operations *op = tlskey->op;
        int rc;
 
        /* Sanity check */
        if ( ! op )
                return -ENOTTY;
 
        /* Signable digest values must be non-replayable */
        if ( ! ( tlskey->transcript.flags & TLSKEY_TSF_NONCED ) ) {
                DBGC ( tlskey, "TLSKEY %p cannot generate signable digest "
                       "without a digested nonce\n", tlskey );
                return -EPROTO;
        }
 
        /* Generate digest value */
        DBGC2 ( tlskey, "TLSKEY %p generating signable %s %s digest\n",
                tlskey, end->name, digest->name );
        if ( ( rc = op->tbshash ( tlskey, end, digest, data, len,
                                  tbs ) ) != 0 ) {
                return rc;
        }
        DBGC ( tlskey, "TLSKEY %p generated signable %s %s digest:\n",
               tlskey, end->name, digest->name );
        DBGC_HDA ( tlskey, 0, tbs, digest->digestsize );
 
        return 0;
}

References data, DBGC, DBGC2, DBGC_HDA, digest_algorithm::digestsize, end, ENOTTY, EPROTO, tls_transcript::flags, len, digest_algorithm::name, op, tls_key_schedule::op, rc, TLSKEY_TSF_NONCED, and tls_key_schedule::transcript.

Referenced by dummy_hash(), rfc8448_simple_test(), tls_new_server_key_exchange(), and tls_send_certificate_verify().

◆ tlskey_save()

int tlskey_save	(	struct tls_key_schedule *	tlskey,
		const void *	nonce,
		size_t	nonce_len,
		struct tls_preshared_key *	psk )

extern

Save pre-shared key.

Parameters

tlskey	Key schedule
nonce	Ticket nonce
nonce_len	Length of ticket nonce
psk	Pre-shared key to fill in

Return values

rc	Return status code

Definition at line 785 of file tlskey.c.

                                                                    {
        const struct tls_key_schedule_operations *op = tlskey->op;
        struct digest_algorithm *digest = tlskey->digest;
        int rc;
 
        /* Clear any existing pre-shared key */
        memset ( psk, 0, sizeof ( *psk ) );
 
        /* Sanity check */
        if ( ! op )
                return -ENOTTY;
 
        /* Session resumption requires a master secret */
        if ( ! ( tlskey->kdf.flags & TLSKEY_KDF_MASTER ) ) {
                DBGC ( tlskey, "TLSKEY %p cannot save key without a master "
                       "secret\n", tlskey );
                return -EPROTO;
        }
 
        /* Save key material */
        DBGC2 ( tlskey, "TLSKEY %p saving key\n", tlskey );
        if ( ( rc = op->save ( tlskey, nonce, nonce_len, psk ) ) != 0 )
                return rc;
        DBGC ( tlskey, "TLSKEY %p saved key:\n", tlskey );
        DBGC_HDA ( tlskey, 0, &psk->key, sizeof ( psk->key ) );
 
        /* Record key properties */
        psk->op = op;
        psk->digest = digest;
        psk->flags = tlskey->kdf.flags;
 
        return 0;
}

References DBGC, DBGC2, DBGC_HDA, tls_key_schedule::digest, tls_preshared_key::digest, ENOTTY, EPROTO, tls_kdf_secret::flags, tls_preshared_key::flags, tls_key_schedule::kdf, tls_preshared_key::key, memset(), nonce, op, tls_key_schedule::op, tls_preshared_key::op, rc, and TLSKEY_KDF_MASTER.

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_simple_test(), and tls_channel_save().

◆ tlskey_load()

int tlskey_load	(	struct tls_key_schedule *	tlskey,
		int	ems,
		const struct tls_preshared_key *	psk )

extern

Load pre-shared key.

Parameters

tlskey	Key schedule
ems	Extended master secret extension is enabled
psk	Pre-shared key

Return values

rc	Return status code

Definition at line 828 of file tlskey.c.

                                                        {
        const struct tls_key_schedule_operations *op = tlskey->op;
        struct digest_algorithm *digest = tlskey->digest;
        int rc;
 
        /* Reset key schedule */
        tlskey_reset ( tlskey );
 
        /* Sanity check */
        if ( ! op )
                return -ENOTTY;
 
        /* Session resumption requires a master secret */
        if ( ! ( psk->flags & TLSKEY_KDF_MASTER ) ) {
                DBGC ( tlskey, "TLSKEY %p cannot load from a non-master "
                       "secret\n", tlskey );
                return -EPROTO;
        }
 
        /* Pre-shared key must match extended/non-extended usage */
        if ( ( !! ems ) != ( !! ( psk->flags & TLSKEY_KDF_EMS ) ) ) {
                DBGC ( tlskey, "TLSKEY %p cannot load from %sextended master "
                       "secret\n", tlskey, ( ems ? "non-" : "" ) );
                return -EPERM;
        }
 
        /* Pre-shared key must match schedule and digest */
        if ( ( op != psk->op ) || ( digest != psk->digest ) ) {
                DBGC ( tlskey, "TLSKEY %p cannot load from %s with %s\n",
                       tlskey, ( psk->op ? psk->op->name : "(unknown)" ),
                       ( psk->digest ? psk->digest->name : "(unknown)" ) );
                return -EPERM;
        }
 
        /* Load key material */
        DBGC ( tlskey, "TLSKEY %p loading key:\n", tlskey );
        DBGC_HDA ( tlskey, 0, &psk->key, sizeof ( psk->key ) );
        if ( ( rc = op->load ( tlskey, psk ) ) != 0 )
                return rc;
 
        /* Set flags */
        tlskey->kdf.flags = ( psk->flags & op->mask );
 
        return 0;
}

References DBGC, DBGC_HDA, tls_key_schedule::digest, tls_preshared_key::digest, ENOTTY, EPERM, EPROTO, tls_kdf_secret::flags, tls_preshared_key::flags, tls_key_schedule::kdf, tls_preshared_key::key, digest_algorithm::name, tls_key_schedule_operations::name, op, tls_key_schedule::op, tls_preshared_key::op, rc, TLSKEY_KDF_EMS, TLSKEY_KDF_MASTER, and tlskey_reset().

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), and tls_channel_load().

◆ tlskey_bind()

int tlskey_bind	(	const struct tls_preshared_key *	psk,
		const void *	prefix,
		size_t	prefix_len,
		void *	binder,
		size_t	binder_len )

extern

Generate pre-shared key binder value.

Parameters

psk	Pre-shared key
prefix	ClientHello prefix
prefix_len	Length of ClientHello prefix
binder	Binder value to fill in
binder_len	Length of binder value

Return values

rc	Return status code

Definition at line 885 of file tlskey.c.

                                                                       {
        const struct tls_key_schedule_operations *op = psk->op;
        struct digest_algorithm *digest = psk->digest;
        int rc;
 
        /* Generate prefix digest and binder value */
        if ( op && digest ) {
                size_t digestsize = digest->digestsize;
                size_t ctxsize = digest->ctxsize;
                uint8_t ctx[ctxsize];
                uint8_t out[digestsize];
 
                /* Calculate prefix digest */
                digest_init ( digest, ctx );
                digest_update ( digest, ctx, prefix, prefix_len );
                digest_final ( digest, ctx, out );
 
                /* Generate binder value */
                DBGC2 ( psk, "TLSKEY %p generating key binder:\n", psk );
                DBGC2_HDA ( psk, 0, &psk->key, sizeof ( psk->key ) );
                if ( ( rc = op->bind ( psk, out, binder, binder_len ) ) != 0 )
                        return rc;
                DBGC ( psk, "TLSKEY %p generated key binder:\n", psk );
                DBGC_HDA ( psk, 0, binder, binder_len );
 
                return 0;
        }
 
        DBGC ( psk, "TLSKEY %p cannot bind empty pre-shared key\n", psk );
        return -ENOENT;
}

References ctx, digest_algorithm::ctxsize, DBGC, DBGC2, DBGC2_HDA, DBGC_HDA, tls_preshared_key::digest, digest_final(), digest_init(), digest_update(), digest_algorithm::digestsize, digestsize, ENOENT, tls_preshared_key::key, op, tls_preshared_key::op, out, prefix, and rc.

Referenced by rfc8448_resumed_test().

Variable Documentation

◆ tls_client

const struct tls_endpoint tls_client

extern

Client endpoint.

Definition at line 102 of file tlskey.c.

                                     {
        .index = TLS_CLIENT,
        .name = "client",
};

◆ tls_server

const struct tls_endpoint tls_server

extern

Server endpoint.

Definition at line 108 of file tlskey.c.

                                     {
        .index = TLS_SERVER,
        .name = "server",
};

◆ tls_early

const struct tls_phase tls_early

extern

Early traffic phase.

Definition at line 137 of file tlskey.c.

                                 {
        .name = "early",
        .label = "e",
        .flags = TLSKEY_KDF_KEYED,
};

Referenced by rfc8448_resumed_test().

◆ tls_handshake

const struct tls_phase tls_handshake

extern

Handshake traffic phase.

Definition at line 144 of file tlskey.c.

                                     {
        .name = "handshake",
        .label = "hs",
        .flags = TLSKEY_KDF_KEYED,
};

Referenced by rfc8448_resumed_test(), rfc8448_simple_test(), and tlskey_hkdf_verify().

◆ tls_application

const struct tls_phase tls_application

extern

Application traffic phase.

Definition at line 151 of file tlskey.c.

                                       {
        .name = "application",
        .label = "ap",
        .flags = ( TLSKEY_KDF_KEYED | TLSKEY_KDF_MASTER ),
};

Referenced by dummy_hash(), dummy_md5_sha1(), rfc8448_resumed_test(), rfc8448_simple_test(), tls_change_cipher(), tlskey_hash_traffic(), and tlskey_hkdf_cipher().

◆ tlskey_hkdf

const struct tls_key_schedule_operations tlskey_hkdf

extern

TLS key schedule based on HKDF.

Definition at line 1369 of file tlskey.c.

                                                     {
        .name = "HKDF",
        .accumulates = 1,
        .mask = TLSKEY_KDF_KEYED,
        .secretsize = tlskey_hkdf_secretsize,
        .expand = tlskey_hkdf_expand,
        .reset = tlskey_hkdf_reset,
        .apply = tlskey_hkdf_apply,
        .master = tlskey_hkdf_master,
        .verify = tlskey_hkdf_verify,
        .traffic = tlskey_hkdf_traffic,
        .cipher = tlskey_hkdf_cipher,
        .tbshash = tlskey_hkdf_tbshash,
        .save = tlskey_hkdf_save,
        .load = tlskey_hkdf_load,
        .bind = tlskey_hkdf_bind,
};

Referenced by rfc8448_resumed_test(), and rfc8448_simple_test().

◆ tlskey_hash

const struct tls_key_schedule_operations tlskey_hash

extern

TLS key schedule based on P_Hash().

Definition at line 1819 of file tlskey.c.

                                                     {
        .name = "P_Hash()",
        .accumulates = 0,
        .mask = ( TLSKEY_KDF_KEYED | TLSKEY_KDF_MASTER | TLSKEY_KDF_EMS ),
        .secretsize = tlskey_hash_secretsize,
        .expand = tlskey_hash_expand,
        .reset = tlskey_hash_reset,
        .apply = tlskey_hash_apply,
        .master = tlskey_hash_master,
        .verify = tlskey_hash_verify,
        .traffic = tlskey_hash_traffic,
        .cipher = tlskey_hash_cipher,
        .tbshash = tlskey_hash_tbshash,
        .save = tlskey_hash_save,
        .load = tlskey_hash_load,
        .bind = tlskey_hash_bind,
};

Referenced by dummy_hash(), and tls_set_digest().

◆ tlskey_md5_sha1

const struct tls_key_schedule_operations tlskey_md5_sha1

extern

TLS key schedule based on P_MD5()+P_SHA1().

Definition at line 1993 of file tlskey.c.

                                                         {
        .name = "P_MD5()+P_SHA1()",
        .accumulates = 0,
        .mask = ( TLSKEY_KDF_KEYED | TLSKEY_KDF_MASTER | TLSKEY_KDF_EMS ),
        .secretsize = tlskey_md5_sha1_secretsize,
        .expand = tlskey_md5_sha1_expand,
        .reset = tlskey_hash_reset,
        .apply = tlskey_md5_sha1_apply,
        .master = tlskey_hash_master,
        .verify = tlskey_hash_verify,
        .traffic = tlskey_hash_traffic,
        .cipher = tlskey_hash_cipher,
        .tbshash = tlskey_hash_tbshash,
        .save = tlskey_md5_sha1_save,
        .load = tlskey_hash_load,
        .bind = tlskey_hash_bind,
};

Referenced by dummy_md5_sha1(), and tls_set_digest().

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ TLS_CLIENT

◆ TLS_SERVER

◆ TLS_RANDOM_LEN

◆ TLSKEY_TSF_NONCED

◆ TLSKEY_TSF_FINISHED

◆ TLSKEY_KDF_KEYED

◆ TLSKEY_KDF_MASTER

◆ TLSKEY_KDF_EMS

Function Documentation

◆ FILE_LICENCE()

◆ FILE_SECBOOT()

◆ tlskey_is_accumulating()

◆ tlskey_start()

◆ tlskey_stop()

◆ tlskey_digest()

◆ tlskey_reset()

◆ tlskey_apply()

◆ tlskey_master()

◆ tlskey_verify()

◆ tlskey_traffic()

◆ tlskey_cipher()

◆ tlskey_tbshash()

◆ tlskey_save()

◆ tlskey_load()

◆ tlskey_bind()

Variable Documentation

◆ tls_client

◆ tls_server

◆ tls_early

◆ tls_handshake

◆ tls_application

◆ tlskey_hkdf

◆ tlskey_hash

◆ tlskey_md5_sha1