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 27This describes some private interfaces currently provided by praudit. 28In the future these may be provided by libbsm instead. Note that 29these interfaces are MT-Safe. 30 31 32NAME 33 print_audit, print_audit_buf - format and print audit trail data 34 print_audit_xml_prolog, 35 print_audit_xml_ending, 36 print_audit_xml_prolog_buf, 37 print_audit_xml_ending_buf - print audit XML prolog and ending 38 39SYNOPSIS 40 int print_audit(const int flags, const char *separator); 41 42 int print_audit_buf(char **in_buf, int *in_buf_len, char **out_buf, 43 int *out_buf_len, const int flags, const char *separator); 44 45 void print_audit_xml_prolog(void); 46 void print_audit_xml_ending(void); 47 int print_audit_xml_prolog_buf(char *out_buf, const int out_buf_len); 48 int print_audit_xml_ending_buf(char *out_buf, const int out_buf_len); 49 50DESCRIPTION 51 print_audit() formats binary audit data from stdin and prints in 52 ASCII on stdout. print_audit_buf() formats binary audit data from 53 in_buf and copies in ASCII to out_buf, terminating with a null 54 byte. 55 56 print_audit_xml_prolog and print_audit_xml_prolog_buf will print 57 only the audit XML prolog. The XML, prolog includes identification 58 of the DTD which is used to parse the XML, and also identifies the 59 stylesheet which is used to view the XML conveniently (for example 60 in a browser which supports these features). 61 62 print_audit_xml_ending and print_audit_xml_ending_buf print only 63 the XML ending which completes the audit XML. 64 65PARAMETERS 66 flags - specifies the types of formatting to be done: 67 68 PRF_DEFAULTM 69 Default formatting. By default, times, user and group IDs 70 (UIDs and GIDs, respectively) are converted to their ASCII 71 representation. Record type and event fields are converted 72 to their ASCII representation. If any other flags are 73 specified they will override this flag. 74 75 PRF_RAWM 76 Print records in their raw form. Times, UIDs, GIDs, 77 record types, and events are displayed as integers. 78 This value and PRF_SHORTM are exclusive. If both 79 are used, no processing is done and EINVAL is returned. 80 81 PRF_SHORTM 82 Print records in their short form. All numeric fields 83 are converted to ASCII and displayed. The short ASCII 84 representations for the record type and event fields 85 are used. This value an PRF_RAWM are exclusive. If 86 both are used, no processing is done and EINVAL is returned. 87 88 PRF_XMLM 89 Print records in XML format. "tags" are included in the 90 output to identify tokens and fields within tokens. 91 Output will not include an XML prolog or ending which 92 are required to from complete, valid XML. The various 93 print XML prolog and ending functions described here 94 must be used separately from print_audit and print_audit_buf 95 to accomplish that. 96 97 PRF_ONELINE 98 Prints one line per record. The record type and event 99 fields are always converted to their short ASCII 100 representation as is done for the -s option. 101 102 103 separator - 104 if non-NULL, this is used as the field delimiter instead of the 105 default delimiter, which is the comma. The maximum size of a 106 delimiter is three characters (not counting the required 107 null-terminator). Note that the delimiter is not meaningful 108 and this parameter is ignored when flags specifies XML format. 109 110 in_buf, in_buf_len, 111 out_buf, out_buf_len - 112 pointers to the start of input and output buffers and their lengths. 113 See Return Values for details about how these are used. 114 115 116RETURN VALUES 117 print_audit() and print_audit_buf() return: 118 0 on success. 119 -1 on failure and set errno to indicate the error: 120 121 EINVAL - invalid input flags, delimiter, or error parsing the 122 binary audit data. 123 124 ENOSPC - output buffer too small. 125 126 EIO - input exhausted before end of an audit record. 127 128 EPERM - internal or other unexpected error. 129 130 Partial results may also be returned for these errors. 131 132 133 The following parameters are always returned: 134 135 out_buf_len - 136 137 updated to reflect size of output successfully produced. If 138 non-zero, this will include the single terminating null byte. 139 140 141 Upon return of partial results, these parameters will also be 142 updated to reflect status (up to the end of the last completed 143 audit record from the input): 144 145 in_buf, in_buf_len - 146 147 updated to reflect amount of input successfully consumed. in_buf 148 will point to the next byte which has not been processed. 149 in_buf_len will be set to the remaining size from this address to 150 the end of the original buffer. 151 152 153 print_audit_xml_prolog_buf and print_audit_xml_ending_buf return: 154 0 on success. 155 -1 on failure and set errno to indicate the error: 156 157 ENOSPC - output buffer too small. 158 159 160EXAMPLES 161 The following code fragment takes audit input from stdin, and 162 will print on stdout complete XML including a prolog: 163 164 print_audit_xml_prolog(); 165 166 /* 167 * Format audit data from stdin and print to stdout. 168 */ 169 retstat = print_audit(PRF_XMLM | PRF_ONELINE, NULL); 170 171 if (retstat == 0) 172 print_audit_xml_ending(); 173 174 175