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

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
 	 */