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