| #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 void channel_clear_cipher ( struct secure_pipe *pipe ); | |
| 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 */ |