1.\"
2.\" Copyright (c) 2006 Christian S.J. Peron
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\"
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 APPLE AND ITS 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 APPLE OR ITS CONTRIBUTORS BE LIABLE FOR
19.\" 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,
23.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
24.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25.\" POSSIBILITY OF SUCH DAMAGE.
26.\"
27.Dd January 18, 2008
28.Dt AUDIT_SUBMIT 3
29.Os
30.Sh NAME
31.Nm audit_submit
32.Nd "general purpose audit record submission"
33.Sh LIBRARY
34.Lb libbsm
35.Sh SYNOPSIS
36.In bsm/libbsm.h
37.Ft int
38.Fo audit_submit
39.Fa "short au_event" "au_id_t auid" "char status"
40.Fa "int reterr" "const char * restrict format" ...
41.Fc
42.Sh DESCRIPTION
43The
44.Fn audit_submit
45function provides a generic programming interface for audit record submission.
46This audit record will contain a header, subject token, an optional text token,
47return token, and a trailer.
48The header will contain the event class specified by
49.Fa au_event .
50The subject token will be generated based on
51.Fa auid .
52The return token is dependent on the
53.Fa status
54and
55.Fa reterr
56arguments; unlike the argument to
57.Xr au_to_return ,
58.Fa reterr
59should be a local rather than BSM error number.
60Optionally, a text token will be created as a part of this record.
61.Pp
62Text token output is under the control of a
63.Fa format
64string that specifies how subsequent arguments (or arguments accessed via the
65variable-length argument facilities of
66.Xr stdarg 3 )
67are converted for output.
68If
69.Fa format
70is
71.Dv NULL ,
72then no text token is created in the audit record.
73.Pp
74It should be noted that
75.Fn audit_submit
76assumes that
77.Xr setaudit 2 ,
78or
79.Xr setaudit_addr 2
80has already been called.
81As a direct result, the terminal ID for the
82subject will be retrieved from the kernel via
83.Xr getaudit 2 ,
84or
85.Xr getaudit_addr 2 .
86.Sh RETURN VALUES
87If successful,
88.Nm
89will return zero.
90Otherwise a -1 is returned and the global variable
91.Va errno
92is set to indicate the error.
93.Sh EXAMPLES
94.Bd -literal -offset indent
95#include <bsm/audit.h>
96#include <bsm/libbsm.h>
97#include <bsm/audit_uevents.h>
98
99#include <stdio.h>
100#include <stdarg.h>
101#include <errno.h>
102
103void
104audit_bad_su(char *from_login, char *to_login)
105{
106	struct auditinfo_addr aia;
107	struct auditinfo ai;
108	au_id_t aid;
109	int error;
110
111	error = getaudit_addr(&aia, sizeof(aia));
112	if (error < 0 && errno == ENOSYS) {
113		error = getaudit(&ai);
114		if (error < 0)
115			err(1, "getaudit");
116		aid = ai.ai_auid;
117	} else if (error < 0)
118		err(1, "getaudit_addr");
119	else
120		aid = aia.ai_auid;
121	error = audit_submit(AUE_su, aid, EPERM, 1,
122	    "bad su from %s to %s", from_login, to_login);
123	if (error != 0)
124		err(1, "audit_submit");
125}
126.Ed
127.Pp
128Will generate the following audit record:
129.Bd -literal -offset indent
130header,94,1,su(1),0,Mon Apr 17 23:23:59 2006, + 271 msec
131subject,root,root,wheel,root,wheel,652,652,0,0.0.0.0
132text,bad su from from csjp to root
133return,failure : Operation not permitted,1
134trailer,94
135.Ed
136.Sh SEE ALSO
137.Xr auditon 2 ,
138.Xr getaudit 2 ,
139.Xr libbsm 3 ,
140.Xr stdarg 3
141.Sh HISTORY
142The
143.Fn audit_submit
144function first appeared in OpenBSM version 1.0.
145OpenBSM 1.0 was introduced in
146.Fx 7.0 .
147.Sh AUTHORS
148The
149.Fn audit_submit
150function was written by
151.An Christian S.J. Peron Aq csjp@FreeBSD.org .
152