auditwrite(3TSOL)

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | ATTRIBUTES | RETURN VALUES | ERRORS | EXAMPLES | FILES | SEE ALSO | NOTES

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>

int auditwrite(...,AW_END);

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 and for multithreading considerations.

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(). Only one normal control command may appear in a single auditwrite() invocation.

(By default, control commands apply to all record descriptors. AW_USERD is a special control command which can affect command scope and can be used with other control commands; see the AW_USERD command for details.)

Another type of argument is an attribute command. Attribute commands describe the attributes that comprise an audit record. The last type of argument is the terminator command. 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 AW_USERD. 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.

A new record descriptor is obtained and returned in rd, in the same way as AW_GETRD, and this is marked as the active save area.

This descriptor can be used with AW_USERD and AW_APPEND to accumulate attributes in the save area.

AW_SAVERD should not be used on the same call with AW_USERD.

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. This command can be used with other control commands except AW_DEFAULTRD, AW_DISCARD, AW_DISCARDRD, AW_FLUSH, and AW_GETRD.

The record descriptor and any related context is automatically released upon completion of the AW_WRITE command or upon any error.

When used on the same call with other commands, this must be the first argument. This command will limit the scope of the other commands to the specified record descriptor. Subsequent calls are not affected unless they also use AW_USERD with the same descriptor, along with another command.

In this mode, the descriptor is not affected by other auditwrite calls. For instance:

---

auditwrite(AW_PRESELECT, &mymask, AW_END);

auditwrite(AW_USERD, rdn, AW_WRITE, ..., AW_END);

---

The first call will not change the behavior of the second, because the descriptor rdn has its own separate context.

When used as the only command, this changes the scope of AW_WRITE and AW_APPEND commands on all subsequent calls which don't include AW_USERD.

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, uint32_t 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_INT32




AWD_INT64




AWD_INT (This is provided for compatibility but should otherwise not be used. It is the equivalent of AWD_INT32.)




AWD_LONG (This is provided for compatibility but should otherwise not be used. It is the equivalent of AWD_INT32.)




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. (This is provided for compatibility but should otherwise not be used. It is the equivalent of AW_IN_ADDR.)

AW_IN_ADDR, struct in_addr *in_addr

Place the specified Internet address into the audit record.

AW_IN_ADDR_EX, struct in6_addr *in6_addr

Place the specified multi-format 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, and the AW_PROCESS_EX and AW_SUBJECT_EX attributes, record the same information. Use the AW_PROCESS or AW_PROCESS_EX attribute when recording information about a process object. Use the AW_SUBJECT or AW_SUBJECT_EX attribute when recording information about a process subject. AW_PROCESS_EX and AW_SUBJECT_EX are extended forms which support multiple IP address formats in the terminal ID field.

AW_PROCESS_EX, 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. See AW_PROCESS.

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_asid_t sid, au_tid_t *tid

Place the specified subject information into the audit record. See AW_PROCESS.

AW_SUBJECT_EX, 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_addr_t *tid

Place the specified subject information into the audit record. See AW_PROCESS.

AW_TEXT, char *text

Place the specified null-terminated string text into the audit record.

AW_UAUTH, char *auth

Place the specified authorization name 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, uint32_t xid, uid_t creator_uid

Place the specified X colormap information into the audit record.

AW_XCLIENT, uint32_t clientid

Place the specified X client ID into the audit record.

AW_XCURSOR, uint32_t xid, uid_t creator_uid

Place the specified X cursor information into the audit record.

AW_XFONT, uint32_t xid, uid_t creator_uid

Place the specified X font information into the audit record.

AW_XGC, uint32_t xid, uid_t creator_uid

Place the specified X gc information into the audit record.

AW_XPIXMAP, uint32_t xid, uid_t creator_uid

Place the specified X pixel-mapping information into the audit record.

AW_XPROPERTY, uint32_t 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, uint32_t 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. All record descriptors and related context are freed also.

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

When multiple threads may be auditing, aw_errno may not be retrieved in an MT-safe way. In this environment, AW_USERD should be used on all auditwrite calls (after a AW_GETRD call), and aw_geterrno(3TSOL), aw_strerror(3TSOL), and aw_perror_r(3TSOL) should be used to obtain and format error information.

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) or getaudit_addr(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);

---

---

Example 5 Using record descriptors




/*
 * Note that this is not MT-safe; see next example for
 * correct multithreaded code.
 *
 * Note that after the WRITE, the record descriptor is freed.
 * For subsequent auditing the AW_GET needs to be repeated
 * before record appending/writing.
 */
(void) auditwrite(AW_GETRD, &rdn, AW_END);
(void) auditwrite(AW_USERD, rdn, AW_END);

(void) auditwrite(AW_APPEND, AW_TEXT, "part 1", AW_END);
(void) auditwrite(AW_EVENTNUM, event_no,
       AW_WRITE, AW_TEXT, "part 2", AW_END);

---

---

Example 6 Multithreading




/*
 * This approach will be safe even when multiple threads may
 * be auditing...
 *
 * Note that after the WRITE, the record descriptor and all
 * context is freed. For subsequent auditing the entire
 * sequence needs to be repeated: get an rd, set state (such
 * as PRESELECT, SERVER, ...), and record appending/writing.
 */
(void) auditwrite(AW_GETRD, &rdn, AW_END);
(void) auditwrite(AW_USERD, rdn, AW_PRESELECT, &mymask, AW_END);
(void) auditwrite(AW_USERD, rdn, AW_APPEND, AW_TEXT, "part 1", AW_END);
(void) auditwrite(AW_USERD, rdn, AW_EVENTNUM, event_no,
       AW_WRITE, AW_TEXT, "part 2", AW_END);

---

Invalid Examples

---

Example 7 Specify no more than one normal control command




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

---

---

Example 8 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.

SEE ALSO

Trusted Solaris 8 HW 12/02 Reference Manual

auditconfig(1M), auditreduce(1M), praudit(1M), audit(2), auditon(2), getaudit(2), stat(2), aw_geterrno(3TSOL), aw_perror(3TSOL), aw_perror_r(3TSOL), aw_strerror(3TSOL), audit_event(4)

Trusted Solaris Developer's Guide

SunOS 5.8 Reference Manual

attributes(5)

NOTES

These interfaces are uncommitted. Although they are not expected to change between minor releases of the Trusted Solaris environment, they may.

In a multithreading environment where multiple threads may invoke auditwrite, to preserve consistency AW_USERD should be used as the first command on all auditwrite calls (after a AW_GETRD call). Also, aw_errno may not be used directly; see ERRORS for details.

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.

Trusted Solaris 8 HW 12/02  Last Revised 3 Aug 2001

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | ATTRIBUTES | RETURN VALUES | ERRORS | EXAMPLES | FILES | SEE ALSO | NOTES