linux-kernel - [PATCH] apparmor: fix documentation mismatches in val_mask_to

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-ID: <20250623144111491BDFs497HCFyciwxWW5SG4@zte.com.cn>
Date: Mon, 23 Jun 2025 14:41:11 +0800 (CST)
From: <jiang.peng9@....com.cn>
To: <apparmor@...ts.ubuntu.com>
Cc: <john.johansen@...onical.com>, <paul@...l-moore.com>, <jmorris@...ei.org>,
        <serge@...lyn.com>, <linux-security-module@...r.kernel.org>,
        <linux-kernel@...r.kernel.org>, <xu.xin16@....com.cn>,
        <yang.yang29@....com.cn>
Subject: [PATCH] apparmor: fix documentation mismatches in val_mask_to_str and
 socket functions

From: Peng Jiang <jiang.peng9@....com.cn>

This patch fixes kernel-doc warnings:
1. val_mask_to_str:
- Added missing descriptions for `size` and `table` parameters.
- Removed outdated str_size and chrs references.
2. Socket Functions:
- Makes non-null requirements clear for socket/address args.
- Standardizes return values per kernel conventions.
- Adds Unix domain socket protocol details.

These changes silence doc validation warnings and improve accuracy for
AppArmor LSM docs.

Signed-off-by: Peng Jiang <jiang.peng9@....com.cn>
---
 security/apparmor/lib.c |  4 ++--
 security/apparmor/lsm.c | 28 ++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/security/apparmor/lib.c b/security/apparmor/lib.c
index f51e79cc36d4..4317881d9542 100644
--- a/security/apparmor/lib.c
+++ b/security/apparmor/lib.c
@@ -84,8 +84,8 @@ int aa_parse_debug_params(const char *str)
 /**
  * val_mask_to_str - convert a perm mask to its short string
  * @str: character buffer to store string in (at least 10 characters)
- * @str_size: size of the @str buffer
- * @chrs: NUL-terminated character buffer of permission characters
+ * @size: size of the @str buffer
+ * @table: permission-value-to-string mappings (NOT NULL)
  * @mask: permission mask to convert
  */
 static int val_mask_to_str(char *str, size_t size,
diff --git a/security/apparmor/lsm.c b/security/apparmor/lsm.c
index 7952e8cab353..e41b85a06f12 100644
--- a/security/apparmor/lsm.c
+++ b/security/apparmor/lsm.c
@@ -1122,8 +1122,15 @@ static void unix_connect_peers(struct aa_sk_ctx *sk_ctx,

 /**
  * apparmor_unix_stream_connect - check perms before making unix domain conn
+ * @sk: initiating socket
+ * @peer_sk: target socket being connected to
+ * @newsk: newly created socket for the connection
  *
  * peer is locked when this hook is called
+ *
+ * Return:
+ *   0 if connection is permitted
+ *   error code on denial or failure
  */
 static int apparmor_unix_stream_connect(struct sock *sk, struct sock *peer_sk,
                                        struct sock *newsk)
@@ -1153,10 +1160,20 @@ static int apparmor_unix_stream_connect(struct sock *sk, struct sock *peer_sk,

 /**
  * apparmor_unix_may_send - check perms before conn or sending unix dgrams
+ * @sock: socket initiating the send operation
+ * @peer: target socket receiving the message
+ *
+ * Performs bidirectional permission checks for Unix domain socket communication:
+ * 1. Verifies sender has AA_MAY_SEND to target socket
+ * 2. Verifies receiver has AA_MAY_RECEIVE from source socket
  *
  * sock and peer are locked when this hook is called
  *
  * called by: dgram_connect peer setup but path not copied to newsk
+ *
+ * Return:
+ *   0 if transmission is permitted
+ *   error code on denial or failure
  */
 static int apparmor_unix_may_send(struct socket *sock, struct socket *peer)
 {
@@ -1264,6 +1281,17 @@ static int apparmor_socket_socketpair(struct socket *socka,

 /**
  * apparmor_socket_bind - check perms before bind addr to socket
+ * @sock: socket being bound (must be non-NULL)
+ * @address: address structure to bind (must be non-NULL)
+ * @addrlen: length of the address structure
+ *
+ * Performs security checks before allowing a socket to bind to an address.
+ * Handles Unix domain sockets specially through aa_unix_bind_perm().
+ * For other socket families, uses generic permission check via aa_sk_perm().
+ *
+ * Return:
+ *   0 if binding is permitted
+ *   error code on denial or invalid parameters
  */
 static int apparmor_socket_bind(struct socket *sock,
                                struct sockaddr *address, int addrlen)
-- 
2.25.1