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