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

diff --git a/src/libstrongswan/crypto/key_exchange.h b/src/libstrongswan/crypto/key_exchange.h
index 6d5ebd13201be549c78ab5d72e948f6dbb5b4dd9..8ae2ee4092fe10644573ec60d1020568bce4999e 100644 (file)
--- a/src/libstrongswan/crypto/key_exchange.h
+++ b/src/libstrongswan/crypto/key_exchange.h
@@ -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
         */