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