Secure channel operations. More...
#include <channel.h>
Data Fields | |
| void(* | reset )(struct secure_channel *channel) |
| Reset the key schedule. | |
| int(* | apply )(struct secure_channel *channel, struct exchange_algorithm *exchange, const void *shared, int *accumulated) |
| Apply a new shared secret to key schedule. | |
| int(* | save )(struct secure_channel *channel, struct secure_preshared_identity *psid) |
| Save a pre-shared key for future resumption of the key schedule. | |
| int(* | load )(struct secure_channel *channel, struct secure_preshared_identity *psid) |
| Load a pre-shared key and resume the key schedule. | |
| int(* | verify )(struct secure_channel *channel, const void *auth, size_t len) |
| Verify authenticator value. | |
Detailed Description
Field Documentation
◆ reset
| void(* secure_channel_operations::reset) (struct secure_channel *channel) |
Reset the key schedule.
- Parameters
-
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.
◆ apply
| int(* secure_channel_operations::apply) (struct secure_channel *channel, struct exchange_algorithm *exchange, const void *shared, int *accumulated) |
Apply a new shared secret to key schedule.
- Parameters
-
channel Secure channel exchange Key exchange algorithm shared New shared secret accumulated Accumulation flag to fill in
- Return values
-
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.
◆ save
| int(* secure_channel_operations::save) (struct secure_channel *channel, struct secure_preshared_identity *psid) |
Save a pre-shared key for future resumption of the key schedule.
- Parameters
-
channel Secure channel psid Pre-shared bound peer identity
- Return values
-
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.
◆ load
| int(* secure_channel_operations::load) (struct secure_channel *channel, struct secure_preshared_identity *psid) |
Load a pre-shared key and resume the key schedule.
- Parameters
-
channel Secure channel psid Pre-shared bound peer identity
- Return values
-
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.
◆ verify
| int(* secure_channel_operations::verify) (struct secure_channel *channel, const void *auth, size_t len) |
Verify authenticator value.
- Return values
-
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.
The documentation for this struct was generated from the following file:
- include/ipxe/channel.h
Generated by
1.16.1