git: 08fd0689d06f - main - net80211: document the crypto enmic/demic functions.

The branch main has been updated by adrian:

URL: https://cgit.FreeBSD.org/src/commit/?id=08fd0689d06fb8587f7d37d8a39647992456b3fd

commit 08fd0689d06fb8587f7d37d8a39647992456b3fd
Author:     Adrian Chadd <adrian@FreeBSD.org>
AuthorDate: 2025-03-16 18:13:01 +0000
Commit:     Adrian Chadd <adrian@FreeBSD.org>
CommitDate: 2025-04-04 03:23:10 +0000

    net80211: document the crypto enmic/demic functions.
    
    These functions implement what's needed for TKIP Michael MIC - which
    is performed over the entire unencrypted MSDU.  Each potential
    fragmented MPDU is encrypted and has its own ICV/MIC.
    
    CCMP/GCMP encrypts each MPDU separately (including the MPDUs that make
    up an A-MPDU), so they'll implement null functions here and instead do
    the MIC/ICV insertion inline in the crypto functions themselves.
    
    Hopefully this makes it a bit clearer on how things should behave, and
    will help figure out and clean up what further hardware offload
    features we need.
    
    Differential Revision:   https://reviews.freebsd.org/D49392
    Reviewed by:    bz
---
 sys/net80211/ieee80211_crypto.c | 18 ++++++++++++++++--
 sys/net80211/ieee80211_crypto.h | 25 +++++++++++++++++++++++--
 2 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/sys/net80211/ieee80211_crypto.c b/sys/net80211/ieee80211_crypto.c
index 600d69d6043b..744d69ce3d1d 100644
--- a/sys/net80211/ieee80211_crypto.c
+++ b/sys/net80211/ieee80211_crypto.c
@@ -774,8 +774,22 @@ ieee80211_crypto_decap(struct ieee80211_node *ni, struct mbuf *m, int hdrlen,
 #undef IEEE80211_WEP_HDRLEN
 }
 
-/*
- * Check and remove any MIC.
+/**
+ * @brief Check and remove any post-defragmentation MIC from an MSDU.
+ *
+ * This is called after defragmentation.  Crypto types that implement
+ * a MIC/ICV check per MSDU will not implement this function.
+ *
+ * As an example, TKIP decapsulation covers both MIC/ICV checks per
+ * MPDU (the "WEP" ICV) and then a Michael MIC verification on the
+ * defragmented MSDU.  Please see 802.11-2020 12.5.2.1.3 (TKIP decapsulation)
+ * for more information.
+ *
+ * @param vap	the current VAP
+ * @param k	the current key
+ * @param m	the mbuf representing the MSDU
+ * @param f	set to 1 to force a MSDU MIC check, even if HW decrypted
+ * @returns	0 if error / MIC check failed, 1 if OK
  */
 int
 ieee80211_crypto_demic(struct ieee80211vap *vap, struct ieee80211_key *k,
diff --git a/sys/net80211/ieee80211_crypto.h b/sys/net80211/ieee80211_crypto.h
index a830d89c6dc8..fa0d3fc3272a 100644
--- a/sys/net80211/ieee80211_crypto.h
+++ b/sys/net80211/ieee80211_crypto.h
@@ -216,6 +216,11 @@ struct ieee80211_cipher {
 	void	(*ic_setiv)(struct ieee80211_key *, uint8_t *);
 	int	(*ic_encap)(struct ieee80211_key *, struct mbuf *);
 	int	(*ic_decap)(struct ieee80211_key *, struct mbuf *, int);
+	/*
+	 * ic_enmic() and ic_demic() are currently only used by TKIP.
+	 * Please see ieee80211_crypto_enmic() and ieee80211_crypto_demic()
+	 * for more information.
+	 */
 	int	(*ic_enmic)(struct ieee80211_key *, struct mbuf *, int);
 	int	(*ic_demic)(struct ieee80211_key *, struct mbuf *, int);
 };
@@ -240,8 +245,24 @@ int	ieee80211_crypto_decap(struct ieee80211_node *,
 		struct mbuf *, int, struct ieee80211_key **);
 int ieee80211_crypto_demic(struct ieee80211vap *vap, struct ieee80211_key *k,
 		struct mbuf *, int);
-/*
- * Add any MIC.
+/**
+ * @brief Add any pre-fragmentation MIC to an MSDU.
+ *
+ * This is called before 802.11 fragmentation.  Crypto types that implement
+ * a MIC/ICV check per MSDU will not implement this function.
+ *
+ * As an example, TKIP implements a Michael MIC check over the entire
+ * unencrypted MSDU before fragmenting it into MPDUs and passing each
+ * MPDU to be separately encrypted with their own MIC/ICV.
+ *
+ * Please see 802.11-2020 12.5.2.1.2 (TKIP cryptographic encapsulation)
+ * for more information.
+ *
+ * @param vap	the current VAP
+ * @param k	the current key
+ * @param m	the mbuf representing the MSDU
+ * @param f	set to 1 to force a MSDU MIC check, even if HW encrypted
+ * @returns	0 if error / MIC encap failed, 1 if OK
  */
 static __inline int
 ieee80211_crypto_enmic(struct ieee80211vap *vap,