src/crypto/channel.c

/*
 * Copyright (C) 2026 Michael Brown <mbrown@fensystems.co.uk>.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA.
 *
 * You can also choose to distribute this program under the terms of
 * the Unmodified Binary Distribution Licence (as given in the file
 * COPYING.UBDL), provided that you have satisfied its requirements.
 */

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
FILE_SECBOOT ( PERMITTED );

#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>

/** @file
 *
 * 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.
 *
 */

/* Disambiguate the various error causes */
#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" )

static void channel_unbind ( struct secure_channel *channel );
static void channel_unconfirm ( struct secure_channel *channel );
static void channel_unestablish ( struct secure_channel *channel );

/*****************************************************************************
 *
 * Ephemeral secrets
 *
 *****************************************************************************
 *
 * The channel maintains a single ephemeral master secret that can be
 * used to derive an arbitrary number of other ephemeral secrets
 * (e.g. for Diffie-Hellman key exchange).
 *
 * The use of a single ephemeral master secret avoids the need for key
 * exchange mechanisms to retain individual copies of their ephemeral
 * private keys, since those private keys can always be regenerated on
 * demand.
 *
 * The ephemeral secret mechanism may also be used to derive other
 * temporary secrets that may be required by the consumer (e.g. TLS
 * client random data, or block cipher initialisation vectors).
 *
 */

/**
 * Initialise ephemeral master secret
 *
 * @v channel		Secure channel
 * @ret rc		Return status code
 */
static int channel_ephemeral_init ( struct secure_channel *channel ) {
	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;
}

/**
 * Generate ephemeral secret
 *
 * @v channel		Secure channel
 * @v info		Additional information
 * @v info_len		Length of additional information
 * @v out		Ephemeral secret to fill in
 * @v len		Length of ephemeral secret
 */
void channel_ephemeral ( struct secure_channel *channel, const void *info,
			 size_t info_len, void *out, size_t len ) {
	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 );
}

/**
 * Generate labelled ephemeral secret
 *
 * @v channel		Secure channel
 * @v label		Additional information string
 * @v out		Ephemeral secret to fill in
 * @v len		Length of ephemeral secret
 */
void channel_ephemeral_label ( struct secure_channel *channel,
			       const char *label, void *out, size_t len ) {

	/* 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 );
}

/**
 * Replace ephemeral master secret
 *
 * @v channel		Secure channel
 */
static void channel_ephemeral_replace ( struct secure_channel *channel ) {

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

/*****************************************************************************
 *
 * Key exchange
 *
 *****************************************************************************
 *
 * Key exchange (or key transport) is used over the as-yet unencrypted
 * channel to obtain a shared secret (e.g. a TLS pre-master secret
 * obtained using ECDHE).  The shared secret is then used to derive
 * the channel key material (e.g. a TLS master secret).
 *
 * The channel is responsible for generating the ephemeral private
 * keys (and the corresponding public keys), and for handling the
 * underlying mechanics of the key exchange algorithm to obtain a
 * shared secret.
 *
 * The consumer is responsible for incorporating the resulting shared
 * secret into its key schedule to produce the key material required
 * by the consumer to operate the channel (e.g. to derive traffic
 * keys).
 *
 * The channel does not itself dictate how the key material is
 * produced, since the key schedule is necessarily defined by the
 * protocol in use (e.g. TLS).
 *
 * Key exchange alone provides no authentication of the peer.  Key
 * binding (see below) must be used to bind the shared secret to a
 * peer identity.
 *
 */

/**
 * Clear shared secret
 *
 * @v channel		Secure channel
 */
void channel_unkey ( struct secure_channel *channel ) {

	/* 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 );
}

/**
 * Generate private key
 *
 * @v channel		Secure channel
 * @v exchange		Key exchange algorithm
 * @v private		Private key to fill in
 */
static void channel_key_private ( struct secure_channel *channel,
				  struct exchange_algorithm *exchange,
				  void *private ) {
	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 );
}

/**
 * Share public key
 *
 * @v channel		Secure channel
 * @v exchange		Key exchange algorithm
 * @v public		Public key to fill in
 * @ret rc		Return status code
 */
int channel_key_share ( struct secure_channel *channel,
			struct exchange_algorithm *exchange, void *public ) {
	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;
}

/**
 * Generate and apply shared secret
 *
 * @v channel		Secure channel
 * @v exchange		Key exchange algorithm
 * @v partner		Partner public key
 * @v shared		Shared secret to fill in
 * @ret rc		Return status code
 */
static int channel_key ( struct secure_channel *channel,
			 struct exchange_algorithm *exchange,
			 const void *partner, void *shared ) {
	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;
}

/**
 * Agree shared secret
 *
 * @v channel		Secure channel
 * @v exchange		Key exchange algorithm
 * @v partner		Partner public key
 * @ret rc		Return status code
 */
int channel_key_agree ( struct secure_channel *channel,
			struct exchange_algorithm *exchange,
			const void *partner ) {
	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;
}

/**
 * Transport shared secret
 *
 * @v channel		Secure channel
 * @v exchange		Key exchange algorithm
 * @v shared		Shared secret to fill in
 * @ret 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.
 */
static int channel_key_transport ( struct secure_channel *channel,
				   struct exchange_algorithm *exchange,
				   void *shared ) {
	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;
}

/*****************************************************************************
 *
 * Key binding
 *
 *****************************************************************************
 *
 * The shared secret that results from key exchange must be bound to a
 * peer identity.  This binding represents a delegation of authority
 * from the peer's long-term authentication key (e.g. the RSA private
 * key corresponding to its X.509 certificate) to the shared secret
 * for the purpose of authenticating the channel by subsequently
 * confirming possession of the shared secret.
 *
 * There are two distinct mechanisms through which this delegation may
 * take place:
 *
 *   - If the shared secret is obtained using key exchange, then the
 *     peer may delegate authority to the shared secret by using its
 *     long-term authentication key to sign 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
 *     signature over its public ephemeral key represents a choice by
 *     the peer to allow possession of the corresponding ephemeral
 *     private key to be used to demonstrate authenticity of the
 *     channel.  The local endpoint trusts the peer's long-term
 *     identity to make this class of choice, and verifies the
 *     signature to authenticate that the peer's long-term identity
 *     made this choice.  The possession of the ephemeral private key
 *     is subsequently demonstrated by key confirmation, which
 *     demonstrates possession of the shared secret (and hence of the
 *     ephemeral private key used to obtain the shared secret).
 *
 *   - If the shared secret is obtained using key transport, then the
 *     local endpoint may delegate authority to the shared secret by
 *     encrypting the unilaterally chosen shared secret using the
 *     peer's long-term authentication key.  The encryption represents
 *     a choice by the local endpoint to allow possession of the
 *     shared secret (as subsequently demonstrated by key
 *     confirmation) to be used as evidence of possession of the
 *     peer's long-term authentication key.
 *
 * In both cases, the end result is the same: the shared secret
 * (whether exchanged or transported) may be relied upon to
 * authenticate the channel as being connected to the peer.
 *
 * The shared secret may be bound to an identity that has not yet been
 * validated.  The consumer is responsible for separately performing
 * validation of the identity (e.g. validation of the full X.509
 * certificate chain, including OCSP checks) at some point before
 * relying upon the channel to protect application data.
 *
 */

/**
 * Clear bound peer identity
 *
 * @v channel		Secure channel
 */
static void channel_unbind ( struct secure_channel *channel ) {

	/* 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;
}

/**
 * Set bound peer identity
 *
 * @v channel		Secure channel
 * @v identity		Identity to be bound
 * @ret rc		Return status code
 */
static int channel_bind ( struct secure_channel *channel,
			  struct x509_certificate *identity ) {

	/* 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;
}

/**
 * Bind peer identity via ephemeral public key signature verification
 *
 * @v channel		Secure channel
 * @v identity		Identity to be bound
 * @v pubkey		Public-key algorithm
 * @v digest		Digest algorithm
 * @v value		Digest value (must cover peer's ephemeral public key)
 * @v signature		Signature
 * @ret 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.
 */
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 ) {
	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;
}

/**
 * Bind peer identity via shared secret encryption
 *
 * @v channel		Secure channel
 * @v identity		Identity to be bound
 * @v exchange		Key exchange algorithm
 * @v pubkey		Public-key algorithm
 * @v ciphertext	Encrypted shared secret
 * @ret 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).
 */
int channel_bind_encrypt ( struct secure_channel *channel,
			   struct x509_certificate *identity,
			   struct exchange_algorithm *exchange,
			   struct pubkey_algorithm *pubkey,
			   struct asn1_builder *ciphertext ) {
	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;
}

/*****************************************************************************
 *
 * Pre-shared keys
 *
 *****************************************************************************
 *
 * Once a shared secret has been bound to a peer identity, it may be
 * saved as a pre-shared key alongside the bound peer identity.  A
 * future secure channel may resume the key schedule from this
 * pre-shared and already bound key.
 *
 * The consumer is responsible for ensuring that the ability to
 * demonstrate possession of the key material after resumption implies
 * possession of the key material that was previously saved (and so
 * implies possession of the original shared secret).
 *
 * The consumer may choose to save a pre-shared key at any point after
 * the peer identity has been bound.  A successful resumption will
 * restore the previously bound peer identity but will clear the
 * confirmed and established peer identities.
 *
 * Key confirmation to demonstrate possession of the key material is
 * still required after resuming a secure channel from a pre-shared
 * key.
 *
 * The establishment check is also still required after resuming a
 * secure channel from a pre-shared key.  It is technically possible
 * (though unlikely in practice) for the establishment check to use a
 * new required peer identity name or root of trust.
 *
 * Support for pre-shared keys is optional.  The consumer may choose
 * not to support the use of pre-shared keys.
 *
 */

/**
 * Save a pre-shared key
 *
 * @v channel		Secure channel
 * @v psid		Pre-shared bound peer identity
 * @ret rc		Return status code
 */
int channel_save ( struct secure_channel *channel,
		   struct secure_preshared_identity *psid ) {
	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;
}

/**
 * Load a pre-shared key
 *
 * @v channel		Secure channel
 * @v psid		Pre-shared bound peer identity
 * @ret rc		Return status code
 */
int channel_load ( struct secure_channel *channel,
		   struct secure_preshared_identity *psid ) {
	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;
}

/*****************************************************************************
 *
 * Key confirmation
 *
 *****************************************************************************
 *
 * The peer must authenticate the channel by demonstrating its
 * possession of the current key material that was derived from the
 * identity-bound shared secret in accordance with the key schedule.
 *
 * The peer may demonstrate its possession of the key material by
 * constructing and sending an authenticator value that can be
 * successfully verified by the local endpoint using the same key
 * material.
 *
 * The receive pipe must already have transitioned to a cipher capable
 * of providing confidentiality before the authenticator value is
 * received, so that the authentication of the channel meaningfully
 * endures beyond the receipt of the authenticator value itself.
 *
 * The key may be confirmed for an identity that has not yet been
 * validated.  The consumer is responsible for separately performing
 * validation of the identity (e.g. validation of the full X.509
 * certificate chain, including OCSP checks) at some point before
 * relying upon the channel to protect application data.
 *
 */

/**
 * Clear confirmed peer identity
 *
 * @v channel		Secure channel
 */
static void channel_unconfirm ( struct secure_channel *channel ) {

	/* 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;
}

/**
 * Confirm peer identity
 *
 * @v channel		Secure channel
 * @v auth		Authenticator value
 * @v len		Length of authenticator value
 * @ret 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.
 */
int channel_confirm ( struct secure_channel *channel,
		      const void *auth, size_t len ) {
	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;
}

/*****************************************************************************
 *
 * Establishment
 *
 *****************************************************************************
 *
 * The channel may be used for application data once the peer identity
 * has been validated, the peer has authenticated the channel via key
 * confirmation, and both pipes have been transitioned to ciphers
 * capable of providing confidentiality.
 *
 * Validating the peer identity (i.e. validating its X.509 certificate
 * chain) is outside the scope of the secure channel and must be
 * performed separately by the consumer.  Validation is an
 * asynchronous operation that will typically require network
 * communication (e.g. to perform OCSP checks).
 *
 * Once the consumer knows that validation has completed and that the
 * channel has been authenticated, it may mark the channel as
 * established.
 *
 * Establishment performs a one-off check that the confirmed peer
 * identity exists, matches the name required by the consumer, and is
 * valid at this point in time.  Future changes to the validity of the
 * peer identity (e.g. due to certificate expiry) will not cause the
 * channel to cease to be established.
 *
 */

/**
 * Clear established peer identity
 *
 * @v channel		Secure channel
 */
static void channel_unestablish ( struct secure_channel *channel ) {

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

/**
 * Establish channel as trusted for application data
 *
 * @v channel		Secure channel
 * @v name		Required peer identity name
 * @v root		Root certificate list, or NULL to use default
 * @ret rc		Return status code
 */
int channel_establish ( struct secure_channel *channel, const char *name,
			struct x509_root *root ) {
	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;
}

/*****************************************************************************
 *
 * Cipher operation
 *
 *****************************************************************************
 *
 */

/**
 * Encrypt or decrypt data via dead cipher
 *
 * @v cipher		Cipher algorithm
 * @v ctx		Context
 * @v src		Data to encrypt or decrypt
 * @v dst		Buffer for encrypted or decrypted data
 * @v len		Length of data
 */
static void channel_dead_crypt ( struct cipher_algorithm *cipher __unused,
				 void *ctx __unused, const void *src __unused,
				 void *dst, size_t len ) {
	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 ) ];
}

/**
 * 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.
 */
struct cipher_algorithm channel_dead_cipher = {
	.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,
};

/**
 * Get pipe name (for debugging)
 *
 * @v channel		Secure channel
 * @v pipe		Secure channel pipe
 * @ret name		Pipe name
 */
static inline const char * channel_pipe_name ( struct secure_channel *channel,
					       struct secure_pipe *pipe ) {

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

/**
 * Clear cipher algorithm
 *
 * @v pipe		Secure channel pipe
 */
void channel_clear_cipher ( struct secure_pipe *pipe ) {

	/* 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;
}

/**
 * Set cipher algorithm and key
 *
 * @v channel		Secure channel
 * @v pipe		Secure channel pipe
 * @v cipher		Cipher algorithm
 * @v key		Key
 * @v len		Length of key
 * @ret 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.
 */
int channel_set_cipher ( struct secure_channel *channel,
			 struct secure_pipe *pipe,
			 struct cipher_algorithm *cipher,
			 const void *key, size_t len ) {
	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;
}

/*****************************************************************************
 *
 * Life cycle management
 *
 *****************************************************************************
 *
 */

/**
 * Open secure channel
 *
 * @v channel		Secure channel
 * @ret rc		Return status code
 */
int channel_open ( struct secure_channel *channel ) {
	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;
}

/**
 * Reopen secure channel
 *
 * @v 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.
 */
void channel_reopen ( struct secure_channel *channel ) {

	/* 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 );
}

/**
 * Close secure channel
 *
 * @v 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.
 */
void channel_close ( struct secure_channel *channel ) {

	/* 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 );
}