xref: /freebsd/contrib/openbsm/man/getaudit.2 (revision 0957b409)
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.Dd October 19, 2008
28.Dt GETAUDIT 2
29.Os
30.Sh NAME
31.Nm getaudit ,
32.Nm getaudit_addr
33.Nd "retrieve audit session state"
34.Sh SYNOPSIS
35.In bsm/audit.h
36.Ft int
37.Fn getaudit "auditinfo_t *auditinfo"
38.Ft int
39.Fn getaudit_addr "auditinfo_addr_t *auditinfo_addr" "u_int length"
40.Sh DESCRIPTION
41The
42.Fn getaudit
43system call
44retrieves the active audit session state for the current process via the
45.Vt auditinfo_t
46pointed to by
47.Fa auditinfo .
48The
49.Fn getaudit_addr
50system call
51retrieves extended state via
52.Fa auditinfo_addr
53and
54.Fa length .
55.Pp
56The
57.Fa auditinfo_t
58data structure is defined as follows:
59.Bd -literal -offset indent
60struct auditinfo {
61	au_id_t        ai_auid;         /* Audit user ID */
62	au_mask_t      ai_mask;         /* Audit masks */
63	au_tid_t       ai_termid;       /* Terminal ID */
64	au_asid_t      ai_asid;         /* Audit session ID */
65};
66typedef struct auditinfo        auditinfo_t;
67.Ed
68.Pp
69The
70.Fa ai_auid
71variable contains the audit identifier which is recorded in the audit log for
72each event the process caused.
73.Pp
74The
75.Fa au_mask_t
76data structure defines the bit mask for auditing successful and failed events
77out of the predefined list of event classes.
78It is defined as follows:
79.Bd -literal -offset indent
80struct au_mask {
81	unsigned int    am_success;     /* success bits */
82	unsigned int    am_failure;     /* failure bits */
83};
84typedef struct au_mask  au_mask_t;
85.Ed
86.Pp
87The
88.Fa au_termid_t
89data structure defines the Terminal ID recorded with every event caused by the
90process.
91It is defined as follows:
92.Bd -literal -offset indent
93struct au_tid {
94	dev_t           port;
95	u_int32_t       machine;
96};
97typedef struct au_tid   au_tid_t;
98.Ed
99.Pp
100The
101.Fa ai_asid
102variable contains the audit session ID which is recorded with every event
103caused by the process.
104.Pp
105The
106.Fn getaudit_addr
107system call
108uses the expanded
109.Fa auditinfo_addr_t
110data structure and supports Terminal IDs with larger addresses
111such as those used in IP version 6.
112It is defined as follows:
113.Bd -literal -offset indent
114struct auditinfo_addr {
115	au_id_t         ai_auid;        /* Audit user ID. */
116	au_mask_t       ai_mask;        /* Audit masks. */
117	au_tid_addr_t   ai_termid;      /* Terminal ID. */
118	au_asid_t       ai_asid;        /* Audit session ID. */
119};
120typedef struct auditinfo_addr   auditinfo_addr_t;
121.Ed
122.Pp
123The
124.Fa au_tid_addr_t
125data structure which includes a larger address storage field and an additional
126field with the type of address stored:
127.Bd -literal -offset indent
128struct au_tid_addr {
129	dev_t           at_port;
130	u_int32_t       at_type;
131	u_int32_t       at_addr[4];
132};
133typedef struct au_tid_addr      au_tid_addr_t;
134.Ed
135.Pp
136These system calls require an appropriate privilege to complete.
137.Sh RETURN VALUES
138.Rv -std getaudit getaudit_addr
139.Sh ERRORS
140The
141.Fn getaudit
142function will fail if:
143.Bl -tag -width Er
144.It Bq Er EFAULT
145A failure occurred while data transferred to or from
146the kernel failed.
147.It Bq Er EINVAL
148Illegal argument was passed by a system call.
149.It Bq Er EPERM
150The process does not have sufficient permission to complete
151the operation.
152.It Bq Er EOVERFLOW
153The
154.Fa length
155argument indicates an overflow condition will occur.
156.It Bq Er E2BIG
157The address is too big and, therefore,
158.Fn getaudit_addr
159should be used instead.
160.El
161.Sh SEE ALSO
162.Xr audit 2 ,
163.Xr auditon 2 ,
164.Xr getauid 2 ,
165.Xr setaudit 2 ,
166.Xr setauid 2 ,
167.Xr libbsm 3
168.Sh HISTORY
169The OpenBSM implementation was created by McAfee Research, the security
170division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
171It was subsequently adopted by the TrustedBSD Project as the foundation for
172the OpenBSM distribution.
173.Sh AUTHORS
174.An -nosplit
175This software was created by McAfee Research, the security research division
176of McAfee, Inc., under contract to Apple Computer Inc.
177Additional authors include
178.An Wayne Salamon ,
179.An Robert Watson ,
180and SPARTA Inc.
181.Pp
182The Basic Security Module (BSM) interface to audit records and audit event
183stream format were defined by Sun Microsystems.
184.Pp
185This manual page was written by
186.An Robert Watson Aq rwatson@FreeBSD.org .
187