]> git.saurik.com Git - apple/xnu.git/blobdiff - bsd/man/man2/getaudit_addr.2
xnu-2782.30.5.tar.gz
[apple/xnu.git] / bsd / man / man2 / getaudit_addr.2
index 25e765cd575e8e16dbd8fc66523372075218980f..26a349b25e829d73fecb83277a84754d85ac6432 100644 (file)
@@ -1 +1,214 @@
-.so man2/getaudit.2
+.\"
+.\" Copyright (c) 2008-2011 Apple Inc. All rights reserved.
+.\"
+.\" @APPLE_OSREFERENCE_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. The rights granted to you under the License
+.\" may not be used to create, or enable the creation or redistribution of,
+.\" unlawful or unlicensed copies of an Apple operating system, or to
+.\" circumvent, violate, or enable the circumvention or violation of, any
+.\" terms of an Apple operating system software license agreement.
+.\"
+.\" 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_OSREFERENCE_LICENSE_HEADER_END@
+.\"
+.Dd March 6, 2011
+.Dt GETAUDIT_ADDR 2
+.Os
+.Sh NAME
+.Nm getaudit_addr ,
+.Nm getaudit(NOW DEPRECATED)
+.Nd "retrieve audit session state"
+.Sh SYNOPSIS
+.In bsm/audit.h
+.In bsm/audit_session.h
+.Ft int
+.Fn getaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
+.Sh SYNOPSIS (NOW DEPRECATED)
+.In bsm/audit.h
+.Ft int
+.Fn getaudit "auditinfo_t *auditinfo"
+.Sh DESCRIPTION
+The
+.Fn getaudit_addr
+system call
+retrieves extended state via
+.Fa auditinfo_addr
+and
+.Fa length .
+It
+uses the
+.Fa auditinfo_addr_t
+data structure supports Terminal IDs incuding those 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 ai_auid
+variable contains the audit identifier which is recorded in the audit log for
+each event the process caused.
+.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_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_asid
+variable contains the audit session ID which is recorded with every event
+caused by the process.
+.Pp
+The
+.Fa ai_flags
+variable contains flags that are opaque to the kernel and used by various
+consumers of the
+.Fa auditinfo_addr
+data.  Please see the
+.Ao Pa bsm/audit_session.h Ac
+header file for more information
+and flag definitions for this platform.
+.Pp
+Without appropriate privilege the audit mask fields will be set to all
+ones.
+.Pp
+The
+.Fn getaudit
+system call (NOW DEPRECATED)
+retrieves the active audit session state for the current process via the
+.Vt auditinfo_t
+pointed to by
+.Fa auditinfo .
+.Pp
+The
+.Fa auditinfo_t
+data structure (NOW DEPRECATED) 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 au_termid_t
+data structure (NOW DEPRECATED) 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
+.Sh RETURN VALUES
+.Rv -std getaudit_addr
+.Sh ERRORS
+The
+.Fn getaudit_addr
+function will fail if:
+.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 EOVERFLOW
+The
+.Fa length
+argument indicates an overflow condition will occur.
+.It Bq Er ERANGE
+The address is too big.
+.El
+.Sh SEE ALSO
+.Xr audit 2 ,
+.Xr auditon 2 ,
+.Xr getauid 2 ,
+.Xr setaudit 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.
+.Pp
+.Fn getaudit_addr
+replaced
+.Fn getaudit
+in Mac OS X 10.7 to support longer terminal addresses such as those used
+by IP version 6.
+.Fn getaudit
+is now deprecated and
+.Fn getaudit_addr
+should be used instead.
+.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 .