channel.c File Reference

Secure channel abstraction. More...

#include <string.h>
#include <errno.h>
#include <ipxe/malloc.h>
#include <ipxe/crypto.h>
#include <ipxe/hkdf.h>
#include <ipxe/rbg.h>
#include <ipxe/channel.h>

Go to the source code of this file.

Macros
#define	ENOTTY_TRANSPORT   __einfo_error ( EINFO_ENOTTY_TRANSPORT )
#define	EINFO_ENOTTY_TRANSPORT   __einfo_uniqify ( EINFO_ENOTTY, 0x01, "Untransportable key" )
#define	EPERM_NOT_CONFIDENTIAL   __einfo_error ( EINFO_EPERM_NOT_CONFIDENTIAL )
#define	EINFO_EPERM_NOT_CONFIDENTIAL   __einfo_uniqify ( EINFO_EPERM, 0x01, "Not confidential" )
#define	EPERM_NOT_VALID   __einfo_error ( EINFO_EPERM_NOT_VALID )
#define	EINFO_EPERM_NOT_VALID   __einfo_uniqify ( EINFO_EPERM, 0x02, "Peer certificate not valid" )
#define	EPROTO_NOT_KEYED   __einfo_error ( EINFO_EPROTO_NOT_KEYED )
#define	EINFO_EPROTO_NOT_KEYED   __einfo_uniqify ( EINFO_EPROTO, 0x01, "No shared key material" )
#define	EPROTO_NOT_BOUND   __einfo_error ( EINFO_EPROTO_NOT_BOUND )
#define	EINFO_EPROTO_NOT_BOUND   __einfo_uniqify ( EINFO_EPROTO, 0x02, "No bound peer identity" )
#define	EPROTO_NOT_CONFIRMED   __einfo_error ( EINFO_EPROTO_NOT_CONFIRMED )
#define	EINFO_EPROTO_NOT_CONFIRMED   __einfo_uniqify ( EINFO_EPROTO, 0x03, "No confirmed peer identity" )

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
static void	channel_unbind (struct secure_channel *channel)
	Clear bound peer identity.
static void	channel_unconfirm (struct secure_channel *channel)
	Clear confirmed peer identity.
static void	channel_unestablish (struct secure_channel *channel)
	Clear established peer identity.
static int	channel_ephemeral_init (struct secure_channel *channel)
	Initialise ephemeral master secret.
void	channel_ephemeral (struct secure_channel *channel, const void *info, size_t info_len, void *out, size_t len)
	Generate ephemeral secret.
void	channel_ephemeral_label (struct secure_channel *channel, const char *label, void *out, size_t len)
	Generate labelled ephemeral secret.
static void	channel_ephemeral_replace (struct secure_channel *channel)
	Replace ephemeral master secret.
void	channel_unkey (struct secure_channel *channel)
	Clear shared secret.
static void	channel_key_private (struct secure_channel *channel, struct exchange_algorithm *exchange, void *private)
	Generate private key.
int	channel_key_share (struct secure_channel *channel, struct exchange_algorithm *exchange, void *public)
	Share public key.
static int	channel_key (struct secure_channel *channel, struct exchange_algorithm *exchange, const void *partner, void *shared)
	Generate and apply shared secret.
int	channel_key_agree (struct secure_channel *channel, struct exchange_algorithm *exchange, const void *partner)
	Agree shared secret.
static int	channel_key_transport (struct secure_channel *channel, struct exchange_algorithm *exchange, void *shared)
	Transport shared secret.
static int	channel_bind (struct secure_channel *channel, struct x509_certificate *identity)
	Set bound peer identity.
int	channel_bind_verify (struct secure_channel *channel, struct x509_certificate *identity, struct pubkey_algorithm *pubkey, struct digest_algorithm *digest, const void *value, const struct asn1_cursor *signature)
	Bind peer identity via ephemeral public key signature verification.
int	channel_bind_encrypt (struct secure_channel *channel, struct x509_certificate *identity, struct exchange_algorithm *exchange, struct pubkey_algorithm *pubkey, struct asn1_builder *ciphertext)
	Bind peer identity via shared secret encryption.
int	channel_save (struct secure_channel *channel, struct secure_preshared_identity *psid)
	Save a pre-shared key.
int	channel_load (struct secure_channel *channel, struct secure_preshared_identity *psid)
	Load a pre-shared key.
int	channel_confirm (struct secure_channel *channel, const void *auth, size_t len)
	Confirm peer identity.
int	channel_establish (struct secure_channel *channel, const char *name, struct x509_root *root)
	Establish channel as trusted for application data.
static void	channel_dead_crypt (struct cipher_algorithm *cipher __unused, void *ctx __unused, const void *src __unused, void *dst, size_t len)
	Encrypt or decrypt data via dead cipher.
static const char *	channel_pipe_name (struct secure_channel *channel, struct secure_pipe *pipe)
	Get pipe name (for debugging).
static void	channel_clear_cipher (struct secure_pipe *pipe)
	Clear cipher algorithm.
int	channel_set_cipher (struct secure_channel *channel, struct secure_pipe *pipe, struct cipher_algorithm *cipher, const void *key, size_t len)
	Set cipher algorithm and key.
int	channel_open (struct secure_channel *channel)
	Open secure channel.
void	channel_reopen (struct secure_channel *channel)
	Reopen secure channel.
void	channel_close (struct secure_channel *channel)
	Close secure channel.

Variables
struct cipher_algorithm	channel_dead_cipher
	Dead cipher.

Detailed Description

Secure channel abstraction.

We define a concept of a secure channel as comprising a pair of ciphers (one for transmit, one for receive) together with the cryptographic state required to establish that these ciphers may be used for encrypted communication with a trusted peer. The model is loosely constructed as a generalisation of TLS minus the protocol specifics.

The channel starts out with both ciphers operating in plaintext mode. Over this initially unencrypted channel, a shared secret is agreed, bound to a peer identity, and used to derive keys for the transmit and receive ciphers.

The major channel operations are:

• Key exchange: a shared secret is agreed (e.g. via Ephemeral Diffie-Hellman key exchange)
• Key binding: the shared secret is bound to a peer identity (i.e. to a long-term public key as recorded in an X.509 certificate)
• Key derivation: the transmit and receive cipher keys are derived from the shared secret
• Key confirmation: the peer demonstrates possession of the identity-bound shared secret
• Identity validation: the long-term public key representing the peer identity is validated as being trusted and as matching the required identity (e.g. a TLS host name)

The channel maintains the following security properties:

• "keyed": a boolean flag indicating that the channel contains key material derived from the shared secret
• "bound": a certificate reference representing the peer identity to which the shared secret has been bound
• "confirmed": a certificate reference representing the peer identity that has demonstrated possession of the identity-bound shared secret
• "established": a certificate reference representing the peer identity that has demonstrated possession of the identity-bound shared secret and has been verified as valid

The peer identities are stored as references to X.509 certificates. The secure channel conceptual model is agnostic about how peer identities may be represented, but X.509 certificates are most convenient for use within iPXE. Validation of the certificate chain is outside the scope of the secure channel and must be performed separately.

When the channel has a "confirmed" certificate reference and that certificate has separately been marked as valid, the secure channel may become established and may subsequently be used to transmit and receive application data.

The channel is a passive entity: it does not itself initiate any messages. All communication is driven by the consumer (such as the TLS protocol). The set of operations described above that are used to establish a secure channel must be performed by the consumer according to its protocol definition.

The order of these operations may vary based upon both the protocol definition and the options negotiated at runtime with the peer. The secure channel abstraction is responsible for maintaining the listed security properties and determining whether or not the required security conditions have been met, regardless of the order in which operations are performed by the consumer.

Definition in file channel.c.

Macro Definition Documentation

ENOTTY_TRANSPORT

#define ENOTTY_TRANSPORT   __einfo_error ( EINFO_ENOTTY_TRANSPORT )

Definition at line 114 of file channel.c.

Referenced by channel_key_transport().

EINFO_ENOTTY_TRANSPORT

#define EINFO_ENOTTY_TRANSPORT   __einfo_uniqify ( EINFO_ENOTTY, 0x01, "Untransportable key" )

Definition at line 115 of file channel.c.

#define EINFO_ENOTTY_TRANSPORT \
        __einfo_uniqify ( EINFO_ENOTTY, 0x01, "Untransportable key" )

EPERM_NOT_CONFIDENTIAL

#define EPERM_NOT_CONFIDENTIAL   __einfo_error ( EINFO_EPERM_NOT_CONFIDENTIAL )

Definition at line 117 of file channel.c.

Referenced by channel_confirm(), channel_establish(), and channel_set_cipher().

EINFO_EPERM_NOT_CONFIDENTIAL

#define EINFO_EPERM_NOT_CONFIDENTIAL   __einfo_uniqify ( EINFO_EPERM, 0x01, "Not confidential" )

Definition at line 118 of file channel.c.

#define EINFO_EPERM_NOT_CONFIDENTIAL \
        __einfo_uniqify ( EINFO_EPERM, 0x01, "Not confidential" )

EPERM_NOT_VALID

#define EPERM_NOT_VALID   __einfo_error ( EINFO_EPERM_NOT_VALID )

Definition at line 120 of file channel.c.

Referenced by channel_establish().

EINFO_EPERM_NOT_VALID

#define EINFO_EPERM_NOT_VALID   __einfo_uniqify ( EINFO_EPERM, 0x02, "Peer certificate not valid" )

Definition at line 121 of file channel.c.

#define EINFO_EPERM_NOT_VALID \
        __einfo_uniqify ( EINFO_EPERM, 0x02, "Peer certificate not valid" )

EPROTO_NOT_KEYED

#define EPROTO_NOT_KEYED   __einfo_error ( EINFO_EPROTO_NOT_KEYED )

Definition at line 123 of file channel.c.

Referenced by channel_bind(), and channel_set_cipher().

EINFO_EPROTO_NOT_KEYED

#define EINFO_EPROTO_NOT_KEYED   __einfo_uniqify ( EINFO_EPROTO, 0x01, "No shared key material" )

Definition at line 124 of file channel.c.

#define EINFO_EPROTO_NOT_KEYED \
        __einfo_uniqify ( EINFO_EPROTO, 0x01, "No shared key material" )

EPROTO_NOT_BOUND

#define EPROTO_NOT_BOUND   __einfo_error ( EINFO_EPROTO_NOT_BOUND )

Definition at line 126 of file channel.c.

Referenced by channel_confirm(), channel_load(), and channel_save().

EINFO_EPROTO_NOT_BOUND

#define EINFO_EPROTO_NOT_BOUND   __einfo_uniqify ( EINFO_EPROTO, 0x02, "No bound peer identity" )

Definition at line 127 of file channel.c.

#define EINFO_EPROTO_NOT_BOUND \
        __einfo_uniqify ( EINFO_EPROTO, 0x02, "No bound peer identity" )

EPROTO_NOT_CONFIRMED

#define EPROTO_NOT_CONFIRMED   __einfo_error ( EINFO_EPROTO_NOT_CONFIRMED )

Definition at line 129 of file channel.c.

Referenced by channel_establish().

EINFO_EPROTO_NOT_CONFIRMED

#define EINFO_EPROTO_NOT_CONFIRMED   __einfo_uniqify ( EINFO_EPROTO, 0x03, "No confirmed peer identity" )

Definition at line 130 of file channel.c.

#define EINFO_EPROTO_NOT_CONFIRMED \
        __einfo_uniqify ( EINFO_EPROTO, 0x03, "No confirmed peer identity" )

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

channel_unbind()

void channel_unbind ( struct secure_channel * channel )

static

Clear bound peer identity.

Parameters

channel

Secure channel

Definition at line 545 of file channel.c.

                                                              {
 
        /* Key confirmation is defined only for the currently bound
         * identity, and so any existing confirmed peer identity must
         * be cleared.
         */
        channel_unconfirm ( channel );
 
        /* Drop and clear reference */
        x509_put ( channel->props.bound );
        channel->props.bound = NULL;
}

References channel, channel_unconfirm(), NULL, and x509_put().

Referenced by channel_bind(), channel_key(), and channel_unkey().

channel_unconfirm()

void channel_unconfirm ( struct secure_channel * channel )

static

Clear confirmed peer identity.

Parameters

channel

Secure channel

Definition at line 867 of file channel.c.

                                                                 {
 
        /* Establishment is defined only for the currently confirmed
         * identity, and so any existing established identity must be
         * cleared.
         */
        channel_unestablish ( channel );
 
        /* Drop and clear reference */
        x509_put ( channel->props.confirmed );
        channel->props.confirmed = NULL;
}

References channel, channel_unestablish(), NULL, and x509_put().

Referenced by channel_confirm(), and channel_unbind().

channel_unestablish()

void channel_unestablish ( struct secure_channel * channel )

static

Clear established peer identity.

Parameters

channel

Secure channel

Definition at line 971 of file channel.c.

                                                                   {
 
        /* Drop and clear reference */
        x509_put ( channel->props.established );
        channel->props.established = NULL;
}

References channel, NULL, and x509_put().

Referenced by channel_establish(), and channel_unconfirm().

channel_ephemeral_init()

int channel_ephemeral_init ( struct secure_channel * channel )

static

Initialise ephemeral master secret.

Parameters

channel

Secure channel

Return values

rc	Return status code

Definition at line 164 of file channel.c.

                                                                     {
        struct digest_algorithm *digest = &channel_ephemeral_algorithm;
        static const char salt[16] = "channel master";
        int rc;
 
        /* Generate random bits with no additional input and without
         * prediction resistance
         */
        if ( ( rc = rbg_generate ( NULL, 0, 0, channel->ephemeral,
                                   sizeof ( channel->ephemeral ) ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not generate random data: "
                       "%s\n", channel, strerror ( rc ) );
                return rc;
        }
 
        /* Generate ephemeral master secret */
        hkdf_extract ( digest, salt, sizeof ( salt ), channel->ephemeral,
                       sizeof ( channel->ephemeral ), channel->ephemeral );
 
        return 0;
}

References channel, channel_ephemeral_algorithm, DBGC, hkdf_extract(), NULL, rbg_generate(), rc, and strerror().

Referenced by channel_open().

channel_ephemeral()

void channel_ephemeral	(	struct secure_channel *	channel,
		const void *	info,
		size_t	info_len,
		void *	out,
		size_t	len )

Generate ephemeral secret.

Parameters

channel	Secure channel
info	Additional information
info_len	Length of additional information
out	Ephemeral secret to fill in
len	Length of ephemeral secret

Definition at line 195 of file channel.c.

                                                                  {
        struct digest_algorithm *digest = &channel_ephemeral_algorithm;
 
        /* Additional info should always be provided */
        assert ( info != NULL );
        assert ( info_len > 0 );
 
        /* Generate from ephemeral master secret and additional information */
        hkdf_expand ( digest, channel->ephemeral, info, info_len, out, len );
}

References assert, channel, channel_ephemeral_algorithm, hkdf_expand(), info, info_len, len, NULL, and out.

Referenced by channel_ephemeral_label(), and tls_send_record().

channel_ephemeral_label()

void channel_ephemeral_label	(	struct secure_channel *	channel,
		const char *	label,
		void *	out,
		size_t	len )

Generate labelled ephemeral secret.

Parameters

channel	Secure channel
label	Additional information string
out	Ephemeral secret to fill in
len	Length of ephemeral secret

Definition at line 215 of file channel.c.

                                                                          {
 
        /* Generate from ephemeral master secret and label */
        channel_ephemeral ( channel, label, strlen ( label ), out, len );
        DBGC2 ( channel, "CHANNEL %p ephemeral \"%s\":\n", channel, label );
        DBGC2_HDA ( channel, 0, out, len );
}

References channel, channel_ephemeral(), DBGC2, DBGC2_HDA, len, out, and strlen().

Referenced by channel_ephemeral_replace(), channel_key_private(), tls_nonce(), and tls_session().

channel_ephemeral_replace()

void channel_ephemeral_replace ( struct secure_channel * channel )

static

Replace ephemeral master secret.

Parameters

channel

Secure channel

Definition at line 229 of file channel.c.

                                                                         {
 
        /* Generate a new ephemeral master key */
        channel_ephemeral_label ( channel, "channel replace",
                                  channel->ephemeral,
                                  sizeof ( channel->ephemeral ) );
}

References channel, and channel_ephemeral_label().

Referenced by channel_close(), and channel_reopen().

channel_unkey()

void channel_unkey

(

struct secure_channel *

channel

)

Clear shared secret.

Parameters

channel

Secure channel

Definition at line 273 of file channel.c.

                                                      {
 
        /* Key binding is defined only for the current shared secret,
         * and so any existing bound peer identity must be cleared.
         */
        channel_unbind ( channel );
 
        /* Clear shared key */
        channel->props.keyed = 0;
 
        /* Reset the key schedule */
        channel->op->reset ( channel );
}

References channel, and channel_unbind().

Referenced by channel_bind_encrypt(), channel_close(), channel_key(), channel_load(), channel_open(), channel_reopen(), and tls_clear_digest().

channel_key_private()

void channel_key_private ( struct secure_channel * channel, struct exchange_algorithm * exchange, void * private )

static

Generate private key.

Parameters

channel	Secure channel
exchange	Key exchange algorithm
private	Private key to fill in

Definition at line 294 of file channel.c.

                                                  {
        size_t privsize = exchange->privsize;
        const char *label;
 
        /* Use exchange algorithm name as additional information */
        label = exchange->name;
 
        /* (Re)generate private key
         *
         * Note that key exchange private keys are always small enough
         * to fit on the stack, even for algorithms such as FFDHE that
         * have large public and shared keys.
         */
        channel_ephemeral_label ( channel, label, private, privsize );
}

References channel, channel_ephemeral_label(), exchange_algorithm::name, and exchange_algorithm::privsize.

Referenced by channel_key(), and channel_key_share().

channel_key_share()

int channel_key_share	(	struct secure_channel *	channel,
		struct exchange_algorithm *	exchange,
		void *	public )

Share public key.

Parameters

channel	Secure channel
exchange	Key exchange algorithm
public	Public key to fill in

Return values

rc	Return status code

Definition at line 320 of file channel.c.

                                                                            {
        size_t privsize = exchange->privsize;
        size_t pubsize = exchange->pubsize;
        uint8_t private[privsize];
        int rc;
 
        /* (Re)generate private key */
        channel_key_private ( channel, exchange, private );
 
        /* Generate public key */
        if ( ( rc = exchange_share ( exchange, private, public ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not share \"%s\": %s\n",
                       channel, exchange->name, strerror ( rc ) );
                goto err_share;
        }
 
        /* Show public key (for debugging) */
        DBGC2 ( channel, "CHANNEL %p sharing \"%s\":\n",
                channel, exchange->name );
        DBGC2_HDA ( channel, 0, public, pubsize );
 
 err_share:
        /* Erase private key */
        memset ( private, 0, sizeof ( private ) );
        return rc;
}

References channel, channel_key_private(), DBGC, DBGC2, DBGC2_HDA, exchange_share(), memset(), exchange_algorithm::name, exchange_algorithm::privsize, exchange_algorithm::pubsize, rc, and strerror().

Referenced by tls_key_share().

channel_key()

int channel_key ( struct secure_channel * channel, struct exchange_algorithm * exchange, const void * partner, void * shared )

static

Generate and apply shared secret.

Parameters

channel	Secure channel
exchange	Key exchange algorithm
partner	Partner public key
shared	Shared secret to fill in

Return values

rc	Return status code

Definition at line 357 of file channel.c.

                                                             {
        size_t sharedsize = exchange->sharedsize;
        size_t privsize = exchange->privsize;
        uint8_t private[privsize];
        int accumulated;
        int rc;
 
        /* (Re)generate private key */
        channel_key_private ( channel, exchange, private );
 
        /* Generate shared secret */
        if ( ( rc = exchange_agree ( exchange, private, partner,
                                     shared ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not agree \"%s\": %s\n",
                       channel, exchange->name, strerror ( rc ) );
                goto err_agree;
        }
 
        /* Show shared secret (for debugging) */
        DBGC2 ( channel, "CHANNEL %p agreed \"%s\":\n",
                channel, exchange->name );
        DBGC2_HDA ( channel, 0, shared, sharedsize );
 
        /* Apply shared secret to key schedule */
        accumulated = 0;
        if ( ( rc = channel->op->apply ( channel, exchange, shared,
                                         &accumulated ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not apply \"%s\": %s\n",
                       channel, exchange->name, strerror ( rc ) );
                goto err_apply;
        }
 
        /* If the accumulation flag was not set, then the ability of
         * the peer to subsequently demonstrate possession of the key
         * material suffices to demonstrate possession of this shared
         * secret, but does not necessarily suffice to demonstrate
         * possession of any previously applied shared secrets.  Any
         * binding of the peer identity is therefore no longer valid.
         */
        if ( ! accumulated )
                channel_unbind ( channel );
 
        /* Channel now possesses a shared secret */
        channel->props.keyed = 1;
        DBGC ( channel, "CHANNEL %p key material obtained via \"%s\"\n",
               channel, exchange->name );
 
 err_apply:
 err_agree:
        /* Clear generated shared secret on any error */
        if ( rc != 0 )
                channel_unkey ( channel );
        /* Erase private key */
        memset ( private, 0, sizeof ( private ) );
        return rc;
}

References channel, channel_key_private(), channel_unbind(), channel_unkey(), DBGC, DBGC2, DBGC2_HDA, exchange_agree(), memset(), exchange_algorithm::name, partner, exchange_algorithm::privsize, rc, exchange_algorithm::sharedsize, and strerror().

Referenced by channel_key_agree(), and channel_key_transport().

channel_key_agree()

int channel_key_agree	(	struct secure_channel *	channel,
		struct exchange_algorithm *	exchange,
		const void *	partner )

Agree shared secret.

Parameters

channel	Secure channel
exchange	Key exchange algorithm
partner	Partner public key

Return values

rc	Return status code

Definition at line 424 of file channel.c.

                                              {
        size_t sharedsize = exchange->sharedsize;
        size_t pubsize = exchange->pubsize;
        void *tmp;
        int rc;
 
        /* Show partner public key (for debugging) */
        DBGC2 ( channel, "CHANNEL %p partner \"%s\":\n",
                channel, exchange->name );
        DBGC2_HDA ( channel, 0, partner, pubsize );
 
        /* Allocate space for shared secret (may be too large for stack) */
        tmp = zalloc ( sharedsize );
        if ( ! tmp ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
 
        /* Generate and apply shared secret */
        if ( ( rc = channel_key ( channel, exchange, partner, tmp ) ) != 0 )
                goto err_key;
 
 err_key:
        /* Erase shared secret */
        zfree ( tmp );
 err_alloc:
        return rc;
}

References channel, channel_key(), DBGC2, DBGC2_HDA, ENOMEM, exchange_algorithm::name, partner, exchange_algorithm::pubsize, rc, exchange_algorithm::sharedsize, tmp, zalloc(), and zfree().

Referenced by tls_key_agree().

channel_key_transport()

int channel_key_transport ( struct secure_channel * channel, struct exchange_algorithm * exchange, void * shared )

static

Transport shared secret.

Parameters

channel	Secure channel
exchange	Key exchange algorithm
shared	Shared secret to fill in

Return values

rc	Return status code

Key transport is modelled as a key exchange algorithm with a public key size of zero: the shared secret is unilaterally generated by the local endpoint and must then be transported to the peer.

Definition at line 467 of file channel.c.

                                                  {
        int rc;
 
        /* Sanity check */
        if ( ! is_key_transport ( exchange ) ) {
                DBGC ( channel, "CHANNEL %p cannot transport \"%s\"\n",
                       channel, exchange->name );
                return -ENOTTY_TRANSPORT;
        }
 
        /* Generate and apply shared secret */
        if ( ( rc = channel_key ( channel, exchange, NULL, shared ) ) != 0 )
                return rc;
 
        return 0;
}

References channel, channel_key(), DBGC, ENOTTY_TRANSPORT, is_key_transport(), exchange_algorithm::name, NULL, and rc.

Referenced by channel_bind_encrypt().

channel_bind()

int channel_bind ( struct secure_channel * channel, struct x509_certificate * identity )

static

Set bound peer identity.

Parameters

channel	Secure channel
identity	Identity to be bound

Return values

rc	Return status code

Definition at line 565 of file channel.c.

                                                              {
 
        /* Clear any existing binding */
        channel_unbind ( channel );
 
        /* Fail if there is no shared secret to be bound */
        if ( ! channel->props.keyed ) {
                DBGC ( channel, "CHANNEL %p cannot bind to empty key\n",
                       channel );
                return -EPROTO_NOT_KEYED;
        }
 
        /* Record bound peer identity */
        channel->props.bound = x509_get ( identity );
        DBGC ( channel, "CHANNEL %p key material bound to \"%s\"\n",
               channel, x509_name ( identity ) );
 
        return 0;
}

References channel, channel_unbind(), DBGC, EPROTO_NOT_KEYED, x509_get(), and x509_name().

Referenced by channel_bind_encrypt(), channel_bind_verify(), and channel_load().

channel_bind_verify()

int channel_bind_verify	(	struct secure_channel *	channel,
		struct x509_certificate *	identity,
		struct pubkey_algorithm *	pubkey,
		struct digest_algorithm *	digest,
		const void *	value,
		const struct asn1_cursor *	signature )

Bind peer identity via ephemeral public key signature verification.

Parameters

channel	Secure channel
identity	Identity to be bound
pubkey	Public-key algorithm
digest	Digest algorithm
value	Digest value (must cover peer's ephemeral public key)
signature	Signature

Return values

rc	Return status code

The peer may delegate authority to the shared secret by signing a digest that covers at least its own ephemeral public key (e.g. the Diffie-Hellman parameters provided in a ServerKeyExchange record) and a challenge nonce (e.g. the TLS client random bytes).

The consumer asserts to the secure channel that the digest covers at least the peer's ephemeral public key and a nonce. The digest may cover arbitrary additional information (e.g. the entire transcript hash as signed by a CertificateVerify record).

This assertion is an unverifiable promise made by the consumer: there is no way for the secure channel itself to determine what is covered by the digest.

Definition at line 611 of file channel.c.

                                                                {
        const struct asn1_cursor *key = &identity->subject.public_key.raw;
        int rc;
 
        /* Verify signature */
        if ( ( rc = pubkey_verify ( pubkey, key, digest, value,
                                    signature ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not verify binding: %s\n",
                       channel, strerror ( rc ) );
                return rc;
        }
 
        /* Bind to the identity that signed the shared secret */
        if ( ( rc = channel_bind ( channel, identity ) ) != 0 )
                return rc;
 
        return 0;
}

References channel, channel_bind(), DBGC, key, pubkey_verify(), x509_subject::public_key, x509_public_key::raw, rc, signature, strerror(), x509_certificate::subject, and value.

Referenced by tls_new_server_key_exchange().

channel_bind_encrypt()

int channel_bind_encrypt	(	struct secure_channel *	channel,
		struct x509_certificate *	identity,
		struct exchange_algorithm *	exchange,
		struct pubkey_algorithm *	pubkey,
		struct asn1_builder *	ciphertext )

Bind peer identity via shared secret encryption.

Parameters

channel	Secure channel
identity	Identity to be bound
exchange	Key exchange algorithm
pubkey	Public-key algorithm
ciphertext	Encrypted shared secret

Return values

rc	Return status code

The local endpoint may delegate authority to the shared secret by encrypting a unilaterally chosen shared secret (e.g. a classic TLS static RSA pre-master secret).

Definition at line 648 of file channel.c.

                                                             {
        const struct asn1_cursor *key = &identity->subject.public_key.raw;
        size_t sharedsize = exchange->sharedsize;
        struct asn1_cursor plaintext;
        void *tmp;
        int rc;
 
        /* Allocate space for shared secret (may be too large for stack) */
        tmp = zalloc ( sharedsize );
        if ( ! tmp ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
        plaintext.data = tmp;
        plaintext.len = sharedsize;
 
        /* Generate unencrypted shared secret */
        if ( ( rc = channel_key_transport ( channel, exchange, tmp ) ) != 0 )
                goto err_transport;
 
        /* Encrypt shared secret */
        if ( ( rc = pubkey_encrypt ( pubkey, key, &plaintext,
                                     ciphertext ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not encrypt \"%s\": %s\n",
                       channel, exchange->name, strerror ( rc ) );
                goto err_encrypt;
        }
 
        /* Bind to the identity that can decrypt the shared secret */
        if ( ( rc = channel_bind ( channel, identity ) ) != 0 )
                goto err_bind;
 
 err_bind:
 err_encrypt:
 err_transport:
        /* Clear the generated shared secret on any error */
        if ( rc != 0 )
                channel_unkey ( channel );
        /* Erase unencrypted shared secret */
        zfree ( tmp );
 err_alloc:
        return rc;
}

References channel, channel_bind(), channel_key_transport(), channel_unkey(), asn1_cursor::data, DBGC, ENOMEM, key, asn1_cursor::len, exchange_algorithm::name, pubkey_encrypt(), x509_subject::public_key, x509_public_key::raw, rc, exchange_algorithm::sharedsize, strerror(), x509_certificate::subject, tmp, zalloc(), and zfree().

Referenced by tls_key_encrypt().

channel_save()

int channel_save	(	struct secure_channel *	channel,
		struct secure_preshared_identity *	psid )

Save a pre-shared key.

Parameters

channel	Secure channel
psid	Pre-shared bound peer identity

Return values

rc	Return status code

Definition at line 738 of file channel.c.

                                                            {
        struct x509_certificate *identity;
        int rc;
 
        /* Clear any existing pre-shared bound peer identity */
        channel_clear_preshared ( psid );
 
        /* Fail if there is no bound peer identity to save */
        identity = channel->props.bound;
        if ( ! identity ) {
                DBGC ( channel, "CHANNEL %p cannot create pre-shared key "
                       "for unbound peer\n", channel );
                return -EPROTO_NOT_BOUND;
        }
 
        /* Fail if consumer does not support pre-shared keys */
        if ( ! channel->op->save ) {
                DBGC ( channel, "CHANNEL %p does not support pre-shared "
                       "keys\n", channel );
                return -ENOTSUP;
        }
 
        /* Save pre-shared key */
        if ( ( rc = channel->op->save ( channel, psid ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not save pre-shared "
                       "key: %s\n", channel, strerror ( rc ) );
                return rc;
        }
 
        /* Record pre-shared bound peer identity */
        psid->bound = x509_get ( identity );
        DBGC ( channel, "CHANNEL %p key material saved for \"%s\"\n",
               channel, x509_name ( identity ) );
 
        return 0;
}

References secure_preshared_identity::bound, channel, channel_clear_preshared(), DBGC, ENOTSUP, EPROTO_NOT_BOUND, rc, strerror(), x509_get(), and x509_name().

Referenced by tls_save().

channel_load()

int channel_load	(	struct secure_channel *	channel,
		struct secure_preshared_identity *	psid )

Load a pre-shared key.

Parameters

channel	Secure channel
psid	Pre-shared bound peer identity

Return values

rc	Return status code

Definition at line 783 of file channel.c.

                                                            {
        struct x509_certificate *identity;
        int rc;
 
        /* Clear any existing shared secret */
        channel_unkey ( channel );
 
        /* Fail if there is no bound peer identity to resume */
        identity = psid->bound;
        if ( ! identity ) {
                DBGC ( channel, "CHANNEL %p cannot resume from empty "
                       "pre-shared key\n", channel );
                rc = -EPROTO_NOT_BOUND;
                goto err_empty;
        }
 
        /* Fail if consumer does not support pre-shared keys */
        if ( ! channel->op->load ) {
                DBGC ( channel, "CHANNEL %p does not support pre-shared "
                       "keys\n", channel );
                rc = -ENOTSUP;
                goto err_unsupported;
        }
 
        /* Load pre-shared key */
        if ( ( rc = channel->op->load ( channel, psid ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not load pre-shared key: "
                       "%s\n", channel, strerror ( rc ) );
                goto err_load;
        }
 
        /* Channel now possesses a shared secret */
        channel->props.keyed = 1;
        DBGC ( channel, "CHANNEL %p key material obtained from pre-shared "
               "key\n", channel );
 
        /* Bind to the identity that was bound to the pre-shared key */
        if ( ( rc = channel_bind ( channel, identity ) ) != 0 )
                goto err_bind;
 
        return 0;
 
 err_bind:
 err_load:
 err_unsupported:
 err_empty:
        channel_unkey ( channel );
        return rc;
}

References secure_preshared_identity::bound, channel, channel_bind(), channel_unkey(), DBGC, ENOTSUP, EPROTO_NOT_BOUND, rc, and strerror().

Referenced by tls_resume().

channel_confirm()

int channel_confirm	(	struct secure_channel *	channel,
		const void *	auth,
		size_t	len )

Confirm peer identity.

Parameters

channel	Secure channel
auth	Authenticator value
len	Length of authenticator value

Return values

rc	Return status code

The consumer asserts to the secure channel that the authenticator value was received after the receive pipe was transitioned to a cipher capable of providing confidentiality.

This assertion is an unverifiable promise made by the consumer: there is no way for the secure channel itself to determine when the authenticator value was received.

Definition at line 896 of file channel.c.

                                                     {
        struct x509_certificate *identity;
        int rc;
 
        /* Clear any existing confirmed peer identity */
        channel_unconfirm ( channel );
 
        /* Fail if there is no bound peer identity to authenticate */
        identity = channel->props.bound;
        if ( ! identity ) {
                DBGC ( channel, "CHANNEL %p cannot authenticate unbound "
                       "peer\n", channel );
                return -EPROTO_NOT_BOUND;
        }
 
        /* Sanity check: binding is not possible without keying */
        assert ( channel->props.keyed );
 
        /* Require key confirmation over a confidential channel */
        if ( ! channel->rx.cipher->confidential ) {
                DBGC ( channel, "CHANNEL %p cannot confirm key with a "
                       "non-confidential cipher\n", channel );
                return -EPERM_NOT_CONFIDENTIAL;
        }
 
        /* Verify authentication data */
        if ( ( rc = channel->op->verify ( channel, auth, len ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p failed to authenticate: %s\n",
                       channel, strerror ( rc ) );
                return rc;
        }
 
        /* Record bound peer identity as confirmed peer identity */
        channel->props.confirmed = x509_get ( identity );
        DBGC ( channel, "CHANNEL %p key material confirmed for \"%s\"\n",
               channel, x509_name ( identity ) );
 
        return 0;
}

References assert, channel, channel_unconfirm(), DBGC, EPERM_NOT_CONFIDENTIAL, EPROTO_NOT_BOUND, len, rc, strerror(), x509_get(), and x509_name().

Referenced by tls_new_finished().

channel_establish()

int channel_establish	(	struct secure_channel *	channel,
		const char *	name,
		struct x509_root *	root )

Establish channel as trusted for application data.

Parameters

channel	Secure channel
name	Required peer identity name
root	Root certificate list, or NULL to use default

Return values

rc	Return status code

Definition at line 986 of file channel.c.

                                                 {
        struct x509_certificate *identity;
        int rc;
 
        /* Clear any existing established peer identity */
        channel_unestablish ( channel );
 
        /* Fail if there is no confirmed peer identity to establish */
        identity = channel->props.confirmed;
        if ( ! identity ) {
                DBGC ( channel, "CHANNEL %p cannot establish unconfirmed "
                       "peer\n", channel );
                return -EPROTO_NOT_CONFIRMED;
        }
 
        /* Sanity check: confirmation is not possible without binding */
        assert ( channel->props.bound == identity );
        assert ( channel->props.keyed );
 
        /* Fail if ciphers are still operating in plaintext mode */
        if ( ! ( channel->tx.cipher->confidential &&
                 channel->rx.cipher->confidential ) ) {
                DBGC ( channel, "CHANNEL %p cannot establish channel with a "
                       "non-confidential cipher\n", channel );
                return -EPERM_NOT_CONFIDENTIAL;
        }
 
        /* Fail if confirmed peer identity name is incorrect */
        if ( ( rc = x509_check_name ( identity, name ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p identity \"%s\" does not match "
                       "\"%s\": %s\n", channel, x509_name ( identity ),
                       name, strerror ( rc ) );
                return rc;
        }
 
        /* Fail if confirmed peer identity has not been validated */
        if ( ! x509_is_valid ( identity, root ) ) {
                DBGC ( channel, "CHANNEL %p identity \"%s\" has not been "
                       "validated\n", channel, x509_name ( identity ) );
                return -EPERM_NOT_VALID;
        }
 
        /* Record confirmed peer identity as established peer identity */
        channel->props.established = x509_get ( identity );
        DBGC ( channel, "CHANNEL %p established for \"%s\"\n",
               channel, x509_name ( identity ) );
 
        return 0;
}

References assert, channel, channel_unestablish(), DBGC, EPERM_NOT_CONFIDENTIAL, EPERM_NOT_VALID, EPROTO_NOT_CONFIRMED, name, rc, root, strerror(), x509_check_name(), x509_get(), x509_is_valid(), and x509_name().

Referenced by tls_establish().

channel_dead_crypt()

void channel_dead_crypt ( struct cipher_algorithm *cipher __unused, void *ctx __unused, const void *src __unused, void * dst, size_t len )

static

Encrypt or decrypt data via dead cipher.

Parameters

cipher	Cipher algorithm
ctx	Context
src	Data to encrypt or decrypt
dst	Buffer for encrypted or decrypted data
len	Length of data

Definition at line 1054 of file channel.c.

                                                         {
        static const uint8_t pattern[] = { 0xde, 0xad, 0xc1, 0xfa };
        uint8_t *bytes = dst;
        unsigned int i;
 
        /* Fill destination with fixed and easily spotted pattern */
        for ( i = 0 ; i < len ; i++ )
                bytes[i] = pattern[ i % sizeof ( pattern ) ];
}

References __unused, bytes, ctx, len, and src.

channel_pipe_name()

const char * channel_pipe_name ( struct secure_channel * channel, struct secure_pipe * pipe )

inlinestatic

Get pipe name (for debugging).

Parameters

channel	Secure channel
pipe	Secure channel pipe

Return values

name

Pipe name

Definition at line 1094 of file channel.c.

                                                                          {
 
        return ( ( pipe == &channel->tx ) ? "TX" :
                 ( pipe == &channel->rx ) ? "RX" : "INVALID" );
}

References channel.

Referenced by channel_set_cipher().

channel_clear_cipher()

void channel_clear_cipher ( struct secure_pipe * pipe )

static

Clear cipher algorithm.

Parameters

pipe	Secure channel pipe

Definition at line 1106 of file channel.c.

                                                              {
 
        /* Zero and free any existing cipher context */
        zfree ( pipe->ctx );
        pipe->ctx = NULL;
 
        /* Default to the dead cipher until set */
        pipe->cipher = &channel_dead_cipher;
}

References channel_dead_cipher, secure_pipe::cipher, secure_pipe::ctx, NULL, and zfree().

Referenced by channel_close(), channel_open(), and channel_set_cipher().

channel_set_cipher()

int channel_set_cipher	(	struct secure_channel *	channel,
		struct secure_pipe *	pipe,
		struct cipher_algorithm *	cipher,
		const void *	key,
		size_t	len )

Set cipher algorithm and key.

Parameters

channel	Secure channel
pipe	Secure channel pipe
cipher	Cipher algorithm
key	Key
len	Length of key

Return values

rc	Return status code

The consumer asserts to the secure channel that the key is ultimately derived from the shared secret that was previously provided to the consumer by the secure channel, i.e. that possession of the cipher key implies possession of the shared secret.

This assertion is an unverifiable promise made by the consumer: we can check that a shared secret exists, but there is no way for the secure channel itself to determine how the cipher key is derived.

Definition at line 1136 of file channel.c.

                                                       {
        int rc;
 
        /* Zero and free any existing cipher context */
        channel_clear_cipher ( pipe );
 
        /* Fail if there is no shared secret from which a key could derive */
        if ( ! channel->props.keyed ) {
                DBGC ( channel, "CHANNEL %p refusing to use definitely "
                       "non-derived shared secret\n", channel );
                rc = -EPROTO_NOT_KEYED;
                goto err_keyed;
        }
 
        /* Refuse to explicitly set a non-confidential cipher */
        if ( ! cipher->confidential ) {
                DBGC ( channel, "CHANNEL %p %s refusing to use "
                       "non-confidential cipher \"%s\"\n", channel,
                       channel_pipe_name ( channel, pipe ), cipher->name );
                rc = -EPERM_NOT_CONFIDENTIAL;
                goto err_confidential;
        }
        pipe->cipher = cipher;
 
        /* Allocate new context */
        pipe->ctx = zalloc ( cipher->ctxsize );
        if ( ! pipe->ctx ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
 
        /* Set cipher key */
        if ( ( rc = cipher_setkey ( cipher, pipe->ctx, key, len ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p %s could not set \"%s\" key: %s\n",
                       channel, channel_pipe_name ( channel, pipe ),
                       cipher->name, strerror ( rc ) );
                goto err_setkey;
        }
 
        DBGC ( channel, "CHANNEL %p %s using \"%s\" with %zd-bit key\n",
               channel, channel_pipe_name ( channel, pipe ),
               cipher->name, ( 8 * len ) );
        return 0;
 
 err_setkey:
 err_alloc:
 err_confidential:
 err_keyed:
        channel_clear_cipher ( pipe );
        return rc;
}

References channel, channel_clear_cipher(), channel_pipe_name(), secure_pipe::cipher, cipher_setkey(), cipher_algorithm::confidential, secure_pipe::ctx, cipher_algorithm::ctxsize, DBGC, ENOMEM, EPERM_NOT_CONFIDENTIAL, EPROTO_NOT_KEYED, key, len, cipher_algorithm::name, rc, strerror(), and zalloc().

Referenced by tls_change_cipher().

channel_open()

int channel_open

(

struct secure_channel *

channel

)

Open secure channel.

Parameters

channel

Secure channel

Return values

rc	Return status code

Definition at line 1205 of file channel.c.

                                                    {
        int rc;
 
        /* Sanity checks */
        assert ( channel != NULL );
        assert ( channel->op != NULL );
        assert ( channel->op->reset != NULL );
        assert ( channel->op->apply != NULL );
        assert ( channel->op->verify != NULL );
 
        /* Clear security properties (which should already be clear) */
        assert ( channel->props.keyed == 0 );
        assert ( channel->props.bound == NULL );
        assert ( channel->props.confirmed == NULL );
        assert ( channel->props.established == NULL );
        channel_unkey ( channel );
        assert ( channel->props.keyed == 0 );
        assert ( channel->props.bound == NULL );
        assert ( channel->props.confirmed == NULL );
        assert ( channel->props.established == NULL );
 
        /* Reset ciphers (which should already have no contexts) */
        assert ( channel->tx.ctx == NULL );
        assert ( channel->rx.ctx == NULL );
        channel_clear_cipher ( &channel->tx );
        channel_clear_cipher ( &channel->rx );
        assert ( channel->tx.ctx == NULL );
        assert ( channel->rx.ctx == NULL );
 
        /* Initialise ephemeral master secret */
        if ( ( rc = channel_ephemeral_init ( channel ) ) != 0 )
                return rc;
 
        /* Enable initial plaintext ciphers */
        channel->tx.cipher = &cipher_null;
        channel->rx.cipher = &cipher_null;
 
        DBGC ( channel, "CHANNEL %p opened\n", channel );
        return 0;
}

References assert, channel, channel_clear_cipher(), channel_ephemeral_init(), channel_unkey(), cipher_null, DBGC, NULL, and rc.

Referenced by add_tls().

channel_reopen()

void channel_reopen

(

struct secure_channel *

channel

)

Reopen secure channel.

Parameters

channel

Secure channel

The channel will be returned to a freshly opened state (including a new ephemeral master secret), but with any existing cipher state retained. All security properties will be cleared.

This allows a new secure channel to be established with either or both of the transmit and receive pipes having already transitioned to a cipher capable of providing confidentiality.

The consumer may choose to reopen a fully established channel while leaving the cipher keys intact (as is done in TLS renegotiation), in which case it may choose to treat the channel as remaining established (to the old peer identity) at least until the point that the cipher keys are next changed (and possibly further, depending upon the protocol design). The secure channel itself does not attempt to model any such choice by the consumer: reopening will clear all security properties including the established peer identity.

Definition at line 1269 of file channel.c.

                                                       {
 
        /* Clear security properties */
        channel_unkey ( channel );
        assert ( channel->props.keyed == 0 );
        assert ( channel->props.bound == NULL );
        assert ( channel->props.confirmed == NULL );
        assert ( channel->props.established == NULL );
 
        /* Replace ephemeral master secret
         *
         * We choose to replace rather than reinitialise the ephemeral
         * master secret so that this function may be used from code
         * paths that cannot allow for failure (such as when closing
         * the channel).
         */
        channel_ephemeral_replace ( channel );
 
        DBGC ( channel, "CHANNEL %p reopened\n", channel );
}

References assert, channel, channel_ephemeral_replace(), channel_unkey(), DBGC, and NULL.

Referenced by tls_restart().

channel_close()

void channel_close

(

struct secure_channel *

channel

)

Close secure channel.

Parameters

channel

Secure channel

All secret values held by the secure channel will be destroyed, including the ephemeral master secret.

This function may safely be called on a channel that has already been closed.

Definition at line 1301 of file channel.c.

                                                      {
 
        /* Clear security properties */
        channel_unkey ( channel );
        assert ( channel->props.keyed == 0 );
        assert ( channel->props.bound == NULL );
        assert ( channel->props.confirmed == NULL );
        assert ( channel->props.established == NULL );
 
        /* Reset ciphers */
        channel_clear_cipher ( &channel->tx );
        channel_clear_cipher ( &channel->rx );
        assert ( channel->tx.ctx == NULL );
        assert ( channel->rx.ctx == NULL );
 
        /* Replace ephemeral master secret
         *
         * We choose to replace rather than zero the ephemeral master
         * secret.  For any channel that has been successfully opened,
         * this ensures that an erroneous reuse of the channel after
         * it has been closed cannot lead to the use of predictable
         * ephemeral secrets (derived from an all-zero value), or to
         * reuse of its previous ephemeral secrets.
         */
        channel_ephemeral_replace ( channel );
 
        DBGC ( channel, "CHANNEL %p closed\n", channel );
}

References assert, channel, channel_clear_cipher(), channel_ephemeral_replace(), channel_unkey(), DBGC, and NULL.

Referenced by add_tls(), and tls_close().

Variable Documentation

channel_dead_cipher

struct cipher_algorithm channel_dead_cipher

Initial value:

                      = {
        .name = "dead",
        .ctxsize = 0,
        .blocksize = 1,
        .alignsize = 1,
        .authsize = 0,
        .confidential = 0,
        .setkey = cipher_null_setkey,
        .setiv = cipher_null_setiv,
        .encrypt = channel_dead_crypt,
        .decrypt = channel_dead_crypt,
        .auth = cipher_null_auth,
}

Dead cipher.

We activate this cipher (rather than the null cipher) upon any cipher-related failure, to guard against code paths that may fail to check for cipher errors.

Definition at line 1073 of file channel.c.

                                            {
        .name = "dead",
        .ctxsize = 0,
        .blocksize = 1,
        .alignsize = 1,
        .authsize = 0,
        .confidential = 0,
        .setkey = cipher_null_setkey,
        .setiv = cipher_null_setiv,
        .encrypt = channel_dead_crypt,
        .decrypt = channel_dead_crypt,
        .auth = cipher_null_auth,
};

Referenced by channel_clear_cipher(), and channel_init().