[PATCH] skb hook documentation

jmorrisat_private

The patch below adds some documentation for the skb hooks.

Any suggestions for improvement to this are welcome.

I'll attempt to push it into bitkeeper later Tues (US time) if there are
no objections.

- James
-- 
James Morris
<jmorrisat_private>

--- lsm/include/linux/security.h	Tue Sep 11 15:03:22 2001
+++ lsm-w1/include/linux/security.h	Tue Sep 11 16:02:41 2001
@@ -200,11 +200,63 @@
 	int (* unix_may_send)		(struct socket *sock, struct socket *other);
 };

+/**
+ * Lifecycle hooks for network buffers.
+ *
+ * These hooks are used to help manage the lifecycle of security blobs for
+ * &sk_buff structures, and are not intended to be used for access decisions.
+ */
 struct skb_security_ops {
-	int (* alloc_security)		(struct sk_buff *skb);
-	void (* clone)			(struct sk_buff *newskb, const struct sk_buff *oldskb);
-	void (* copy)			(struct sk_buff *newskb, const struct sk_buff *oldskb);
-	void (* free_security)		(struct sk_buff *skb);
+	/**
+	 * alloc_security - new buffer allocation hook
+	 * @skb: the buffer being allocated
+	 *
+	 * called: alloc_skb <net/core/skbuff.c>
+	 *
+	 * This hook is called by the &sk_buff allocator when a new
+	 * buffer is being allocated.  An LSM module may allocate and
+	 * assign a new security blob for the &sk_buff via this hook.
+	 *
+	 * Return 0 if successful, or -ENOMEM on out of memory condition.
+	 */
+	int (* alloc_security) (struct sk_buff *skb);
+
+	/**
+	 * clone - sk_buff clone hook
+	 * @newskb: the newly cloned buffer
+	 * @oldskb: the buffer being cloned
+	 *
+	 * called: skb_clone <net/core/skbuff.c>
+	 *
+	 * This hook is called when an &sk_buff is being cloned, and may
+	 * be used, for example, to increment a reference count on the
+	 * associated security blob.
+	 */
+	void (* clone) (struct sk_buff *newskb, const struct sk_buff *oldskb);
+
+	/**
+	 * copy - sk_buff copy hook
+	 * @newskb: the newly copied buffer
+	 * @oldskb: the buffer being copied
+	 *
+	 * called: copy_skb_header <net/core/skbuff.c>
+	 *
+	 * This hook is called when an &sk_buff header is being copied,
+	 * which occurs during the skb_copy() and pskb_copy() functions in
+	 * <net/core/skbuff.c>
+	 */
+	void (* copy) (struct sk_buff *newskb, const struct sk_buff *oldskb);
+
+	/**
+	 * free_security - sk_buff destruction hook
+	 * @skb: the buffer being destroyed
+	 *
+	 * called: __kfree_skb <net/core/skbuff.c>
+	 *
+	 * This hook is called when an &sk_buff is being destroyed, and
+	 * should be used to free any associated security blob.
+	 */
+	void (* free_security) (struct sk_buff *skb);
 };

 struct net_device;



_______________________________________________
linux-security-module mailing list
linux-security-moduleat_private
http://mail.wirex.com/mailman/listinfo/linux-security-module
