channel.h

Go to the documentation of this file.

#ifndef _IPXE_CHANNEL_H
#define _IPXE_CHANNEL_H
 
/** @file
 *
 * Secure channel abstraction
 *
 */
 
FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
FILE_SECBOOT ( PERMITTED );
 
#include <stdint.h>
#include <ipxe/crypto.h>
#include <ipxe/x509.h>
#include <ipxe/sha256.h>
 
/** Ephemeral master secret digest algorithm */
#define channel_ephemeral_algorithm sha256_algorithm
 
/** Secure channel properties */
struct secure_channel_properties {
        /** Channel contains key material derived from a shared secret */
        int keyed;
        /**
         * Bound peer identity (if any)
         *
         * This is guaranteed to be set only if the "keyed" property
         * is also set.
         */
        struct x509_certificate *bound;
        /**
         * Confirmed peer identity (if any)
         *
         * This is guaranteed to be set only if the "bound" property
         * is also set, and then to have the same value as the "bound"
         * property.
         */
        struct x509_certificate *confirmed;
        /**
         * Established peer identity (if any)
         *
         * This is guaranteed to be set only if the "confirmed"
         * property is also set, and then to have the same value as
         * both the "confirmed" and "bound" properties.
         *
         * If an established peer identity exists, then it is
         * guaranteed that the channel may be used for confidential
         * communication with the peer that was specified at the point
         * that the channel was established as trusted.
         */
        struct x509_certificate *established;
};
 
/** A secure channel transmit or receive pipe */
struct secure_pipe {
        /** Cipher algorithm */
        struct cipher_algorithm *cipher;
        /** Cipher context */
        void *ctx;
};
 
/**
 * A secure channel
 *
 * This is designed to be embedded within a containing structure that
 * represents the consumer, such as a TLS connection.
 *
 * The containing structure must have been initialised to all zeros
 * before use.
 */
struct secure_channel {
        /** Channel operations */
        struct secure_channel_operations *op;
 
        /** Ephemeral master secret */
        uint8_t ephemeral[SHA256_DIGEST_SIZE];
        /** Security properties */
        struct secure_channel_properties props;
 
        /** Transmit pipe */
        struct secure_pipe tx;
        /** Receive pipe */
        struct secure_pipe rx;
};
 
/**
 * A pre-shared bound peer identity
 *
 * This is designed to be embedded within a containing structure that
 * also holds the pre-shared key material, such as a TLS session
 * structure.
 *
 * The containing structure must have been initialised to all zeros
 * before use.
 */
struct secure_preshared_identity {
        /** Bound peer identity */
        struct x509_certificate *bound;
};
 
/** Secure channel operations */
struct secure_channel_operations {
        /**
         * Reset the key schedule
         *
         * @v channel           Secure channel
         *
         * Return the key schedule to a freshly initialised state,
         * with all key material destroyed.
         *
         * The consumer must leave the key schedule in a state that is
         * ready to receive an initial shared secret.
         *
         * This method is used to clean up after errors and when the
         * secure channel is closed.  It may be invoked repeatedly,
         * and may not fail.
         */
        void ( * reset ) ( struct secure_channel *channel );
        /**
         * Apply a new shared secret to key schedule
         *
         * @v channel           Secure channel
         * @v exchange          Key exchange algorithm
         * @v shared            New shared secret
         * @v accumulated       Accumulation flag to fill in
         * @ret rc              Return status code
         *
         * Incorporate a new shared secret into the key schedule to
         * produce the key material required to operate the channel
         * (e.g. to subsequently derive traffic keys).
         *
         * If the resulting key material is cryptographically
         * dependent upon all previously incorporated shared secrets
         * as well as upon the new shared secret (as is the case with
         * the HKDF-based key schedule used in TLS version 1.3), then
         * this method may set the accumulation flag.  If the key
         * material depends solely upon the new shared secret (as is
         * the case with the master secret computation in earlier
         * versions of TLS), then the method must not set the
         * accumulation flag.
         *
         * This method implicitly asserts to the secure channel that
         * the ability of the peer to subsequently demonstrate
         * possession of the resulting key material is sufficient to
         * demonstrate the peer's possession of the new shared secret.
         *
         * Setting the accumulation flag asserts to the secure channel
         * that the ability of the peer to demonstrate possession of
         * the resulting key material is also sufficient to
         * demonstrate the peer's possession of all previously
         * incorporated shared secrets, and therefore that any peer
         * identity that was already bound to the old shared secret
         * remains bound to the new shared secret.
         *
         * Conversely, leaving the accumulation flag unset indicates
         * to the secure channel that the ability of the peer to
         * demonstrate possession of the resulting key material does
         * not necessarily suffice to demonstrate possession of any
         * previously incorporated shared secrets, and therefore that
         * any peer identity that was bound to the old shared secret
         * is not bound to the new shared secret.
         *
         * If this method does not set the accumulation flag, then the
         * secure channel will therefore automatically unbind any
         * stored peer identity that had previously been bound to the
         * old shared secret.
         *
         * If this method returns an error, then the secure channel
         * will be reset to a non-keyed state.
         */
        int ( * apply ) ( struct secure_channel *channel,
                          struct exchange_algorithm *exchange,
                          const void *shared, int *accumulated );
        /**
         * Save a pre-shared key for future resumption of the key schedule
         *
         * @v channel           Secure channel
         * @v psid              Pre-shared bound peer identity
         * @ret rc              Return status code
         *
         * Save key material alongside an already bound peer identity,
         * so that a future operation may resume the key schedule with
         * the peer identity already bound to the key material.
         *
         * This method asserts to the secure channel that the ability
         * of the peer to subsequently demonstrate possession of the
         * future resumed key material is sufficient to demonstrate
         * the peer's possession of the current key material.
         *
         * This method is optional if the consumer does not support
         * resumption from a pre-shared key.
         *
         * If this method returns an error, then any existing
         * pre-shared bound peer identity will be cleared.
         */
        int ( * save ) ( struct secure_channel *channel,
                         struct secure_preshared_identity *psid );
        /**
         * Load a pre-shared key and resume the key schedule
         *
         * @v channel           Secure channel
         * @v psid              Pre-shared bound peer identity
         * @ret rc              Return status code
         *
         * Load key material that was previously saved alongside a
         * bound peer identity.
         *
         * This method asserts to the secure channel that the ability
         * of the peer to subsequently demonstrate possession of the
         * resumed key material is sufficient to demonstrate the
         * peer's possession of the originally saved key material.
         *
         * This method is optional if the consumer does not support
         * resumption from a pre-shared key.
         *
         * If this method returns an error, then the secure channel
         * will be reset to a non-keyed state.
         */
        int ( * load ) ( struct secure_channel *channel,
                         struct secure_preshared_identity *psid );
        /**
         * Verify authenticator value
         *
         * @v channel           Secure channel
         * @v auth              Authenticator value
         * @v len               Length of authenticator value
         * @ret rc              Return status code
         *
         * Verify that the peer has demonstrated possession of the key
         * material (and hence has demonstrated possession of the
         * identity-bound shared secret).
         *
         * This method asserts to the secure channel that the
         * authenticator value is guaranteed to be non-replayable
         * (e.g. by being constructed as a digest that covers a
         * challenge nonce, as with the TLS Finished verification data
         * which covers the client random bytes within the handshake
         * transcript).
         *
         * If this method returns an error, then the secure channel
         * will be left in a non-confirmed state.
         */
        int ( * verify ) ( struct secure_channel *channel,
                           const void *auth, size_t len );
};
 
extern struct cipher_algorithm channel_dead_cipher;
 
/**
 * Initialise secure channel
 *
 * @v channel           Secure channel
 * @v op                Channel operations
 */
static inline void channel_init ( struct secure_channel *channel,
                                  struct secure_channel_operations *op ) {
 
        channel->op = op;
        channel->tx.cipher = &channel_dead_cipher;
        channel->rx.cipher = &channel_dead_cipher;
}
 
/**
 * Check if secure channel has been established
 *
 * @v channel           Secure channel
 * @ret is_established  Channel has been established
 */
static inline __attribute__ (( always_inline )) int
channel_is_established ( struct secure_channel *channel ) {
 
        return ( channel->props.established != NULL );
}
 
/**
 * Clear pre-shared bound peer identity
 *
 * @v psid              Pre-shared identity
 */
static inline __attribute__ (( always_inline )) void
channel_clear_preshared ( struct secure_preshared_identity *psid ) {
 
        x509_put ( psid->bound );
        psid->bound = NULL;
}
 
extern void channel_ephemeral ( struct secure_channel *channel,
                                const void *info, size_t info_len,
                                void *out, size_t len );
extern void channel_ephemeral_label ( struct secure_channel *channel,
                                      const char *label, void *out,
                                      size_t len );
extern void channel_unkey ( struct secure_channel *channel );
extern int channel_key_share ( struct secure_channel *channel,
                               struct exchange_algorithm *exchange,
                               void *public );
extern int channel_key_agree ( struct secure_channel *channel,
                               struct exchange_algorithm *exchange,
                               const void *partner );
extern 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 );
extern int channel_bind_encrypt ( struct secure_channel *channel,
                                  struct x509_certificate *identity,
                                  struct exchange_algorithm *exchange,
                                  struct pubkey_algorithm *pubkey,
                                  struct asn1_builder *ciphertext );
extern int channel_save ( struct secure_channel *channel,
                          struct secure_preshared_identity *psid );
extern int channel_load ( struct secure_channel *channel,
                          struct secure_preshared_identity *psid );
extern int channel_confirm ( struct secure_channel *channel,
                             const void *auth, size_t len );
extern int channel_establish ( struct secure_channel *channel,
                               const char *name, struct x509_root *root );
extern int channel_set_cipher ( struct secure_channel *channel,
                                struct secure_pipe *pipe,
                                struct cipher_algorithm *cipher,
                                const void *key, size_t len );
extern int channel_open ( struct secure_channel *channel );
extern void channel_reopen ( struct secure_channel *channel );
extern void channel_close ( struct secure_channel *channel );
 
#endif /* _IPXE_CHANNEL_H */