PERFORCE change 84779 for review

[Robert Watson]

http://perforce.freebsd.org/chv.cgi?CH=84779

Change 84779 by rwatson at rwatson_peppercorn on 2005/10/04 11:51:17

	A number of changes to audit.h and audit_private.h:
	
	- Annotate each to indicate what goes in them and why.
	- #error out if they are included in non-kernel code, and remove
	  #ifdef _KERNEL sections.
	- Additional comments relating to types, defines, data structures,
	  functions, etc, in audit_private.h.
	- Minor style tweaks.

Affected files ...

.. //depot/projects/trustedbsd/audit3/sys/security/audit/audit.h#3 edit
.. //depot/projects/trustedbsd/audit3/sys/security/audit/audit_private.h#5 edit

Differences ...

==== //depot/projects/trustedbsd/audit3/sys/security/audit/audit.h#3 (text+ko) ====

@@ -21,10 +21,17 @@
  * @APPLE_LICENSE_HEADER_END@
  */
 
+/*
+ * This header includes function prototypes and type definitions that are
+ * necessary for the kernel as a whole to interact with the audit subsystem.
+ */
+
 #ifndef _BSM_AUDIT_KERNEL_H
 #define	_BSM_AUDIT_KERNEL_H
 
-#ifdef _KERNEL
+#ifndef _KERNEL
+#error "no user-serviceable parts inside"
+#endif
 
 #include <bsm/audit.h>
 
@@ -183,9 +190,8 @@
  * possible that an audit record was begun before auditing was turned off.
  */
 #define AUDIT_SYSCALL_EXIT(error, td)	do {				\
-	if (audit_enabled | (td->td_ar != NULL)) {			\
+	if (audit_enabled | (td->td_ar != NULL))			\
 		audit_syscall_exit(error, td);				\
-	}								\
 	} while (0)
 
 /*
@@ -217,6 +223,4 @@
 
 #endif /* AUDIT */
 
-#endif /* _KERNEL */
-
 #endif /* !_BSM_AUDIT_KERNEL_H */

==== //depot/projects/trustedbsd/audit3/sys/security/audit/audit_private.h#5 (text+ko) ====

@@ -21,25 +21,47 @@
  * @APPLE_LICENSE_HEADER_END@
  */
 
+/*
+ * This include file contains function prototypes and type definitions used
+ * within the audit implementation.
+ */
+
 #ifndef _BSM_AUDIT_PRIVATE_H
 #define _BSM_AUDIT_PRIVATE_H
 
+#ifndef _KERNEL
+#error "no user-serviceable parts inside"
+#endif
+
 #include <sys/ipc.h>
 #include <sys/socket.h>
 #include <sys/ucred.h>
 
+#ifdef MALLOC_DECLARE
+MALLOC_DECLARE(M_AUDIT); 
+#endif
+
+/*
+ * Success/failure conditions for the conversion of a kernel audit record to
+ * BSM format.
+ */
 #define BSM_SUCCESS		0
 #define BSM_FAILURE		1
 #define BSM_NOAUDIT		2
 
-#ifdef MALLOC_DECLARE
-MALLOC_DECLARE(M_AUDIT); 
-#endif
-
-/* Defines for the kernel audit record k_ar_commit field */
+/*
+ * Defines for the kernel audit record k_ar_commit field.
+ */
 #define AR_COMMIT_KERNEL	0x00000001U
 #define AR_COMMIT_USER		0x00000010U
 
+/*
+ * Audit data is generated as a stream of struct audit_record structures,
+ * linked by struct kaudit_record, and contain storage for possible audit so
+ * that it will not need to be allocated during the processing of a system
+ * call, both improving efficiency and avoiding sleeping at untimely moments.
+ * This structure is converted to BSM format before being written to disk.
+ */
 struct vnode_au_info {
 	mode_t		vn_mode;
 	uid_t		vn_uid;
@@ -169,19 +191,25 @@
 	TAILQ_ENTRY(kaudit_record)	k_q;
 };
 
+/*
+ * Functions to manage the allocation, release, and commit of kernel audit
+ * records.
+ */
 void			 audit_abort(struct kaudit_record *ar);
 void			 audit_commit(struct kaudit_record *ar, int error, 
 					int retval);
-
 struct kaudit_record	*audit_new(int event, struct thread *td);
 
+/*
+ * Functions relating to the conversion of internal kernel audit records to
+ * the BSM file format.
+ */
 int			kaudit_to_bsm(struct kaudit_record *kar,
-					struct au_record **pau);
-
+			    struct au_record **pau);
 int			bsm_rec_verify(void *rec);
 
 /*
- * Kernel versions of the BSM audit record functions.
+ * Kernel versions of the libbsm audit record functions.
  */
 struct au_record 	*kau_open(void);
 int			kau_write(struct au_record *rec, token_t *m);
@@ -190,7 +218,9 @@
 void			kau_free(struct au_record *rec);
 void			kau_init(void);
 
-
+/*
+ * Return values for pre-selection and post-selection decisions.
+ */
 #define AU_PRS_SUCCESS  1
 #define AU_PRS_FAILURE  2
 #define AU_PRS_BOTH     (AU_PRS_SUCCESS|AU_PRS_FAILURE)
@@ -201,7 +231,6 @@
 #define AUDIT_OPEN_FLAGS FWRITE | O_APPEND
 #define AUDIT_CLOSE_FLAGS FWRITE | O_APPEND
 
-#ifdef _KERNEL
 #include <sys/fcntl.h>
 #include <sys/kernel.h>
 #include <sys/malloc.h>
@@ -242,6 +271,4 @@
 void audit_shutdown(void *arg, int howto);
 void audit_rotate_vnode(struct ucred *cred, struct vnode *vp);
 
-#endif /* _KERNEL */
-
 #endif /* ! _BSM_AUDIT_PRIVATE_H */