1/* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22/* 23 * Copyright 2002 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27#pragma ident "%Z%%M% %I% %E% SMI" 28 29This describes some private interfaces currently provided by praudit. 30In the future these may be provided by libbsm instead. Note that 31these interfaces are MT-Safe. 32 33 34NAME 35 print_audit, print_audit_buf - format and print audit trail data 36 print_audit_xml_prolog, 37 print_audit_xml_ending, 38 print_audit_xml_prolog_buf, 39 print_audit_xml_ending_buf - print audit XML prolog and ending 40 41SYNOPSIS 42 int print_audit(const int flags, const char *separator); 43 44 int print_audit_buf(char **in_buf, int *in_buf_len, char **out_buf, 45 int *out_buf_len, const int flags, const char *separator); 46 47 void print_audit_xml_prolog(void); 48 void print_audit_xml_ending(void); 49 int print_audit_xml_prolog_buf(char *out_buf, const int out_buf_len); 50 int print_audit_xml_ending_buf(char *out_buf, const int out_buf_len); 51 52DESCRIPTION 53 print_audit() formats binary audit data from stdin and prints in 54 ASCII on stdout. print_audit_buf() formats binary audit data from 55 in_buf and copies in ASCII to out_buf, terminating with a null 56 byte. 57 58 print_audit_xml_prolog and print_audit_xml_prolog_buf will print 59 only the audit XML prolog. The XML, prolog includes identification 60 of the DTD which is used to parse the XML, and also identifies the 61 stylesheet which is used to view the XML conveniently (for example 62 in a browser which supports these features). 63 64 print_audit_xml_ending and print_audit_xml_ending_buf print only 65 the XML ending which completes the audit XML. 66 67PARAMETERS 68 flags - specifies the types of formatting to be done: 69 70 PRF_DEFAULTM 71 Default formatting. By default, times, user and group IDs 72 (UIDs and GIDs, respectively) are converted to their ASCII 73 representation. Record type and event fields are converted 74 to their ASCII representation. If any other flags are 75 specified they will override this flag. 76 77 PRF_RAWM 78 Print records in their raw form. Times, UIDs, GIDs, 79 record types, and events are displayed as integers. 80 This value and PRF_SHORTM are exclusive. If both 81 are used, no processing is done and EINVAL is returned. 82 83 PRF_SHORTM 84 Print records in their short form. All numeric fields 85 are converted to ASCII and displayed. The short ASCII 86 representations for the record type and event fields 87 are used. This value an PRF_RAWM are exclusive. If 88 both are used, no processing is done and EINVAL is returned. 89 90 PRF_XMLM 91 Print records in XML format. "tags" are included in the 92 output to identify tokens and fields within tokens. 93 Output will not include an XML prolog or ending which 94 are required to from complete, valid XML. The various 95 print XML prolog and ending functions described here 96 must be used separately from print_audit and print_audit_buf 97 to accomplish that. 98 99 PRF_ONELINE 100 Prints one line per record. The record type and event 101 fields are always converted to their short ASCII 102 representation as is done for the -s option. 103 104 105 separator - 106 if non-NULL, this is used as the field delimiter instead of the 107 default delimiter, which is the comma. The maximum size of a 108 delimiter is three characters (not counting the required 109 null-terminator). Note that the delimiter is not meaningful 110 and this parameter is ignored when flags specifies XML format. 111 112 in_buf, in_buf_len, 113 out_buf, out_buf_len - 114 pointers to the start of input and output buffers and their lengths. 115 See Return Values for details about how these are used. 116 117 118RETURN VALUES 119 print_audit() and print_audit_buf() return: 120 0 on success. 121 -1 on failure and set errno to indicate the error: 122 123 EINVAL - invalid input flags, delimiter, or error parsing the 124 binary audit data. 125 126 ENOSPC - output buffer too small. 127 128 EIO - input exhausted before end of an audit record. 129 130 EPERM - internal or other unexpected error. 131 132 Partial results may also be returned for these errors. 133 134 135 The following parameters are always returned: 136 137 out_buf_len - 138 139 updated to reflect size of output successfully produced. If 140 non-zero, this will include the single terminating null byte. 141 142 143 Upon return of partial results, these parameters will also be 144 updated to reflect status (up to the end of the last completed 145 audit record from the input): 146 147 in_buf, in_buf_len - 148 149 updated to reflect amount of input successfully consumed. in_buf 150 will point to the next byte which has not been processed. 151 in_buf_len will be set to the remaining size from this address to 152 the end of the original buffer. 153 154 155 print_audit_xml_prolog_buf and print_audit_xml_ending_buf return: 156 0 on success. 157 -1 on failure and set errno to indicate the error: 158 159 ENOSPC - output buffer too small. 160 161 162EXAMPLES 163 The following code fragment takes audit input from stdin, and 164 will print on stdout complete XML including a prolog: 165 166 print_audit_xml_prolog(); 167 168 /* 169 * Format audit data from stdin and print to stdout. 170 */ 171 retstat = print_audit(PRF_XMLM | PRF_ONELINE, NULL); 172 173 if (retstat == 0) 174 print_audit_xml_ending(); 175 176 177