[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [PATCH] kerneldoc for kernel/audit*.c



Top posting my 'Woo!'

Thanks Randy!

-tim

On Tuesday 13 September 2005 14:47, Chris Wright wrote:
> From: Randy Dunlap <rdunlap xenotime net>
> 
> for kernel/audit*.c:
> - add kerneldoc for non-static functions;
> - don't init static data to 0;
> - limit lines to < 80 columns;
> - fix long-format style;
> - delete whitespace at end of some lines;
> 
> (chrisw: resend and update to current audit-2.6 tree)
> 
> Signed-off-by: Randy Dunlap <rdunlap xenotime net>
> Signed-off-by: Chris Wright <chrisw osdl org>
> ---
>  kernel/audit.c   |  134 ++++++++++++++++++++++++++++++++++++++-----------
>  kernel/auditsc.c |  150 ++++++++++++++++++++++++++++++++++++++++++++++++-------
>  2 files changed, 238 insertions(+), 46 deletions(-)
> 
> diff --git a/kernel/audit.c b/kernel/audit.c
> --- a/kernel/audit.c
> +++ b/kernel/audit.c
> @@ -72,7 +72,7 @@ static int	audit_failure = AUDIT_FAIL_PR
>   * contains the (non-zero) pid. */
>  int		audit_pid;
>  
> -/* If audit_limit is non-zero, limit the rate of sending audit records
> +/* If audit_rate_limit is non-zero, limit the rate of sending audit records
>   * to that number per second.  This prevents DoS attacks, but results in
>   * audit records being dropped. */
>  static int	audit_rate_limit;
> @@ -102,7 +102,7 @@ static struct sock *audit_sock;
>   * than AUDIT_MAXFREE are in use, the audit buffer is freed instead of
>   * being placed on the freelist). */
>  static DEFINE_SPINLOCK(audit_freelist_lock);
> -static int	   audit_freelist_count = 0;
> +static int	   audit_freelist_count;
>  static LIST_HEAD(audit_freelist);
>  
>  static struct sk_buff_head audit_skb_queue;
> @@ -186,8 +186,14 @@ static inline int audit_rate_check(void)
>  	return retval;
>  }
>  
> -/* Emit at least 1 message per second, even if audit_rate_check is
> - * throttling. */
> +/**
> + * audit_log_lost - conditionally log lost audit message event
> + * @message: the message stating reason for lost audit message
> + *
> + * Emit at least 1 message per second, even if audit_rate_check is
> + * throttling.
> + * Always increment the lost messages counter.
> +*/
>  void audit_log_lost(const char *message)
>  {
>  	static unsigned long	last_msg = 0;
> @@ -218,7 +224,6 @@ void audit_log_lost(const char *message)
>  		       audit_backlog_limit);
>  		audit_panic(message);
>  	}
> -
>  }
>  
>  static int audit_set_rate_limit(int limit, uid_t loginuid)
> @@ -300,6 +305,19 @@ int kauditd_thread(void *dummy)
>  	}
>  }
>  
> +/**
> + * audit_send_reply - send an audit reply message via netlink
> + * @pid: process id to send reply to
> + * @seq: sequence number
> + * @type: audit message type
> + * @done: done (last) flag
> + * @multi: multi-part message flag
> + * @payload: payload data
> + * @size: payload size
> + *
> + * Allocates an skb, builds the netlink message, and sends it to the pid.
> + * No failure notifications.
> + */
>  void audit_send_reply(int pid, int seq, int type, int done, int multi,
>  		      void *payload, int size)
>  {
> @@ -374,7 +392,8 @@ static int audit_receive_msg(struct sk_b
>  	if (err)
>  		return err;
>  
> -	/* As soon as there's any sign of userspace auditd, start kauditd to talk to it */
> +	/* As soon as there's any sign of userspace auditd,
> +	 * start kauditd to talk to it */
>  	if (!kauditd_task)
>  		kauditd_task = kthread_run(kauditd_thread, NULL, "kauditd");
>  	if (IS_ERR(kauditd_task)) {
> @@ -467,9 +486,11 @@ static int audit_receive_msg(struct sk_b
>  	return err < 0 ? err : 0;
>  }
>  
> -/* Get message from skb (based on rtnetlink_rcv_skb).  Each message is
> +/*
> + * Get message from skb (based on rtnetlink_rcv_skb).  Each message is
>   * processed by audit_receive_msg.  Malformed skbs with wrong length are
> - * discarded silently.  */
> + * discarded silently.
> + */
>  static void audit_receive_skb(struct sk_buff *skb)
>  {
>  	int		err;
> @@ -597,7 +618,10 @@ err:
>  	return NULL;
>  }
>  
> -/* Compute a serial number for the audit record.  Audit records are
> +/**
> + * audit_serial - compute a serial number for the audit record
> + *
> + * Compute a serial number for the audit record.  Audit records are
>   * written to user-space as soon as they are generated, so a complete
>   * audit record may be written in several pieces.  The timestamp of the
>   * record and this serial number are used by the user-space tools to
> @@ -609,8 +633,8 @@ err:
>   * audit context (for those records that have a context), and emit them
>   * all at syscall exit.  However, this could delay the reporting of
>   * significant errors until syscall exit (or never, if the system
> - * halts). */
> -
> + * halts).
> + */
>  unsigned int audit_serial(void)
>  {
>  	static spinlock_t serial_lock = SPIN_LOCK_UNLOCKED;
> @@ -646,6 +670,21 @@ static inline void audit_get_stamp(struc
>   * will be written at syscall exit.  If there is no associated task, tsk
>   * should be NULL. */
>  
> +/**
> + * audit_log_start - obtain an audit buffer
> + * @ctx: audit_context (may be NULL)
> + * @gfp_mask: type of allocation
> + * @type: audit message type
> + *
> + * Returns audit_buffer pointer on success or NULL on error.
> + *
> + * Obtain an audit buffer.  This routine does locking to obtain the
> + * audit buffer, but then no locking is required for calls to
> + * audit_log_*format.  If the task (ctx) is a task that is currently in a
> + * syscall, then the syscall is marked as auditable and an audit record
> + * will be written at syscall exit.  If there is no associated task, then
> + * task context (ctx) should be NULL.
> + */
>  struct audit_buffer *audit_log_start(struct audit_context *ctx, int gfp_mask,
>  				     int type)
>  {
> @@ -710,6 +749,7 @@ struct audit_buffer *audit_log_start(str
>  /**
>   * audit_expand - expand skb in the audit buffer
>   * @ab: audit_buffer
> + * @extra: space to add at tail of the skb
>   *
>   * Returns 0 (no space) on failed expansion, or available space if
>   * successful.
> @@ -726,10 +766,12 @@ static inline int audit_expand(struct au
>  	return skb_tailroom(skb);
>  }
>  
> -/* Format an audit message into the audit buffer.  If there isn't enough
> +/*
> + * Format an audit message into the audit buffer.  If there isn't enough
>   * room in the audit buffer, more room will be allocated and vsnprint
>   * will be called a second time.  Currently, we assume that a printk
> - * can't format message larger than 1024 bytes, so we don't either. */
> + * can't format message larger than 1024 bytes, so we don't either.
> + */
>  static void audit_log_vformat(struct audit_buffer *ab, const char *fmt,
>  			      va_list args)
>  {
> @@ -754,7 +796,8 @@ static void audit_log_vformat(struct aud
>  		/* The printk buffer is 1024 bytes long, so if we get
>  		 * here and AUDIT_BUFSIZ is at least 1024, then we can
>  		 * log everything that printk could have logged. */
> -		avail = audit_expand(ab, max_t(unsigned, AUDIT_BUFSIZ, 1+len-avail));
> +		avail = audit_expand(ab,
> +			max_t(unsigned, AUDIT_BUFSIZ, 1+len-avail));
>  		if (!avail)
>  			goto out;
>  		len = vsnprintf(skb->tail, avail, fmt, args2);
> @@ -765,8 +808,14 @@ out:
>  	return;
>  }
>  
> -/* Format a message into the audit buffer.  All the work is done in
> - * audit_log_vformat. */
> +/**
> + * audit_log_format - format a message into the audit buffer.
> + * @ab: audit_buffer
> + * @fmt: format string
> + * @...: optional parameters matching @fmt string
> + *
> + * All the work is done in audit_log_vformat.
> + */
>  void audit_log_format(struct audit_buffer *ab, const char *fmt, ...)
>  {
>  	va_list args;
> @@ -778,9 +827,18 @@ void audit_log_format(struct audit_buffe
>  	va_end(args);
>  }
>  
> -/* This function will take the passed buf and convert it into a string of
> - * ascii hex digits. The new string is placed onto the skb. */
> -void audit_log_hex(struct audit_buffer *ab, const unsigned char *buf, 
> +/**
> + * audit_log_hex - convert a buffer to hex and append it to the audit skb
> + * @ab: the audit_buffer
> + * @buf: buffer to convert to hex
> + * @len: length of @buf to be converted
> + *
> + * No return value; failure to expand is silently ignored.
> + *
> + * This function will take the passed buf and convert it into a string of
> + * ascii hex digits. The new string is placed onto the skb.
> + */
> +void audit_log_hex(struct audit_buffer *ab, const unsigned char *buf,
>  		size_t len)
>  {
>  	int i, avail, new_len;
> @@ -809,10 +867,16 @@ void audit_log_hex(struct audit_buffer *
>  	skb_put(skb, len << 1); /* new string is twice the old string */
>  }
>  
> -/* This code will escape a string that is passed to it if the string
> - * contains a control character, unprintable character, double quote mark, 
> +/**
> + * audit_log_unstrustedstring - log a string that may contain random characters
> + * @ab: audit_buffer
> + * @string: string to be logged
> + *
> + * This code will escape a string that is passed to it if the string
> + * contains a control character, unprintable character, double quote mark,
>   * or a space. Unescaped strings will start and end with a double quote mark.
> - * Strings that are escaped are printed in hex (2 digits per char). */
> + * Strings that are escaped are printed in hex (2 digits per char).
> + */
>  void audit_log_untrustedstring(struct audit_buffer *ab, const char *string)
>  {
>  	const unsigned char *p = string;
> @@ -851,10 +915,15 @@ void audit_log_d_path(struct audit_buffe
>  	kfree(path);
>  }
>  
> -/* The netlink_* functions cannot be called inside an irq context, so
> - * the audit buffer is places on a queue and a tasklet is scheduled to
> +/**
> + * audit_log_end - end one audit record
> + * @ab: the audit_buffer
> + *
> + * The netlink_* functions cannot be called inside an irq context, so
> + * the audit buffer is placed on a queue and a tasklet is scheduled to
>   * remove them from the queue outside the irq context.  May be called in
> - * any context. */
> + * any context.
> + */
>  void audit_log_end(struct audit_buffer *ab)
>  {
>  	if (!ab)
> @@ -875,9 +944,18 @@ void audit_log_end(struct audit_buffer *
>  	audit_buffer_free(ab);
>  }
>  
> -/* Log an audit record.  This is a convenience function that calls
> - * audit_log_start, audit_log_vformat, and audit_log_end.  It may be
> - * called in any context. */
> +/**
> + * audit_log - Log an audit record
> + * @ctx: audit context
> + * @gfp_mask: type of allocation
> + * @type: audit message type
> + * @fmt: format string to use
> + * @...: variable parameters matching the format string
> + *
> + * This is a convenience function that calls audit_log_start,
> + * audit_log_vformat, and audit_log_end.  It may be called
> + * in any context.
> + */
>  void audit_log(struct audit_context *ctx, int gfp_mask, int type, 
>  	       const char *fmt, ...)
>  {
> diff --git a/kernel/auditsc.c b/kernel/auditsc.c
> --- a/kernel/auditsc.c
> +++ b/kernel/auditsc.c
> @@ -330,6 +330,15 @@ static int audit_list_rules(void *_dest)
>  	return 0;
>  }
>  
> +/**
> + * audit_receive_filter - apply all rules to the specified message type
> + * @type: audit message type
> + * @pid: target pid for netlink audit messages
> + * @uid: target uid for netlink audit messages
> + * @seq: netlink audit message sequence (serial) number
> + * @data: payload data
> + * @loginuid: loginuid of sender
> + */
>  int audit_receive_filter(int type, int pid, int uid, int seq, void *data,
>  							uid_t loginuid)
>  {
> @@ -527,7 +536,7 @@ static enum audit_state audit_filter_tas
>  /* At syscall entry and exit time, this filter is called if the
>   * audit_state is not low enough that auditing cannot take place, but is
>   * also not high enough that we already know we have to write an audit
> - * record (i.e., the state is AUDIT_SETUP_CONTEXT or  AUDIT_BUILD_CONTEXT).
> + * record (i.e., the state is AUDIT_SETUP_CONTEXT or AUDIT_BUILD_CONTEXT).
>   */
>  static enum audit_state audit_filter_syscall(struct task_struct *tsk,
>  					     struct audit_context *ctx,
> @@ -721,10 +730,15 @@ static inline struct audit_context *audi
>  	return context;
>  }
>  
> -/* Filter on the task information and allocate a per-task audit context
> +/**
> + * audit_alloc - allocate an audit context block for a task
> + * @tsk: task
> + *
> + * Filter on the task information and allocate a per-task audit context
>   * if necessary.  Doing so turns on system call auditing for the
>   * specified task.  This is called from copy_process, so no lock is
> - * needed. */
> + * needed.
> + */
>  int audit_alloc(struct task_struct *tsk)
>  {
>  	struct audit_context *context;
> @@ -911,8 +925,12 @@ static void audit_log_exit(struct audit_
>  	}
>  }
>  
> -/* Free a per-task audit context.  Called from copy_process and
> - * __put_task_struct. */
> +/**
> + * audit_free - free a per-task audit context
> + * @tsk: task whose audit context block to free
> + *
> + * Called from copy_process and __put_task_struct.
> + */
>  void audit_free(struct task_struct *tsk)
>  {
>  	struct audit_context *context;
> @@ -934,13 +952,24 @@ void audit_free(struct task_struct *tsk)
>  	audit_free_context(context);
>  }
>  
> -/* Fill in audit context at syscall entry.  This only happens if the
> +/**
> + * audit_syscall_entry - fill in an audit record at syscall entry
> + * @tsk: task being audited
> + * @arch: architecture type
> + * @major: major syscall type (function)
> + * @a1: additional syscall register 1
> + * @a2: additional syscall register 2
> + * @a3: additional syscall register 3
> + * @a4: additional syscall register 4
> + *
> + * Fill in audit context at syscall entry.  This only happens if the
>   * audit context was created when the task was created and the state or
>   * filters demand the audit context be built.  If the state from the
>   * per-task filter or from the per-syscall filter is AUDIT_RECORD_CONTEXT,
>   * then the record will be written at syscall exit time (otherwise, it
>   * will only be written if another part of the kernel requests that it
> - * be written). */
> + * be written).
> + */
>  void audit_syscall_entry(struct task_struct *tsk, int arch, int major,
>  			 unsigned long a1, unsigned long a2,
>  			 unsigned long a3, unsigned long a4)
> @@ -950,7 +979,8 @@ void audit_syscall_entry(struct task_str
>  
>  	BUG_ON(!context);
>  
> -	/* This happens only on certain architectures that make system
> +	/*
> +	 * This happens only on certain architectures that make system
>  	 * calls in kernel_thread via the entry.S interface, instead of
>  	 * with direct calls.  (If you are porting to a new
>  	 * architecture, hitting this condition can indicate that you
> @@ -1014,11 +1044,18 @@ void audit_syscall_entry(struct task_str
>  	context->auditable  = !!(state == AUDIT_RECORD_CONTEXT);
>  }
>  
> -/* Tear down after system call.  If the audit context has been marked as
> +/**
> + * audit_syscall_exit - deallocate audit context after a system call
> + * @tsk: task being audited
> + * @valid: success/failure flag
> + * @return_code: syscall return value
> + *
> + * Tear down after system call.  If the audit context has been marked as
>   * auditable (either because of the AUDIT_RECORD_CONTEXT state from
>   * filtering, or because some other part of the kernel write an audit
>   * message), then write out the syscall information.  In call cases,
> - * free the names stored from getname(). */
> + * free the names stored from getname().
> + */
>  void audit_syscall_exit(struct task_struct *tsk, int valid, long return_code)
>  {
>  	struct audit_context *context;
> @@ -1053,7 +1090,13 @@ void audit_syscall_exit(struct task_stru
>  	put_task_struct(tsk);
>  }
>  
> -/* Add a name to the list.  Called from fs/namei.c:getname(). */
> +/**
> + * audit_getname - add a name to the list
> + * @name: name to add
> + *
> + * Add a name to the list of audit names for this context.
> + * Called from fs/namei.c:getname().
> + */
>  void audit_getname(const char *name)
>  {
>  	struct audit_context *context = current->audit_context;
> @@ -1082,10 +1125,13 @@ void audit_getname(const char *name)
>  		
>  }
>  
> -/* Intercept a putname request.  Called from
> - * include/linux/fs.h:putname().  If we have stored the name from
> - * getname in the audit context, then we delay the putname until syscall
> - * exit. */
> +/* audit_putname - intercept a putname request
> + * @name: name to intercept and delay for putname
> + *
> + * If we have stored the name from getname in the audit context,
> + * then we delay the putname until syscall exit.
> + * Called from include/linux/fs.h:putname().
> + */
>  void audit_putname(const char *name)
>  {
>  	struct audit_context *context = current->audit_context;
> @@ -1122,8 +1168,14 @@ void audit_putname(const char *name)
>  #endif
>  }
>  
> -/* Store the inode and device from a lookup.  Called from
> - * fs/namei.c:path_lookup(). */
> +/**
> + * audit_inode - store the inode and device from a lookup
> + * @name: name being audited
> + * @inode: inode being audited
> + * @flags: lookup flags (as used in path_lookup())
> + *
> + * Called from fs/namei.c:path_lookup().
> + */
>  void audit_inode(const char *name, const struct inode *inode, unsigned flags)
>  {
>  	int idx;
> @@ -1159,6 +1211,14 @@ void audit_inode(const char *name, const
>  	context->names[idx].rdev  = inode->i_rdev;
>  }
>  
> +/**
> + * auditsc_get_stamp - get local copies of audit_context values
> + * @ctx: audit_context for the task
> + * @t: timespec to store time recorded in the audit_context
> + * @serial: serial value that is recorded in the audit_context
> + *
> + * Also sets the context as auditable.
> + */
>  void auditsc_get_stamp(struct audit_context *ctx,
>  		       struct timespec *t, unsigned int *serial)
>  {
> @@ -1170,6 +1230,15 @@ void auditsc_get_stamp(struct audit_cont
>  	ctx->auditable = 1;
>  }
>  
> +/**
> + * audit_set_loginuid - set a task's audit_context loginuid
> + * @task: task whose audit context is being modified
> + * @loginuid: loginuid value
> + *
> + * Returns 0.
> + *
> + * Called (set) from fs/proc/base.c::proc_loginuid_write().
> + */
>  int audit_set_loginuid(struct task_struct *task, uid_t loginuid)
>  {
>  	if (task->audit_context) {
> @@ -1188,11 +1257,26 @@ int audit_set_loginuid(struct task_struc
>  	return 0;
>  }
>  
> +/**
> + * audit_get_loginuid - get the loginuid for an audit_context
> + * @ctx: the audit_context
> + *
> + * Returns the context's loginuid or -1 if @ctx is NULL.
> + */
>  uid_t audit_get_loginuid(struct audit_context *ctx)
>  {
>  	return ctx ? ctx->loginuid : -1;
>  }
>  
> +/**
> + * audit_ipc_perms - record audit data for ipc
> + * @qbytes: msgq bytes
> + * @uid: msgq user id
> + * @gid: msgq group id
> + * @mode: msgq mode (permissions)
> + *
> + * Returns 0 for success or NULL context or < 0 on error.
> + */
>  int audit_ipc_perms(unsigned long qbytes, uid_t uid, gid_t gid, mode_t mode)
>  {
>  	struct audit_aux_data_ipcctl *ax;
> @@ -1216,6 +1300,13 @@ int audit_ipc_perms(unsigned long qbytes
>  	return 0;
>  }
>  
> +/**
> + * audit_socketcall - record audit data for sys_socketcall
> + * @nargs: number of args
> + * @args: args array
> + *
> + * Returns 0 for success or NULL context or < 0 on error.
> + */
>  int audit_socketcall(int nargs, unsigned long *args)
>  {
>  	struct audit_aux_data_socketcall *ax;
> @@ -1237,6 +1328,13 @@ int audit_socketcall(int nargs, unsigned
>  	return 0;
>  }
>  
> +/**
> + * audit_sockaddr - record audit data for sys_bind, sys_connect, sys_sendto
> + * @len: data length in user space
> + * @a: data address in kernel space
> + *
> + * Returns 0 for success or NULL context or < 0 on error.
> + */
>  int audit_sockaddr(int len, void *a)
>  {
>  	struct audit_aux_data_sockaddr *ax;
> @@ -1258,6 +1356,15 @@ int audit_sockaddr(int len, void *a)
>  	return 0;
>  }
>  
> +/**
> + * audit_avc_path - record the granting or denial of permissions
> + * @dentry: dentry to record
> + * @mnt: mnt to record
> + *
> + * Returns 0 for success or NULL context or < 0 on error.
> + *
> + * Called from security/selinux/avc.c::avc_audit()
> + */
>  int audit_avc_path(struct dentry *dentry, struct vfsmount *mnt)
>  {
>  	struct audit_aux_data_path *ax;
> @@ -1279,6 +1386,14 @@ int audit_avc_path(struct dentry *dentry
>  	return 0;
>  }
>  
> +/**
> + * audit_signal_info - record signal info for shutting down audit subsystem
> + * @sig: signal value
> + * @t: task being signaled
> + *
> + * If the audit subsystem is being terminated, record the task (pid)
> + * and uid that is doing that.
> + */
>  void audit_signal_info(int sig, struct task_struct *t)
>  {
>  	extern pid_t audit_sig_pid;
> @@ -1295,4 +1410,3 @@ void audit_signal_info(int sig, struct t
>  		}
>  	}
>  }
> -
> 
> --
> Linux-audit mailing list
> Linux-audit redhat com
> http://www.redhat.com/mailman/listinfo/linux-audit
> 
> 


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]