Creating an Audit Record

An audit record is created by passing one control command and one or more token commands to the auditwrite(3TSOL) routine in one call (AW_WRITE) or several calls (AW_APPEND for each call with AW_WRITE in the last call). An audit record must have an AW_EVENT token and should have an AW_RETURN token to indicate which event occurred and whether the event succeeded or failed. See "Return Token" for more information.

Making Invalid and Valid Calls

These examples show the different audit records logged to the audit trail when a call to the auditwrite(3TSOL) routine is invalid and valid. The structure of audit records and tokens is described in "Token Structure".

Invalid Call

If you use more than one control command, or omit the control command, or do not include the AW_END terminator command, your code compiles and runs and a record is logged to the audit trail to record the invalid call to the auditwrite(3TSOL) routine. Note that the event is logged to the trail only if the process preselection mask audits the AUE_auditwrite event for failure.

This example shows an invalid auditwrite(3TSOL) routine call that omits the AW_END terminator command and the resulting audit record. The header files for the examples in the rest of this chapter are shown in this first program.

#include <bsm/auditwrite.h>
#include <tsol/label.h>
#include <sys/param.h>
#include <bsm/libbsm.h>
#include <tsol/priv.h>

main()
{
/* Invalid call missing AW_END. Do not do it this way. */
	auditwrite(AW_EVENT, "AUE_second_signature", AW_WRITE);
}

An invalid call is logged to syslog, and if the invalid record has enough information, it is also logged to the audit trail. In the example, the invalid call is logged to syslog only with the following information:

header, 194,2,auditwrite routine fail,,Fri Sep 06 10:11:33 1996, 
+ 179 msec text,
auditwrite routine aborted: aw_errno = 6 = Command invalid, errno = 0 
= no such device or address 
subject,zelda,zelda,staff,zelda,staff,1774,348,0 0 phoenix
slabel,C
return,failure,-1

Valid Call

This call to the auditwrite(3TSOL) routine includes the AW_END command and logs the AUE_second_signature event to the audit trail.

/* Valid call that includes AW_END */
auditwrite(AW_EVENT, "AUE_second_signature", AW_WRITE, AW_END);

The viewing terminal shows this record:

header, 4022,2,second signature requested,,Fri Sep 06 
  10:16:49 1996 + 969 msec
subject,zelda,zelda,staff,zelda,staff,1774,348,0 0 phoenix
slabel,C
return,success,0

Creating a Minimum Audit Record

An audit record consists of a sequence of tokens. Each token of the record starts with a token type followed by the token values. You can put whatever tokens and values you want into an audit record by passing the appropriate token commands to the auditwrite(3TSOL) routine.

At a minimum, every audit record has the header, subject, slabel, and return tokens. The auditwrite(3TSOL) routine call from the previous example generates the minimum audit record by specifying the AW_EVENT token command only.

Remember the proc_audit_appl privilege is needed in the effective set whenever you call auditwrite(3TSOL). The code comments indicate where privilege bracketing as described in Chapter 3, Privileges should take place. The remaining examples will not show the comments, because it is assumed you understand to do this.

/* Turn proc_audit_appl on in the effective set */
auditwrite(AW_EVENT, "AUE_second_signature", AW_WRITE, AW_END);
/* Turn the proc_audit_appl privilege off */

The output lines below have one token each. The first word on each line is the token ID followed by the token components. The description text defined in /etc/security/audit_event (second signature requested) is added to the header token.

By default the subject, slabel (sensitivity label), and return tokens are placed in the audit record even though the AW_SUBJECT, AW_SLABEL, and AW_RETURN token commands were not passed to this auditwrite(3TSOL) routine call.

• By default, the subject and slabel token values contain the security attribute information and sensitivity label of the process.

• By default, the return token has a return value of 0 (success).

If you pass AW_SUBJECT, AW_SLABEL, or AW_RETURN to the auditwrite(3TSOL) routine, you must explicitly define the token values. Auditing preselection and post-selection rely on the return token value to select audit records by success or failure. Always include the return token and the appropriate success or failure value in an audit record as described in "Return Token".

header, 4022,2,second signature requested,,Fri Sep 06
 10:16:49 1996 + 969 msec
subject,zelda,zelda,staff,zelda,staff,1774,348,0 0 phoenix
slabel,C
return,success,0

Token Structure

Trusted Solaris Audit Administration presents the structure for every token and byte sizes for each component. To help you get an idea of how to read the records and determine record size if space is a concern, the subject token structure is presented here.

Return Token

The Return token is AW_RETURN and takes a number (success or fail) and a return value. By default the return token indicates success and shows a return value of 0. You will want to set the return token value just before passing the token to the auditwrite(3TSOL) routine.

The return value affects whether or not the audit record is logged to the audit trail. If the process preselection mask audits the class to which the event belongs for failures only, a successful event is not logged. If the process preselection mask audits the class to which the event belongs for success only, a failed event is not logged. If the process preselection mask audits the class to which the event belongs for success and failure, successful and failed events are both logged. Also, the auditreduce(1M) post-selection program selects audit records by the success or failure value in the record's return token.

This example creates part of an audit record showing that a second signature was requested by the system. The signature_request() function attempts to obtain the signature and returns information on the success or failure of the attempt and sets the signature_request and retval parameters. The succ_or_fail parameter is set according to the value in signature_request and it and retval are passed as values for the AW_RETURN token.

char succ_or_fail;
u_int retval;

auditwrite(AW_TEXT, "Second signature needed,"
	AW_APPEND, AW_END);

if (signature_request() == -1) {
	succ_or_fail = -1;
	retval = -2;
} else {
	succ_or_fail = 0;
	retval = 1;
}

auditwrite(AW_EVENT, "AUE_second_signature",
	AW_RETURN succ_or_fail, retval,
	AW_WRITE, AW_END);

The signature was not obtained and the viewing terminal shows this record:

header,128,2,second signature requested,,Wed 
  Sep 11 10:17:37 1996, + 239 msec
text, Second signature needed
return,failure,-2
subject,zelda,zelda,staff,zelda,staff,1905,536,0 0 phoenix
slabel,C