Added a note about DH/keymat lifecycle for custom implementations
[strongswan.git] / src / libcharon / sa / keymat.h
index 4f01aa4..6c2b5d4 100644 (file)
@@ -40,7 +40,12 @@ struct keymat_t {
         *
         * The diffie hellman is either for IKE negotiation/rekeying or
         * CHILD_SA rekeying (using PFS). The resulting DH object must be passed
-        * to derive_keys or to derive_child_keys and destroyed after use
+        * to derive_keys or to derive_child_keys and destroyed after use.
+        *
+        * Only DH objects allocated through this method are passed to other
+        * keymat_t methods, allowing private DH implementations. In some cases
+        * (such as retrying with a COOKIE), a DH object allocated from a different
+        * keymat_t instance may be passed to other methods.
         *
         * @param group                 diffie hellman group
         * @return                              DH object, NULL if group not supported
@@ -117,10 +122,12 @@ struct keymat_t {
         * @param ike_sa_init   encoded ike_sa_init message
         * @param nonce                 nonce value
         * @param id                    identity
+        * @param reserved              reserved bytes of id_payload
         * @return                              authentication octets
         */
        chunk_t (*get_auth_octets)(keymat_t *this, bool verify, chunk_t ike_sa_init,
-                                                          chunk_t nonce, identification_t *id);
+                                                          chunk_t nonce, identification_t *id,
+                                                          char reserved[3]);
        /**
         * Build the shared secret signature used for PSK and EAP authentication.
         *
@@ -133,10 +140,12 @@ struct keymat_t {
         * @param nonce                 nonce value
         * @param secret                optional secret to include into signature
         * @param id                    identity
+        * @param reserved              reserved bytes of id_payload
         * @return                              signature octets
         */
        chunk_t (*get_psk_sig)(keymat_t *this, bool verify, chunk_t ike_sa_init,
-                                                  chunk_t nonce, chunk_t secret, identification_t *id);
+                                                  chunk_t nonce, chunk_t secret,
+                                                  identification_t *id, char reserved[3]);
        /**
         * Destroy a keymat_t.
         */