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 |
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.
Token ID |
Audit ID |
User ID |
Group ID |
Real user ID |
Real group ID |
Process ID |
Session ID |
Device ID |
Machine ID |
subject |
zelda |
root |
other |
root |
other |
1774 |
348 |
0 0 |
phoenix |
1 byte |
4 bytes |
4 bytes |
4 bytes |
4 bytes |
4 bytes |
4 bytes |
4 bytes |
4 bytes |
4 bytes |
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 |