sharpetronics/strongswan
1
0
Fork 0
mirror of https://github.com/strongswan/strongswan.git synced 2025-10-03 00:00:24 -04:00
Code Issues Projects Releases Wiki Activity

key-exchange: Document how the interface is used with KEMs

Browse Source
This commit is contained in:
Tobias Brunner 2024-10-07 11:56:40 +02:00
parent 40676786aa
commit 09636199e6
1 changed files with 28 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
src/libstrongswan/crypto/key_exchange.h
View File

@ -98,7 +98,27 @@ extern enum_name_t *key_exchange_method_names;
extern enum_name_t *key_exchange_method_names_short;
/**
* Implementation of a key exchange algorithms (e.g. Diffie-Hellman).
* Implementation of a key exchange algorithm or a key encapsulation mechanism
* (KEM).
*
* For KEMs, implementations can assume the following order of method calls
* on initiator and responder, which allows them to determine their role:
@verbatim
Initiator Responder
get_public_key()
set_public_key()
get_public_key()
set_public_key()
get_shared_secret()
get_shared_secret()
@endverbatim
* Initiators are expected to return the public key of a randomly generated
* key pair from get_public_key(). Responders will receive that via
* set_public_key() and encapsulate a randomly generated shared secret with it.
* The resulting ciphertext is expected to be returned by the responder from
* get_public_key(). It gets passed to the initiator via set_public_key(), which
* decapsulates it using its private key to get the shared secret generated by
* the responder.
*/
struct key_exchange_t {
@ -114,9 +134,13 @@ struct key_exchange_t {
/**
* Sets the public key received from the peer.
*
* See the interface description on how this method is used with KEMs.
*
* @note This operation should be relatively quick. Costly public key
* validation operations or key derivation should be implemented in
* get_shared_secret().
* get_shared_secret(). For KEMs that's not possible, however, it's also
* not as important because they usually won't be used as initial key
* exchange method during IKE_SA_INIT.
*
* @param value public key of peer
* @return TRUE if other public key verified and set
@ -127,6 +151,8 @@ struct key_exchange_t {
/**
* Gets the own public key to transmit.
*
* See the interface description on how this method is used with KEMs.
*
* @param value public key (allocated)
* @return TRUE if public key retrieved
*/