.\"
-.\" Copyright (c) 2007 Apple Inc. All rights reserved.
+.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\"
.\"
.\" @APPLE_LICENSE_HEADER_END@
.\"
-.Dd July 30, 2007
+.Dd March 23, 2009
.Dt SETAUDIT 2
-.Os Darwin
+.Os
.Sh NAME
-.Nm setaudit
-.Nd set the audit information for the current process
+.Nm setaudit ,
+.Nm setaudit_addr
+.Nd "set audit session state"
.Sh SYNOPSIS
-.Fd #include <bsm/audit.h>
+.In bsm/audit.h
.Ft int
-.Fn setaudit "const struct auditinfo * auditinfo"
+.Fn setaudit "auditinfo_t *auditinfo"
+.Ft int
+.Fn setaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
.Sh DESCRIPTION
The
.Fn setaudit
-function sets the audit information for the current process.
-.Fa auditinfo
-should point at a
-.Fa struct auditinfo
-describing the requested user audit settings.
+system call
+sets the active audit session state for the current process via the
+.Vt auditinfo_t
+pointed to by
+.Fa auditinfo .
+The
+.Fn setaudit_addr
+system call
+sets extended state via
+.Fa auditinfo_addr
+and
+.Fa length .
+.Pp
+The
+.Fa auditinfo_t
+data structure is defined as follows:
+.nf
+.in +4n
+
+struct auditinfo {
+ au_id_t ai_auid; /* Audit user ID */
+ au_mask_t ai_mask; /* Audit masks */
+ au_tid_t ai_termid; /* Terminal ID */
+ au_asid_t ai_asid; /* Audit session ID */
+};
+typedef struct auditinfo auditinfo_t;
+.in
+.fi
+.Pp
+The
+.Fa ai_auid
+variable contains the audit identifier which is recorded in the audit log for
+each event the process caused.
+The value of AU_DEFAUDITID (-1) should not be used.
+The exception is if the value of audit identifier is known at the
+start of the session but will be determined and set later.
+Until
+.Fa ai_auid
+is set to something other than AU_DEFAUDITID any audit events
+generated by the system with be filtered by the non-attributed audit
+mask.
+.PP
+
+The
+.Fa au_mask_t
+data structure defines the bit mask for auditing successful and failed events
+out of the predefined list of event classes. It is defined as follows:
+.nf
+.in +4n
+
+struct au_mask {
+ unsigned int am_success; /* success bits */
+ unsigned int am_failure; /* failure bits */
+};
+typedef struct au_mask au_mask_t;
+.in
+.fi
+.PP
+
+The
+.Fa au_termid_t
+data structure defines the Terminal ID recorded with every event caused by the
+process. It is defined as follows:
+.nf
+.in +4n
+
+struct au_tid {
+ dev_t port;
+ u_int32_t machine;
+};
+typedef struct au_tid au_tid_t;
+
+.in
+.fi
+.PP
+The
+.Fa ai_asid
+variable contains the audit session ID which is recorded with every event
+caused by the process. It can be any value in the range 1 to PID_MAX (99999).
+If the value of AU_ASSIGN_ASID is used for
+.Fa ai_asid
+a unique session ID will be generated by the kernel.
+The audit session ID will be returned in
+.Fa ai_asid
+field on success.
+.Pp
+The
+.Fn setaudit_addr
+system call
+uses the expanded
+.Fa auditinfo_addr_t
+data structure supports Terminal IDs with larger addresses such as those used
+in IP version 6. It is defined as follows:
+.nf
+.in +4n
+
+struct auditinfo_addr {
+ au_id_t ai_auid; /* Audit user ID. */
+ au_mask_t ai_mask; /* Audit masks. */
+ au_tid_addr_t ai_termid; /* Terminal ID. */
+ au_asid_t ai_asid; /* Audit session ID. */
+ u_int64_t ai_flags; /* Audit session flags */
+};
+typedef struct auditinfo_addr auditinfo_addr_t;
+.in
+.fi
+.Pp
+The
+.Fa au_tid_addr_t
+data structure which includes a larger address storage field and an additional
+field with the type of address stored:
+.nf
+.in +4n
+
+struct au_tid_addr {
+ dev_t at_port;
+ u_int32_t at_type;
+ u_int32_t at_addr[4];
+};
+typedef struct au_tid_addr au_tid_addr_t;
+.in
+.fi
+.Pp
+The
+.Fa ai_flags
+field is opaque to the kernel and can be used to store user
+defined session flags.
+.Pp
+These system calls require an appropriate privilege to complete.
+.Pp
+These system calls should only be called once at the start of a new
+session and not again during the same session to update the session
+information.
+There are some exceptions, however.
+The
+.Fa ai_auid
+field may be updated later if initially set to the value of
+AU_DEFAUDITID (-1).
+Likewise, the
+.Fa ai_termid
+fields may be updated later if the
+.Fa at_type
+field in
+.Fa au_tid_addr
+is set to AU_IPv4 and the other
+.Fa ai_tid_addr
+fields are all set to zero.
+The
+.Fa ai_flags
+field can only be set when a new session is initially created.
+Creating a new session is done by setting the
+.Fa ai_asid
+field to an unique session value or AU_ASSIGN_ASID.
+These system calls will fail when attempting to change the
+.Fa ai_auid ,
+.Fa ai_termid ,
+or
+.Fa ai_flags
+fields once set to something other than the default values.
+The audit preselection masks may be changed at any time
+but are usually updated with
+.Xr auditon 2
+using the A_SETPMASK command.
.Sh RETURN VALUES
-Upon successful completion a value of 0 is returned.
-Otherwise, a value of -1 is returned and
-.Va errno
-is set to indicate the error.
+.Rv -std setaudit setaudit_addr
+.Sh ERRORS
+.Bl -tag -width Er
+.It Bq Er EFAULT
+A failure occurred while data transferred to or from
+the kernel failed.
+.It Bq Er EINVAL
+Illegal argument was passed by a system call.
+.It Bq Er EPERM
+The process does not have sufficient permission to complete
+the operation.
+.El
.Sh SEE ALSO
.Xr audit 2 ,
.Xr auditon 2 ,
-.Xr auditctl 2 ,
+.Xr getaudit 2 ,
.Xr getauid 2 ,
.Xr setauid 2 ,
-.Xr getaudit 2
+.Xr libbsm 3
.Sh HISTORY
-The
-.Fn setaudit
-function call first appeared in Mac OS X 10.3 (Panther).
+The OpenBSM implementation was created by McAfee Research, the security
+division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
+It was subsequently adopted by the TrustedBSD Project as the foundation for
+the OpenBSM distribution.
+.Sh AUTHORS
+.An -nosplit
+This software was created by McAfee Research, the security research division
+of McAfee, Inc., under contract to Apple Computer Inc.
+Additional authors include
+.An Wayne Salamon ,
+.An Robert Watson ,
+and SPARTA Inc.
+.Pp
+The Basic Security Module (BSM) interface to audit records and audit event
+stream format were defined by Sun Microsystems.
+.Pp
+This manual page was written by
+.An Robert Watson Aq rwatson@FreeBSD.org
+and
+.An Stacey Son Aq sson@FreeBSD.org .
projects / apple / xnu.git / blobdiff