Re: [PATCH] security.h documentation

sdsat_private

Here is a patch to add documentation for the binprm_security_ops.
It also adds a comment header to the super_block_security_ops,
since I forgot to add one earlier.  Barring objections, I can 
commit these changes.

--
Stephen D. Smalley, NAI Labs
ssmalleyat_private

--- lsm-wirex/include/linux/security.h	Thu Sep 13 13:01:55 2001
+++ lsm/include/linux/security.h	Thu Sep 13 15:35:33 2001
@@ -46,19 +46,77 @@
 /* setfsuid or setfsgid, id0 == fsuid or fsgid */
 #define LSM_SETID_FS	8
 
-
+/**
+ * Security hooks for program execution operations.
+ */
 struct binprm_security_ops {
-	int (* alloc_security)		(struct linux_binprm *bprm);	/* create per binprm security stuff */
-	void (* free_security)		(struct linux_binprm *bprm);	/* free it */
-	void (* compute_creds)		(struct linux_binprm *bprm);	/* transfer credentials to current during exec */
-	/*
-	 * set_security may be called multiple times on a single execve, e.g.
-	 * for interpreters.  It can tell whether it has already been called by
-	 * checking to see if bprm->security is non-NULL.
+	/**
+	 * alloc_security - allocate security structure for linux_binprm
+	 * @bprm: linux_binprm structure to be modified
+	 *
+	 * called: do_execve <fs/exec.c>
+	 *
+	 * Allocate and attach a security structure to the bprm->security 
+	 * field. The security field is initialized to NULL when the bprm
+	 * structure is allocated.  Return 0 if operation was successful.
+	 */
+	int (* alloc_security) (struct linux_binprm *bprm);
+
+	/**
+	 * free_security - deallocate security structure for linux_binprm
+	 * @bprm: linux_binprm structure to be modified
+	 *
+	 * called: do_execve <fs/exec.c>
+	 *
+	 * Deallocate and clear the bprm->security field.
+	 */
+	void (* free_security) (struct linux_binprm *bprm);
+
+	/**
+	 * compute_creds - compute and set process security attributes
+	 * @bprm: linux_binprm structure 
+	 *
+	 * called: compute_creds <fs/exec.c>
+	 *
+	 * Compute and set the security attributes of a process
+	 * being transformed by an execve operation based on the
+	 * old attributes (current->security) and the information
+	 * saved in bprm->security by the set_security hook.
+	 * Since this hook function (and its caller) are void,
+	 * this hook can not return an error.  However, it can
+	 * leave the security attributes of the process unchanged
+	 * if an access failure occurs at this point. It can 
+	 * also perform other state changes on the process (e.g.
+	 * closing open file descriptions to which access is no
+	 * longer granted if the attributes were changed). 
+	 */
+	void (* compute_creds) (struct linux_binprm *bprm);
+
+	/**
+	 * set_security - save security information in linux_binprm
+	 * @bprm: linux_binprm structure 
+	 *
+	 * called: prepare_binprm <fs/exec.c>
+	 *
+	 * Save security information in the bprm->security field,
+	 * typically based on information about the bprm->file,
+	 * for later use by the compute_creds hook.  This hook may 
+	 * also optionally check permissions (e.g. for transitions between 
+	 * security domains).  Return 0 if the hook is successful
+	 * and permission is granted.
+	 *
+	 * This hook may be called multiple times during a single execve, 
+	 * e.g. for interpreters.  The hook can tell whether it has already 
+	 * been called by checking to see if bprm->security is non-NULL.  
+	 * If so, then the hook may decide either to retain the security
+	 * information saved earlier or to replace it.
 	 */
-	int (* set_security)		(struct linux_binprm *bprm);	/* set per binprm security stuff */
+	int (* set_security) (struct linux_binprm *bprm);
 };
 
+/**
+ * Security hooks for filesystem operations.
+ */
 struct super_block_security_ops {
 	/**
 	 * alloc_security - allocate security structure for this filesystem

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