-.\"
-.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
-.\"
-.\" @APPLE_LICENSE_HEADER_START@
-.\"
-.\" This file contains Original Code and/or Modifications of Original Code
-.\" as defined in and that are subject to the Apple Public Source License
-.\" Version 2.0 (the 'License'). You may not use this file except in
-.\" compliance with the License. Please obtain a copy of the License at
-.\" http://www.opensource.apple.com/apsl/ and read it before using this
-.\" file.
-.\"
-.\" The Original Code and all software distributed under the License are
-.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
-.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
-.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
-.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
-.\" Please see the License for the specific language governing rights and
-.\" limitations under the License.
-.\"
-.\" @APPLE_LICENSE_HEADER_END@
-.\"
-.Dd March 23, 2009
-.Dt SETAUDIT 2
-.Os
-.Sh NAME
-.Nm setaudit ,
-.Nm setaudit_addr
-.Nd "set audit session state"
-.Sh SYNOPSIS
-.In bsm/audit.h
-.Ft int
-.Fn setaudit "auditinfo_t *auditinfo"
-.Ft int
-.Fn setaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
-.Sh DESCRIPTION
-The
-.Fn setaudit
-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
-.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 getaudit 2 ,
-.Xr getauid 2 ,
-.Xr setauid 2 ,
-.Xr libbsm 3
-.Sh HISTORY
-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