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