Audit Token Structure

Logically, each token has a token type identifier followed by data specific to the token. Each token type has its own format and structure. The current tokens are shown in Table A-1. The token scheme can be extended.

An audit record always contains a header token. The header token indicates where the audit record begins in the audit trail. Every audit record contains a subject token, except for audit records from some nonattributable events. In the case of attributable events, these two tokens refer to the values of the process that caused the event. In the case of asynchronous events, the process tokens refer to the system.

arbitrary Token

The arbitrary token encapsulates data for the audit trail. It consists of four fixed fields and an array of data. The fixed fields are: a token ID that identifies this token as an arbitrary token, a suggested format field (for example, hexadecimal), a size field that specifies the size of data encapsulated (for example, short), and a count field that gives the number of following items. The remainder of the token is composed of one or more items of the specified type. The arbitrary token appears as follows:

Figure A-2 arbitrary Token Format

The print format field can take the values shown in Table A-2.

The item size field can take the values shown in Table A-3.

arg Token

The arg token contains system call argument information: the argument number of the system call, the augment value, and an optional descriptive text string. This token allows a 32-bit integer system-call argument in an audit record. The arg token has 5 fields: a token ID that identifies this token as an arg token, an argument ID that tells which system call argument the token refers to, the argument value, the length of a descriptive text string, and the text string. Figure A-3 shows the token form.

Figure A-3 arg Token Format

attr Token

The attr token contains information from the file vnode. This token has 7 fields: a token ID that identifies this as an attr token, the file access mode and type, the owner user ID, the owner group ID, the file system ID, the inode ID, and device ID the file might represent. See the statvfs(2) man page for further information about the file system ID and the device ID. This token usually accompanies a path token and is produced during path searches. In the event of a path-search error, this token is not included as part of the audit record since there is no vnode available to obtain the necessary file information. Figure A-4 shows the attr token format.

Figure A-4 attr Token Format

exec_args Token

The exec_args token records the arguments to an exec system call. The exec_args record has two fixed fields: a token ID field that identifies this as an exec_args token, and a count that represents the number of arguments passed to the exec call. The remainder of the token is composed of zero or more null-terminated strings. Figure A-5 shows an exec_args token.

Figure A-5 exec_args Token Format

The exec_args token is output only when the audit policy argv is active. See "Setting Audit Policies" for more information.

exec_env Token

The exec_env token records the current environment variables to an exec system call. The exec_env record has two fixed fields: a token ID field that identifies this as an exec_env token, and a count that represents the number of arguments passed to the exec call. The remainder of the token is composed of zero or more null-terminated strings. Figure A-6 shows an exec_env token.

Figure A-6 exec_env Token Format

The exec_env token is output only when the audit policy arge is active. See "Setting Audit Policies" for more information.

exit Token

The exit token records the exit status of a program. The exit token contains the exit status of the program and a return value. The status field is the same as that passed to the exit system call. The return value field indicates a system error number or a return value to further describe the exit status. Figure A-7 shows an exit token.

Figure A-7 exit Token Format

file Token

The file token is a special token generated by the audit daemon to mark the beginning of a new audit trail file and the end of an old file as it is deactivated. The audit daemon builds a special audit record containing this token to "link" together successive audit files into one audit trail. The file token has four fields: a token ID that identifies this token as a file token, a time and date stamp that identifies the time the file was created or closed, a byte count of the file name including a null terminator, and a field holding the file null-terminated name. Figure A-8 shows a file token.

Figure A-8 file Token Format

groups Token (Obsolete)

This token has been replaced by the newgroups token, which provides the same type of information but requires less space. A description of the groups token is provided here for completeness, but the application designer should use the newgroups token. Notice that praudit does not distinguish between the two tokens, as both token IDs are labelled groups when ASCII style output is displayed.

The groups token records the groups entries from the process's credential. The groups token has two fixed fields: a token ID field that identifies this as a groups token, and a count that represents the number of groups contained in this audit record. The remainder of the token is composed of zero or more group entries. Figure A-9 shows a groups token.

Figure A-9 groups Token Format

The groups token is output only when the audit policy group is active. See "The auditconfig Command" for more information.

header Token

The header token is special in that it marks the beginning of an audit record and combines with the trailer token to bracket all the other tokens in the record. The header token has six fields: a token ID field that identifies this as a header token, a byte count of the total length of the audit record including both header and trailer, a version number that identifies the version of the audit record structure, the audit event ID that identifies the type of audit event the record represents, an event ID modifier that contains ancillary descriptive information concerning the type of the event, and the time and date the record was created. Figure A-10 shows a header token.

Figure A-10 header Token Format

The event modifier field has the following flags defined:

0x4000			PAD_NOTATTR						nonattributable event
0x8000			PAD_FAILURE						fail audit event

in_addr Token

The in_addr token contains an Internet address. This 4-byte value is an Internet Protocol address. The token has two fields: a token ID that identifies this token as an in_addr token and an Internet address. Figure A-11 shows an in_addr token.

Figure A-11 in_addr Token Format

ip Token

The ip token contains a copy of an Internet Protocol header but does not include any IP options. The IP options may be added by including more of the IP header in the token. The token has two fields: a token ID that identifies this as an ip token and a copy of the IP header (all 20 bytes). The IP header structure is defined in /usr/include/netinet/ip.h. Figure A-12 shows an ip token.

Figure A-12 ip Token Format

ipc Token

The ipc token contains the System V IPC message/semaphore/shared-memory handle used by the caller to identify a particular IPC object. This token has three fields: a token ID that identifies this as an ipc token, a type field that specifies the type of the IPC object, and the handle that identifies the IPC object. Figure A-13 shows an ipc token.

Figure A-13 ipc Token Format

The IPC object identifiers violate the context-free nature of the Solaris CMW audit tokens. No global "name" uniquely identifies IPC objects; instead, they are identified by their handles, which are valid only during the time the IPC objects are active. The identification should not be a problem since the System V IPC mechanisms are seldom used and they all share the same audit class.

The IPC object type field may have the values shown in Table A-4. The values are defined in /usr/include/bsm/audit.h.

ipc_perm Token

The ipc_perm token contains a copy of the System V IPC access information. This token is added to audit records generated by shared memory, semaphore, and message IPC events. The token has eight fields: a token ID that identifies this token as an ipc_perm token, the user ID of the IPC owner, the group ID of the IPC owner, the user ID of the IPC creator, the group ID of the IPC creator, the access modes of the IPC, the sequence number of the IPC, and the IPC key value. The values are taken from the ipc_perm structure associated with the IPC object. Figure A-14 shows an ipc_perm token format.

Figure A-14 ipc_perm Token Format

iport Token

The iport token contains the TCP (or UDP) port address. The token has two fields: a token ID that identifies this as an iport token and the TCP/UDP port address. Figure A-15 shows an iport token.

Figure A-15 iport Token Format

newgroups Token

This token is the replacement for the groups token. Notice that praudit does not distinguish between the two tokens, as both token IDs are labelled groups when ASCII output is displayed.

The newgroups token records the groups entries from the process's credential. The newgroups token has two fixed fields: a token ID field that identifies this as a newgroups token, and a count that represents the number of groups contained in this audit record. The remainder of the token is composed of zero or more group entries. Figure A-16 shows a newgroups token.

Figure A-16 newgroups Token Format

The newgroups token is output only when the audit policy group is active. See "The auditconfig Command" for more information.

opaque Token

The opaque token contains unformatted data as a sequence of bytes. The token has three fields: a token ID that identifies this as an opaque token, a byte count of the amount of data, and an array of byte data. Figure A-17 shows an opaque token.

Figure A-17 opaque Token Format

path Token

The path token contains access path information for an object. The token contains a token ID and the absolute path to the object based on the real root of the system. The path has the following structure: a byte count of the path length and the path. Figure A-18 shows a path token.

Figure A-18 path Token Format

process Token

The process token contains information describing a process as an object such as the recipient of a signal. The token has 9 fields: a token ID that identifies this token as a process token, the invariant audit ID, the effective user ID, the effective group ID, the real user ID, the real group ID, the process ID, the audit session ID, and a terminal ID. Figure A-19 shows a process token.

Figure A-19 process Token Format

The audit ID, user ID, group ID, process ID, and session ID are long instead of short.

The process token fields for the session ID, the real user ID, or the real group ID may be unavailable. The entry is then set to -1.

return Token

The return token contains the return status of the system call (u_error) and the process return value (u_rval1). The token has three fields: a token ID that identifies this token as a return token, the error status of the system call, and the system call return value. This token is always returned as part of kernel-generated audit records for system calls. The token indicates exit status and other return values in application auditing. Figure A-20 shows a return token.

Figure A-20 return Token Format

seq Token

The seq token (sequence token) is an optional token that contains an increasing sequence number. This token is for debugging. The token is added to each audit record when the AUDIT_SEQ policy is active. The seq token has 2 fields: a token ID that identifies this token as a seq token, and a 32-bit unsigned long field that contains the sequence number. The sequence number is incremented every time an audit record is generated and put onto the audit trail. Figure A-21 shows a seq token.

Figure A-21 seq Token Format

socket Token

The socket token contains information describing an Internet socket. The socket token has 6 fields: a token ID that identifies this token as a socket token, a socket type field that indicates the type of socket referenced (TCP/UDP/UNIX), the local port address, the local Internet address, the remote port address, and the remote Internet address. Figure A-22 shows a socket token.

Figure A-22 socket Token Format

socket-inet Token

The socket-inet token describes a socket connection to a local port, which is used to represent the socket information in the Internet namespace. The socket-inet token has 4 fields: a token ID that identifies this token as a socket-inet token, a socket family field that indicates the Internet family (AF_INET, AF_OSI, and so on), the address of the local port, and the address of the socket. Figure A-23 shows a socket-inet token.

Figure A-23 socket-inet Token Format

subject Token

The subject token describes a subject (process). The structure is the same as the process token. The token has 9 fields: an ID that identifies this as a subject token, the invariant audit ID, the effective user ID, the effective group ID, the real user ID, the real group ID, the process ID, the audit session ID, and a terminal ID. This token is always returned as part of kernel-generated audit records for system calls. Figure A-24 shows the token.

Figure A-24 subject Token Format

The audit ID, user ID, group ID, process ID, and session ID are long instead of short.

The subject token fields for the session ID, the real user ID, or the real group ID may be unavailable. The entry is then set to -1.

text Token

The text token contains a text string. The token has three fields: a token ID that identifies this token as a text token, the length of the text string, and the text string itself. Figure A-25 shows a text token.

Figure A-25 text Token Format

trailer Token

The two tokens, header and trailer, are special in that they distinguish the endpoints of an audit record and bracket all the other tokens. A header token begins an audit record. A trailer token ends an audit record. It is an optional token that is added as the last token of each record only when the AUDIT_TRAIL audit policy has been set.

The trailer token is special in that it marks the termination of an audit record. Together with the header token, the trailer token delimits an audit record. The trailer token supports backward seeks of the audit trail. The trailer token has three fields: a token ID that identifies this token as a trailer token, a pad number to aid in marking the end of the record, and the total number of characters in the audit record, including both the header and trailer tokens. Figure A-26 shows a trailer token.

Figure A-26 trailer Token Format

The audit trail analysis software ensures that each record contains both header and trailer. In the case of a write error, as when a file system becomes full, an audit record can be incomplete and truncated. auditsvc, the system call responsible for writing data to the audit trail, attempts to put out complete audit records. See the auditsvc(2) man page. If file system space has run out, the call terminates without releasing the current audit record. When the call resumes, it can then repeat the truncated record.