Man Pages (3), (3C), (3K), (3N), (3R), (3X), (3X11TSOL): Library Functions

auditwrite(3)

NAME

auditwrite- Construct and write user-level audit records

SYNOPSIS

cc

flag

file

-lbsm

-lsocket

-lnsl

-lintl

-ltsol

library

#include <bsm/auditwrite.h>

#include <bsm/audit_uevents.h>

#include <tsol/priv.h>

#include <tsol/label.h>

DESCRIPTION

auditwrite() provides a single-function programmer interface to auditing for user-level programs. The principal features of auditwrite() are audit record construction, audit record queueing, a save area, and support for trusted server auditing. See NOTES for privileges needed to write audit records.

Record Construction

auditwrite() creates complete audit records or appends information to an existing, partial audit record. A single-shot audit record is one that is constructed and written in a single call to auditwrite(). Multi-shot audit records are those constructed piecemeal through two or more calls to auditwrite(). See EXAMPLES.

Record Queuing

Audit records may be queued by specifying a threshold. When the threshold is reached, records are written in one operation. This batching minimizes system-call overhead.

Save Area

A special audit-record buffer may be requested as a save area. Attributes stored in the save area are prepended to every subsequent record written with auditwrite().

Trusted Server Auditing Support

Some trusted servers act on behalf of untrusted client processes performing security checks and providing access to TCB objects. A trusted server must sometimes generate audit records with the audit characteristics of its clients. The AW_SERVER command tells auditwrite() that the caller is a trusted server and that additional information should be added to each audit record if the information has not already been provided.

PARAMETERS

auditwrite() takes a variable number of arguments. Arguments are of three types. One type, referred to as control commands, controls the behavior of auditwrite(). One and only one control command may appear on the auditwrite() invocation line. Another type of argument is an attribute command. Attribute commands describe the attributes that compose an audit record. Control and attribute commands may appear in any order in an auditwrite() invocation. The last type of argument is the terminator command. The terminator command AW_END must be the last argument on the auditwrite invocation line. The terminator command notifies auditwrite when to stop parsing the invocation line.

Control Commands

AW_WRITE: Write to the audit trail the default audit record or the audit record specified by the last AW_USERD command. If queueing is in effect, the record is queued and written when the queue is flushed.
AW_APPEND: Attach one or more record attributes to the end of the record. AW_APPEND is used in the multi-shot construction of an audit record. Attributes are kept in a record buffer until auditwrite() is called with the AW_WRITE command. One or more attribute commands must be specified with the AW_APPEND command.
AW_DEFAULTRD: Use the default record descriptor.
AW_DISCARD: Discard all partial and complete audit records.
AW_DISCARDRD, int rd: Discard the record descriptor specified by rd. An rd of -1 can be specified to discard the default rd.
AW_GETRD, int *rd: Obtain an audit record descriptor for use with AW_USERD.
AW_PRESELECT, au_mask_t *pmask: Preselect audit records according to pmask. Normally audit records are preselected by auditwrite() using the preselection mask in the execution environment. See getaudit(2) for details.
AW_NOPRESELECT: Use the preselection mask in the execution environment instead of the one specified with the AW_PRESELECT command.
AW_QUEUE, u_int hi_water: Turn on audit-record queueing. AW_QUEUE causes auditwrite() to queue all audit records. When the total number of bytes of all queued audit records reaches hi_water, the queue is flushed. The queue may also be flushed at will with AW_FLUSH. The auditwrite() audit-record queue should not be confused with the kernel audit-record queue. The auditwrite() queue is a separate and distinct queue created in user address space. The auditwrite() audit-record queue can minimize system-call overhead by writing several audit records in one operation.
AW_NOQUEUE: Turn off audit-record queueing. Flush the queue.
AW_FLUSH: Flush the audit-record queue.
AW_SAVERD, int *rd: Turn on use of a save area. Attributes stored in the save area are prepended to records before they are written.
AW_NOSAVE: Turn off use of the save area.
AW_SERVER: Turn on the trusted server option. The AW_SERVER command tells auditwrite() that the calling program is a server that must generate complete audit records. auditwrite() adds header and trailer attributes to all records. Sequence and group attributes are also added depending upon the audit policy. See audit(2) for further information on audit policy.
AW_NOSERVER: Turn off the trusted server option.
AW_USERD, int rd: Use the record descriptor obtained with AW_GETRD.

Attribute Commands

Attribute commands describe the attributes that compose an audit record. Attribute commands must be specified with one and only one AW_APPEND or AW_WRITE control command.

AW_ARG, char n, char *text u_long v

Place the specified system call argument information into the audit record. n contains the argument number. text contains a string describing the argument. v contains the value of the argument.

AW_ATTR, mode_t mode, uid_t uid, gid_t gid, dev_t dev, ino_t ino dev_t rdev

Place the specified file system object attribute information into the audit record. You can get this information using the stat(2) system call.

AW_CLEARANCE bclear_t *clear

Place the specified clearance into the audit record. If sensitivity labels are not enabled on this system or if the appropriate audit policy (slabel) from auditon(2) is not enabled on this system, the command is ignored.

AW_DATA, char unit_print, char unit_type, char unit_count caddr_t p

Place the specified arbitrary data into the audit record. unit_print describes how the data should be printed by programs that read the audit trail. These are allowable values for unit_print:

AWD_BINARY

AWD_OCTAL

AWD_DECIMAL

AWD_HEX

AWD_STRING

unit_type describes the type of data in p. These are allowable values for unit_type:

AWD_BYTE

AWD_CHAR

AWD_SHORT

AWD_INT

AWD_LONG

unit_count describes how many elements of unit_type exist in p, which is an address pointing to the data to be written.

AW_EVENT char *event_str

Specify the audit event associated with the audit record. One and only one event must be associated with every audit record. If an attempt is made to write an audit record for which an event has not been specified, auditwrite() returns an error. event_str is any valid user-level audit-event string as defined by audit_event(4).

(AW_EVENT is used for third-party application events. For other events, AW_EVENTNUM should be used if possible, since AW_EVENT incurs additional overhead for string lookup.)

AW_EVENTNUM int event: AW_EVENTNUM is similar to AW_EVENT but takes as its argument any valid event number instead of an event string. To maintain compatibility between third party add-ons, only registered events may use this attribute command. event is any valid audit event defined in audit_event(4) and </usr/include/bsm/audit_uevent.h>. See audit_event(4) for further information on audit-event strings.
AW_EXEC_ARGS
char **argv: Place the specified command line arguments into the audit record. The array is terminated by a null pointer. (The format is the same as that used for argv by an invoking C program.) If the appropriate audit policy (argv) from auditon(2) is not enabled on this system, this call is ignored.
AW_EXEC_ENV
char **envp: Place the specified command-line environment into the audit record. The array is terminated by a null pointer. (This format is the same as that used for envp by an invoking C program.) If the appropriate audit policy (arge) from auditon(2) is not enabled on this system, this call is ignored.
AW_EXIT, int status int errno: Place the specified program exit-status information into the audit record. status contains the exit status of the calling program. errno contains the system error number or an internal error number indicating the cause of the program exit.
AW_GROUPS, int num gid_t *groups: Format and place the elements of the array groups into the audit record. num specifies the number of elements in the array and must be between NGROUPS_UMIN and NGROUPS_UMAX as defined in </usr/include/sys/param.h>. If the audit policy [see auditconfig(1M)] is not configured for including supplementary groups, the command is ignored.

AW_INADDR struct in_addr *in_addr: Place the specified Internet address into the audit record.
AW_IPC, char type, int id: Place the specified interprocess-communications identifier into the audit record. type is one of these values: AT_IPC_MSG, AT_IPC_SEM, AT_IPC_SHM, or AT_IPC_NULL.
AW_IPC_PERM struct ipc_perm *perm: Place the specified interprocess-communications identifier permission information into the audit record.
AW_IPORT, u_short iport: Place the specified IP port into the audit record.
AW_LEVEL, blevel_t *level: Place the specified level into the audit record. If sensitivity labels are not enabled on this system or if the appropriate audit policy (slabel) from auditon(2) is not enabled on this system, the command is ignored.

AW_OPAQUE, caddr_t data short byte_count

Place into the audit record the opaque data to which data points and which has byte_count length.

AW_PATH, char *path

Place the specified path into the audit record. Paths are anchored with the current active root if they do not begin with a slash (/).

AW_PRIVILEGE, priv_set_t *priv_set char settype

Place the specified privilege set into the audit record. These are allowable values for settype:

AU_PRIV_UNKNOWN

AU_PRIV_FORCED

AU_PRIV_ALLOWED

AU_PRIV_EFFECTIVE

AU_PRIV_INHERITABLE

AU_PRIV_PERMITTED

AU_PRIV_SAVED

AW_PROCESS, au_id_t auid, uid_t euid, gid_t egid uid_t ruid, gid_t rgid, pid_t pid, au_asid_t sid au_tid_t *tid

Place the specified process information into the audit record. The AW_PROCESS and AW_SUBJECT attributes record the same information. Use the AW_PROCESS attribute when recording information about a process object. Use the AW_SUBJECT attribute when recording information about a process subject.

AW_RETURN, char number u_int retval

Indicates the success or failure of an audit event. This attribute is used by auditwrite() for preselection, and by the auditreduce(1M) post-selection program to select audit records according to success or failure.

number indicates the success or failure of the event. Failure is denoted by a nonzero number value. Positive values are interpreted by praudit(1M) as errno values. Corresponding error strings are printed. Negative values indicate a general failure specific to the audit event. Success is denoted by a zero number value. retval indicates the return value or status value of the successful or failed function or program.

AW_SLABEL, bslabel_t *label: Place the specified sensitivity label into the audit record. If sensitivity labels are not enabled on this system or if the appropriate audit policy (slabel) from auditon(2) is not enabled on this system, the command is ignored.
AW_SOCKET, struct socket *s: Place the specified socket information into the audit record.

AW_SUBJECT, au_id_t auid, uid_t euid, gid_t egid uid_t ruid, gid_t rgid, pid_t pid, au_aside_t sid au_tid_t *tid: Place the specified subject information into the audit record. The AW_PROCESS and AW_SUBJECT attributes record the same information. Use the AW_PROCESS attribute when recording information about a process object. Use the AW_SUBJECT attribute when recording information about a process subject.
AW_TEXT, char *text: Place the specified null-terminated string text into the audit record.
AW_USEOFPRIV, char flag priv_t priv: Place a flag and a single privilege into the audit record denoting an attempted use of privilege. flag indicates success (1) or failure (0) of the attempt. priv indicates the privilege upon which the attempt was made.
AW_XATOM char *atom_string: Place the specified X atom string into the audit record.
AW_XCOLORMAP, u_long xid uid_t creator_uid: Place the specified X colormap information into the audit record.
AW_XCLIENT u_long clientid: Place the specified X client ID into the audit record.
AW_XCURSOR, u_long xid uid_t creator_uid: Place the specified X cursor information into the audit record.
AW_XFONT, u_long xid uid_t creator_uid: Place the specified X font information into the audit record.
AW_XGC, u_long xid uid_t creator_uid: Place the specified X gc information into the audit record.
AW_XPIXMAP, u_long xid uid_t creator_uid: Place the specified X pixel-mapping information into the audit record.
AW_XPROPERTY, u_long xid, uid_t creator_uid, char *atom_name: Place the specified X property information into the audit record.
AW_XSELECT, char *property_string, char *property_type, char *window_data: Place the specified X select information into the audit record.
AW_XWINDOW, u_long xid, uid_t creator_uid: Place the specified X window information into the audit record.

Terminator Command

The terminator command AW_END must be the last argument on the auditwrite() invocation line.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsu
MT-Level	MT-Safe

RETURN VALUES

auditwrite() returns:

0: On success.
-1: On failure, and sets aw_errno to indicate the error.

ERRORS

When an error is encountered, any whole or partial audit records are immediately written to the audit trail. These include records that may have been queued. In addition, a LOG_ALERT message is sent to syslogd(1M) and an attempt is made to write an auditwrite() "processing error" audit record to the audit trail.

aw_strerror(3) or aw_perror(3) may be used for obtaining the error strings associated with aw_errno.

These are the possible values of aw_errno:

AW_ERR_ADDR_INVALID: An address specified was invalid.
AW_ERR_ALLOC_FAIL: An attempt to allocate memory failed.
AW_ERR_AUDITON_FAIL: The auditon(2) system call failed. See errno for the reason.
AW_ERR_AUDIT_FAIL: The audit(2) system call failed. See errno for the reason.
AW_ERR_CMD_INCOMPLETE: A required command was omitted. This event occurs when AW_APPEND is specified without any attribute commands or vice versa.
AW_ERR_CMD_INVALID: The command specified was not a valid command.
AW_ERR_CMD_IN_EFFECT: A command already in effect, such as AW_QUEUE or AW_SAVERD was specified.
AW_ERR_CMD_NOT_IN_EFFECT: An attempt was made to reverse a command that was not in effect.
AW_ERR_CMD_TOO_MANY: More than one control command was specified.
AW_ERR_EVENT_ID_INVALID: The event ID string passed was not valid.
AW_ERR_EVENT_ID_NOT_SET: An attempt was made to write an audit record without a valid event ID. When this attempt occurs, the event ID is set to a null value and the record is written anyway as a part of error-processing procedure.
AW_ERR_GETAUDIT_FAIL: The getaudit(2) system call failed. See errno for the reason.
AW_ERR_QUEUE_SIZE_INVALID: The specified queue size was greater than the system-imposed maximum audit-record size.
AW_ERR_RD_INVALID: The specified record descriptor was invalid.
AW_ERR_REC_TOO_BIG: An attempt was made to construct an audit record larger than the system-imposed maximum audit record size.
AW_ERR_NO_PLABEL: The process label for the current process could not be obtained; thus a complete record could not be generated.

EXAMPLES

Valid Examples

Example 1 Single-shot record construction

/* Single-shot record construction:
 * Construct an audit record and write the record to the audit trail.
 * Uses the default audit record.
 */
 
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string1, AW_TEXT, "hello", AW_WRITE, AW_END);

Example 2 Multi-shot construction

/* Multi-shot construction:
 * Construct an audit record piecemeal and write the record.
 * Uses the default audit record.
 */
 
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string2, AW_APPEND, AW_END);
(void) auditwrite(AW_TEXT, "part 1", AW_APPEND, AW_END);
(void) auditwrite(AW_TEXT, "part 2", AW_APPEND, AW_END);
(void) auditwrite(AW_RETURN, 0, 0, AW_APPEND, AW_END);
(void) auditwrite(AW_WRITE, AW_END);

Example 3 Multi-shot record construction

/* Multi-shot record construction:
 * Decide upon the return token value when it occurs.
 */
 
(void) auditwrite(AW_EVENTNUM, AUE_ftpd, AW_APPEND, AW_END);
(void) auditwrite(AW_TEXT, "Read access attempt", AW_APPEND, AW_END);
 
if (access_decision() == FALSE) {
        succ_or_fail = -1;
        reason = get_reason;
} else {
        succ_or_fail = 0;
        reason = 0;
}
 
(void) auditwrite(AW_TEXT, "more text", AW_RETURN, succ_or_fail, reason, AW_APPEND, AW_END);
(void) auditwrite(AW_WRITE, AW_END);

Example 4 Queueing

/* Queueing:
 * Turn on queueing, queue two records, then turn off queueing. Queue is flushed
 * automatically when queuing is turned off.
 */
 
(void) auditwrite(AW_QUEUE, 1024, AW_END);
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string3, AW_RETURN, 0, 0, AW_WRITE, AW_END);
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string4, AW_RETURN, 0, 0, AW_WRITE, AW_END);
(void) auditwrite(AW_EVENTNUM, AUE_valid_event_string5, AW_RETURN, 0, 0, AW_APPEND, AW_END);
(void) auditwrite(AW_NOQUEUE, AW_END);

Invalid Examples

Example 5 Only one control command may be specified

/*
 * Invalid command combinations:
 * Only one control command may be specified.
 */
(void) auditwrite(AW_EVENTNUM, valid_event_str, AW_TEXT, "text", AW_DISCARD, AW_WRITE, AW_END);

Example 6 No control command specified

/*
 * Invalid command combinations:
 * No control command specified
 */
(void) auditwrite(AW_TEXT, "text", AW_END);

FILES

/etc/security/audit_event: Used to obtain the mappings between audit event strings and audit event numbers.

Trusted Solaris 7 Reference Manual

auditreduce(1M), praudit(1M), audit(2), getaudit(2), stat(2), audit_event(4), auditconfig(1M), auditon(2)

Trusted Solaris Developer's Guide

SunOS 5.7 Reference Manual

attributes(5)

NOTES

When a subject is not provided, auditwrite() attempts to generate the subject, groups, and (depending on appropriate audit policy) sensitivity label attributes for the current process. This attempt has implications for servers because unless they negotiate to get the AUID, UID, sensitivity label, and groups of the process being served and provide them to auditwrite(), the values recorded will be those of the server process. Programmers of servers should take this circumstance into account when using auditwrite() and make specific requests to auditwrite() to work around this problem.

To write an audit record with an event number from 2048 to 32767, the calling process must have PRIV_PROC_AUDIT_TCB in its set of effective privileges. If the event number is from 32768 to 65535, the calling process must have PRIV_PROC_AUDIT_APPL in its set of effective privileges. These sets of event numbers are the only valid user-level event numbers.

Information labels (ILs) are not supported in Trusted Solaris 7 and later releases. Trusted Solaris software interprets any ILs on communications and files from systems running earlier releases as ADMIN_LOW.

Objects still have CMW labels, and CMW labels still include the IL component: IL[SL]; however, the IL component is fixed at ADMIN_LOW.

As a result, Trusted Solaris 7 has the following characteristics:
- ILs do not display in window labels; SLs (Sensitivity Labels) display alone within brackets.
- ILs do not float.
- Setting an IL on an object has no effect.
- Getting an object's IL will always return ADMIN_LOW.
- Although certain utilities, library functions, and system calls can manipulate IL strings, the resulting ILs are always ADMIN_LOW, and cannot be set on any objects.
- In auditing, the ilabel token is recorded as ADMIN_LOW, when it is recorded. The audit event numbers 519 (AUE_OFLOAT), 520 (AUE_SFLOAT), and 9036 (AUE_iil_change) continue to be reserved, but those events are no longer recorded.

Trusted Solaris 7 Last Revised 30 Sep 1999