xref: /freebsd/contrib/openbsm/man/setaudit.2 (revision 7aa383846770374466b1dcb2cefd71bde9acf463)
1.\"-
2.\" Copyright (c) 2005 Robert N. M. Watson
3.\" Copyright (c) 2008 Apple Inc.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" $P4: //depot/projects/trustedbsd/openbsm/man/setaudit.2#10 $
28.\"
29.Dd April 19, 2005
30.Dt SETAUDIT 2
31.Os
32.Sh NAME
33.Nm setaudit ,
34.Nm setaudit_addr
35.Nd "set audit session state"
36.Sh SYNOPSIS
37.In bsm/audit.h
38.Ft int
39.Fn setaudit "auditinfo_t *auditinfo"
40.Ft int
41.Fn setaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
42.Sh DESCRIPTION
43The
44.Fn setaudit
45system call
46sets the active audit session state for the current process via the
47.Vt auditinfo_t
48pointed to by
49.Fa auditinfo .
50The
51.Fn setaudit_addr
52system call
53sets extended state via
54.Fa auditinfo_addr
55and
56.Fa length .
57.Pp
58The
59.Fa auditinfo_t
60data structure is defined as follows:
61.nf
62.in +4n
63
64struct auditinfo {
65	au_id_t        ai_auid;         /* Audit user ID */
66	au_mask_t      ai_mask;         /* Audit masks */
67	au_tid_t       ai_termid;       /* Terminal ID */
68	au_asid_t      ai_asid;         /* Audit session ID */
69};
70typedef struct auditinfo        auditinfo_t;
71.in
72.fi
73.Pp
74The
75.Fa ai_auid
76variable contains the audit identifier which is recorded in the audit log for
77each event the process caused.
78.PP
79
80The
81.Fa au_mask_t
82data structure defines the bit mask for auditing successful and failed events
83out of the predefined list of event classes. It is defined as follows:
84.nf
85.in +4n
86
87struct au_mask {
88	unsigned int    am_success;     /* success bits */
89	unsigned int    am_failure;     /* failure bits */
90};
91typedef struct au_mask  au_mask_t;
92.in
93.fi
94.PP
95
96The
97.Fa au_termid_t
98data structure defines the Terminal ID recorded with every event caused by the
99process. It is defined as follows:
100.nf
101.in +4n
102
103struct au_tid {
104	dev_t           port;
105	u_int32_t       machine;
106};
107typedef struct au_tid   au_tid_t;
108
109.in
110.fi
111.PP
112The
113.Fa ai_asid
114variable contains the audit session ID which is recorded with every event
115caused by the process.
116.Pp
117The
118.Fn setaudit_addr
119system call
120uses the expanded
121.Fa auditinfo_addr_t
122data structure supports Terminal IDs with larger addresses such as those used
123in IP version 6.  It is defined as follows:
124.nf
125.in +4n
126
127struct auditinfo_addr {
128	au_id_t         ai_auid;        /* Audit user ID. */
129	au_mask_t       ai_mask;        /* Audit masks. */
130	au_tid_addr_t   ai_termid;      /* Terminal ID. */
131	au_asid_t       ai_asid;        /* Audit session ID. */
132};
133typedef struct auditinfo_addr   auditinfo_addr_t;
134.in
135.fi
136.Pp
137The
138.Fa au_tid_addr_t
139data structure which includes a larger address storage field and an additional
140field with the type of address stored:
141.nf
142.in +4n
143
144struct au_tid_addr {
145	dev_t           at_port;
146	u_int32_t       at_type;
147	u_int32_t       at_addr[4];
148};
149typedef struct au_tid_addr      au_tid_addr_t;
150.in
151.fi
152.Pp
153These system calls require an appropriate privilege to complete.
154.Sh RETURN VALUES
155.Rv -std setaudit setaudit_addr
156.Sh ERRORS
157.Bl -tag -width Er
158.It Bq Er EFAULT
159A failure occurred while data transferred to or from
160the kernel failed.
161.It Bq Er EINVAL
162Illegal argument was passed by a system call.
163.It Bq Er EPERM
164The process does not have sufficient permission to complete
165the operation.
166.El
167.Sh SEE ALSO
168.Xr audit 2 ,
169.Xr auditon 2 ,
170.Xr getaudit 2 ,
171.Xr getauid 2 ,
172.Xr setauid 2 ,
173.Xr libbsm 3
174.Sh HISTORY
175The OpenBSM implementation was created by McAfee Research, the security
176division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
177It was subsequently adopted by the TrustedBSD Project as the foundation for
178the OpenBSM distribution.
179.Sh AUTHORS
180.An -nosplit
181This software was created by McAfee Research, the security research division
182of McAfee, Inc., under contract to Apple Computer Inc.
183Additional authors include
184.An Wayne Salamon ,
185.An Robert Watson ,
186and SPARTA Inc.
187.Pp
188The Basic Security Module (BSM) interface to audit records and audit event
189stream format were defined by Sun Microsystems.
190.Pp
191This manual page was written by
192.An Robert Watson Aq rwatson@FreeBSD.org .
193