From nobody Wed Apr 22 21:07:56 2026 X-Original-To: dev-commits-src-branches@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4g1BdT2Rylz6bKkr for ; Wed, 22 Apr 2026 21:07:57 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R13" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4g1BdT0NFnz3kKZ for ; Wed, 22 Apr 2026 21:07:57 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1776892077; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=oWLVjhMh2U5t2XuzU20+kKNMofWvvQBx2T8Uup6Tffk=; b=sIxmUbVTQ5s2QJIBT+RAvQx3Wa7gXBAtISr66A9qQ/YGRYt6r30HIngICR3FBEweHnw3Dx l1o2lXNlkxN6Kvd+9AA6GSPmyY7YjnY7BrH3HNPubfzSn2hkrNBpubYWSiIwA63UNdp09A WvhPQn5eAWxYbYKp9bQXC27XRIPKdr+YylOAeYbAJx8XVFbcUAgnyadpkSiS3gqsu3HsKu /LkuRKiVgbHQ7cIPhUwceaFpO0P06Gw0msVvwrpMR5SyHRiLaggqwH8IoCo9Yz0NY1a1zH oFGrJ4WtF7fSCFZrNVCqaMGX2Z+a7hwiw5eN8FwtkW+Trp7PlL/o2aRj0EemRA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1776892077; a=rsa-sha256; cv=none; b=ocp3dqMBcovUGW6Vd/1YUVx/+KSjwFSQjGEDcDbZpYuvc9mv2Dnz+V3uX34dr4CKP/luE/ q7Q/mcxoQBzze4m5bPD9YZRJofK06R5ift48vwXZ8OaEFGAlfZuQ76Bfqmtu+UpfUFH+dA iUyQDO4Fv8wy1kBhKW3WFrsGQnlfmJYfpe5HOfltskzZQ6zOO35D7eV1IG8HdZxG1bMWyS dYk4TyjOAIKlpPtn+rEac8oxWThEKuYM1tGwKtFtZG88dTyZ563utR8E06P3Vz/uif/VzY QEHh6OXyS3o0YsFvVGYR8OxthcY3qPY4Kc22DnmnvOlxe1/PgR0SQEl8ew8NdA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1776892077; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=oWLVjhMh2U5t2XuzU20+kKNMofWvvQBx2T8Uup6Tffk=; b=eJb3Z4T4oKDwrTOt7dgM7YZERCvXVIgvJsYRdX7ibP03C7mutKDV73yN/8u8yrJJm3R2Ms gkcHZbXJtg8EytFnLO3dAXHi8bcB6Uy7tY/DMlD04AOHxkgM0VKFd0Q0WjpLnysnIvZkl7 XSbdUGFXy/o9EEfObnDNK4W8TqlgbjXOkYwW8DVSaQTFsLAT6ADHmLoMq4veKPV5sCjXHK wUTvz8vmsraY8mQ+bmzPKaXonFbXHlu+fVnlGWGQwQJAtmWSjQ+fhGoRkH0Ah6yFGFD52w f14RGpVx6HqMhGZvRPfl78/kc+zMy3QduRs0LbKN2vpVv9snvfS6stfCx49wMw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4g1BdS71lrznZ6 for ; Wed, 22 Apr 2026 21:07:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 25ef4 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Wed, 22 Apr 2026 21:07:56 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org Cc: Adrian Chadd From: Bjoern A. Zeeb Subject: git: bc6b3e0307da - stable/15 - net80211: document some of the crypto/key functions List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-branches@freebsd.org Sender: owner-dev-commits-src-branches@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: bz X-Git-Repository: src X-Git-Refname: refs/heads/stable/15 X-Git-Reftype: branch X-Git-Commit: bc6b3e0307da96b745d901ea83c1290413c977d8 Auto-Submitted: auto-generated Date: Wed, 22 Apr 2026 21:07:56 +0000 Message-Id: <69e938ac.25ef4.b4ea15e@gitrepo.freebsd.org> The branch stable/15 has been updated by bz: URL: https://cgit.FreeBSD.org/src/commit/?id=bc6b3e0307da96b745d901ea83c1290413c977d8 commit bc6b3e0307da96b745d901ea83c1290413c977d8 Author: Adrian Chadd AuthorDate: 2025-09-20 21:30:42 +0000 Commit: Bjoern A. Zeeb CommitDate: 2026-04-22 20:56:51 +0000 net80211: document some of the crypto/key functions This documents the following functions: * ieee80211_is_key_global() * ieee80211_is_key_unicast() * ieee80211_crypto_get_key_wepidx() * ieee80211_crypto_get_keyid() * ieee80211_crypto_get_txkey() * ieee80211_crypto_encap() * ieee80211_crypto_decap() Differential Revision: https://reviews.freebsd.org/D52649 (cherry picked from commit 1f76551e1a5e98673f31043d11366ca41d4f56fe) --- sys/net80211/ieee80211.c | 28 +++++++++++-- sys/net80211/ieee80211_crypto.c | 87 ++++++++++++++++++++++++++++++++++++----- 2 files changed, 102 insertions(+), 13 deletions(-) diff --git a/sys/net80211/ieee80211.c b/sys/net80211/ieee80211.c index 2b7cf635b9f5..1299f86ebdc7 100644 --- a/sys/net80211/ieee80211.c +++ b/sys/net80211/ieee80211.c @@ -2689,13 +2689,18 @@ ieee80211_channel_type_char(const struct ieee80211_channel *c) return 'f'; } -/* - * Determine whether the given key in the given VAP is a global key. +/** + * @brief Determine whether the given key in the given VAP is a global key. + * * (key index 0..3, shared between all stations on a VAP.) * * This is either a WEP key or a GROUP key. * * Note this will NOT return true if it is a IGTK key. + * + * @param vap the current VAP + * @param key ieee80211_key to use/check + * @returns true if it's a global/WEP key, false otherwise */ bool ieee80211_is_key_global(const struct ieee80211vap *vap, @@ -2705,8 +2710,23 @@ ieee80211_is_key_global(const struct ieee80211vap *vap, key < &vap->iv_nw_keys[IEEE80211_WEP_NKID]); } -/* - * Determine whether the given key in the given VAP is a unicast key. +/** + * @brief Determine whether the given key in the given VAP is a unicast key. + * + * This only returns true if it's a unicast key. + * + * Note: For now net80211 only supports a single unicast key, stored in + * an ieee80211_node entry. + * + * Code should use this to know if it's a unicast key and then call + * ieee80211_crypto_get_keyid() to get the 802.11 key ID (0..3 for + * unicast/global keys, 4..5 for IGTK keys.) Since the unicast + * and global key indexes "overlap", callers will need to check + * both the type and id. + * + * @param vap the current VAP + * @param key ieee80211_key to use/check + * @returns true if the key is a unicast key, false if it is not */ bool ieee80211_is_key_unicast(const struct ieee80211vap *vap, diff --git a/sys/net80211/ieee80211_crypto.c b/sys/net80211/ieee80211_crypto.c index 1e63ca46f28f..566f0b2e0c23 100644 --- a/sys/net80211/ieee80211_crypto.c +++ b/sys/net80211/ieee80211_crypto.c @@ -611,11 +611,15 @@ ieee80211_crypto_setkey(struct ieee80211vap *vap, struct ieee80211_key *key) return dev_key_set(vap, key); } -/* - * Return index if the key is a WEP key (0..3); -1 otherwise. +/** + * @brief Return index if the key is a WEP key (0..3); -1 otherwise. * * This is different to "get_keyid" which defaults to returning * 0 for unicast keys; it assumes that it won't be used for WEP. + * + * @param vap the current VAP + * @param k ieee80211_key to check + * @returns 0..3 if it's a global/WEP key, -1 otherwise. */ int ieee80211_crypto_get_key_wepidx(const struct ieee80211vap *vap, @@ -628,8 +632,18 @@ ieee80211_crypto_get_key_wepidx(const struct ieee80211vap *vap, return (-1); } -/* - * Note: only supports a single unicast key (0). +/** + * @brief Return the index of a unicast, global or IGTK key. + * + * Return the index of a key. For unicast keys the index is 0..1. + * For global/WEP keys it's 0..3. For IGTK keys its 4..5. + * + * TODO: support >1 unicast key + * TODO: support IGTK keys + * + * @param vap the current VAP + * @param k ieee80211_key to check + * @returns 0..3 for a WEP/global key, 0..1 for unicast key, 4..5 for IGTK key */ uint8_t ieee80211_crypto_get_keyid(struct ieee80211vap *vap, struct ieee80211_key *k) @@ -641,6 +655,19 @@ ieee80211_crypto_get_keyid(struct ieee80211vap *vap, struct ieee80211_key *k) return (0); } +/** + * @param Return the key to use for encrypting an mbuf frame to a node + * + * This routine chooses a suitable key used to encrypt the given frame with. + * It doesn't do the encryption; it only chooses the key. If a key is not + * available then the routine will return NULL. + * + * It's up to the caller to enforce whether a key is absolutely required or not. + * + * @param ni The ieee80211_node to send the frame to + * @param m the mbuf to encrypt + * @returns the ieee80211_key to encrypt with, or NULL if there's no suitable key + */ struct ieee80211_key * ieee80211_crypto_get_txkey(struct ieee80211_node *ni, struct mbuf *m) { @@ -676,8 +703,28 @@ ieee80211_crypto_get_txkey(struct ieee80211_node *ni, struct mbuf *m) return &ni->ni_ucastkey; } -/* - * Add privacy headers appropriate for the specified key. +/** + * @brief Privacy encapsulate and encrypt the given mbuf. + * + * This routine handles the mechanics of encryption - expanding the + * mbuf to add privacy headers, IV, ICV, MIC, MMIC, and then encrypts + * the given mbuf if required. + * + * This should be called by the driver in its TX path as part of + * encapsulation before passing frames to the hardware/firmware + * queues. + * + * Drivers/hardware which does its own entirely offload path + * should still call this for completeness - it indicates to the + * driver that the frame itself should be encrypted. + * + * The driver should have set capability bits in the attach / + * key allocation path to disable various encapsulation/encryption + * features. + * + * @param ni ieee80211_node for this frame + * @param mbuf mbuf to modify + * @returns the key used if the frame is to be encrypted, NULL otherwise */ struct ieee80211_key * ieee80211_crypto_encap(struct ieee80211_node *ni, struct mbuf *m) @@ -693,9 +740,31 @@ ieee80211_crypto_encap(struct ieee80211_node *ni, struct mbuf *m) return NULL; } -/* - * Validate and strip privacy headers (and trailer) for a - * received frame that has the WEP/Privacy bit set. +/** + * @brief Decapsulate and validate an encrypted frame. + * + * This handles an encrypted frame (one with the privacy bit set.) + * It also obeys the key / config / receive packet flags for how + * the driver says its already been processed. + * + * Unlike ieee80211_crypto_encap(), this isn't called in the driver. + * Instead, drivers passed the potentially decrypted frame - fully, + * partial, or not at all - and net80211 will call this as appropriate. + * + * This handles NICs (like ath(4)) which have a variable size between + * the 802.11 header and 802.11 payload due to DMA alignment / encryption + * engine concerns. + * + * If the frame was decrypted and validated successfully then 1 is returned + * and the mbuf can be treated as an 802.11 frame. If it is not decrypted + * successfully or it was decrypted but failed validation/checks, then + * 0 is returned. + * + * @param ni ieee80211_node for received frame + * @param m mbuf frame to receive + * @param hdrlen length of the 802.11 header, including trailing null bytes + * @param key pointer to ieee80211_key that will be set if appropriate + * @returns 0 if the frame wasn't decrypted/validated, 1 if decrypted/validated. */ int ieee80211_crypto_decap(struct ieee80211_node *ni, struct mbuf *m, int hdrlen,