X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/b0d623f7f2ae71ed96e60569f61f9a9a27016e80..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/bsd/man/man2/setaudit_addr.2?ds=inline diff --git a/bsd/man/man2/setaudit_addr.2 b/bsd/man/man2/setaudit_addr.2 index f11b4169f..d6b48c4d5 100644 --- a/bsd/man/man2/setaudit_addr.2 +++ b/bsd/man/man2/setaudit_addr.2 @@ -1 +1,253 @@ -.so man2/setaudit.2 +.\" +.\" Copyright (c) 2008-2011 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 4, 2011 +.Dt SETAUDIT_ADDR 2 +.Os +.Sh NAME +.Nm setaudit_addr , +.Nm setaudit(NOW DEPRECATED) +.Nd "set audit session state" +.Sh SYNOPSIS +.In bsm/audit.h +.In bsm/audit_session.h +.Ft int +.Fn setaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length" +.Sh SYNOPSIS (NOW DEPRECATED) +.In bsm/audit.h +.Ft int +.Fn setaudit "auditinfo_t *auditinfo" +.Sh DESCRIPTION +The +.Fn setaudit_addr +system call +uses the +.Fa auditinfo_addr_t +data structure for the +.Fa auditinfo_addr +argument which supports Terminal IDs with large 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. 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_tid_addr_t +data structure 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. 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 the +.Fa ai_asid +field on success. +.Pp +The +.Fa ai_flags +field is opaque to the kernel and can be used to store flags associated +with the audit session. Please see the +.Ao Pa bsm/audit_session.h Ac +header file +for more infomration and flag definitions for this platform. +.Pp +The +.Fa setaudit_addr +system call require an appropriate privilege to complete. +.Pp +This system call 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. +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 +or +.Fa ai_termid +fields once set to something other than the default values. +The +.Fa ai_flags +field may be updated only according to local access control +policy but this is usually accomplished with +.Xr auditon 2 +using the A_SETSFLAGS command. +The audit preselection masks may be changed at any time +but are usually updated with +.Xr auditon 2 +.Pp +The +.Fn setaudit +system call (NOW DEPRECATED) +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 (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 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. +.Pp +.Fn setaudit_addr +replaced +.Fn setaudit +in Mac OS X 10.7 to support longer terminal addresses such as those used +by IP version 6. +.Fn setaudit +is now deprecated and +.Fn setaudit_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 .