audit_library(3T) C2 Trusted DG/UX 5.4.2T audit_library(3T)
NAME
audreccreate, audrecdiscard, audrecwrite, audrecsetdivision,
addheadersect, addgenericsect, addaclsect, addauditmasksect,
adddevsect, addidssect, addintssect, addmodesect,
addopaquesect, addstringssect, addusernamesect - audit record
creation routines in libtrust.a
SYNOPSIS
#include <audrec.h> /* needed for all these routines */
/* includes other sys header files */
int audreccreate(bodysize)
int bodysize;
void audrecdiscard()
int audrecwrite()
int audrecsetdivision(division)
int division;
#include <sys/auditevents.h>
int addheadersect(event, reason, pid)
audeventt event;
audreasont reason;
pidt pid;
int addgenericsect(section, dataptr, datalen)
audsectt section;
char *dataptr;
int datalen;
The following functions call add_generic_sect(3T):
int addaclsect(aclstructptr)
aclstructt *aclstructptr;
int addauditmasksect(maskarray)
audmaskt maskarray;
int adddevsect(deviceptr)
devt *deviceptr;
int addidssect(credptr)
credt *credptr;
int addintssect(intptr, count)
int *intptr;
int count;
int addmodesect(modeptr)
modet *modeptr;
addopaquesect(ptr, len)
Licensed material--property of copyright holder(s) 1
audit_library(3T) C2 Trusted DG/UX 5.4.2T audit_library(3T)
char *ptr;
int len;
addstringssect(string)
char *string;
addusernamesect(username)
char *username;
For other section types, call addgenericsect directly.
where:
bodysize
is the initial number of bytes to allocate for the audit
record body (excluding head or tail sections). However, if
this is zero, it will default to AUD_REC_BODYSIZE_DEFAULT.
division
is the audit record division to which all following record
sections apply. Usually, this is AUD_DIV_OBJECT (from
sys/audit.h) to separate object sections from subject
sections.
event is an event type from <sys/audit_events.h>
reason is a reason code from <sys/audit.h>
pid is zero if the action applies to this process, another process
id if the action being audited applies to another process.
Privilege is required to use a value other than zero.
aclstructptr
is a pointer to an internal ACL structure.
maskarray
is an audit mask.
deviceptr
is the address of a device dev_t.
credptr
is the address of a credentials structure which holds uids,
gids and groups.
intptr
is the address of an integer or an array of integers.
count is the number of integers at intptr.
modeptr
is the address of a mode which holds permission bits.
ptr is the address of the data area to be put into the section.
len is the length in bytes of the ptr data area.
string is a string to be put into the section.
username
is the username string to be put into the section.
DESCRIPTION
The audreccreate function must be the first function called when
building an audit record. It will allocate memory in which to build
an audit record and will do some internal initialization.
If bodysize is 0, memory will be allocated for a record of size
Licensed material--property of copyright holder(s) 2
audit_library(3T) C2 Trusted DG/UX 5.4.2T audit_library(3T)
AUD_REC_BODYSIZE_DEFAULT. If bodysize is specified, memory will be
allocated for a record with a body size of bodysize (room for a
header and tail are added). If this initial allocation of memory is
not enough to hold the record, the addgenericsect(3T) functions
will realloc(3C) more memory as they need it.
The addheadersect routine should be called next to fill in the
header. The record header contains information common to all
records. Only event, reason, and perhaps pid can be specified by the
application. When the record is written, the kernel will fill in the
other fields such as event time. If pid is non-zero and the caller
has the required privilege, pid will be used in the header record.
If the caller does not have the appropriate privilege, or pid is
zero, the current process id will be used.
The header section will always be first, although addheadersect
should be the first routine called after audreccreate.
Addheadersect does not call addgenericsect.
Fill in the body sections of the record using addgenericsect or the
routines that call it. These routines are used to build an audit
record, section by section. Each routine fills in one section. The
routines that call addgenericsect automatically fill in the section
name and data length, whereas these values must be supplied to
addgenericsect. The order in which these routines are called will
be the order that the sections are placed into the audit record.
The audrecsetdivision function is used to change the division to
which data sections apply. All sections apply to the subject until a
new division is set. For example, to create a record containing the
ACL of the subject and the object, use addaclsect(3T) for the
subject ACL, then audrecsetdivision(AUDDIVOBJECT), then
addaclsect(3T) for the object ACL. The change to AUD_DIV_OBJECT
division indicates that the second ACL section applies to the object.
Valid divisions are: AUD_DIV_OBJECT and AUD_DIV_OTHER. The latter is
used for data that is not an attribute of the subject or the object.
More than one of either type of division may appear in the same audit
record. A second object division should only be used if there is a
second object.
Use audrecwrite to write the audit record to the trail. The audit
system will fill in the system-supplied portions of the record before
putting the record into the audit buffers.
To free the memory allocated by audreccreate, use audrecdiscard.
However, it is not necessary to free the memory before creating
another audit record. Audreccreate will reuse the memory from the
previous call and reinitialize it.
EXAMPLES
if ((audreccreate(0) < 0) ||
(addheadersect(AUDETMYEVENT, AUDSUCCESS,
(pidt)0) < 0) ||
(addaclsect(saclp) < 0) ||
Licensed material--property of copyright holder(s) 3
audit_library(3T) C2 Trusted DG/UX 5.4.2T audit_library(3T)
(audrecsetdivision(AUDDIVOBJECT) < 0) ||
(addaclsect(oaclp) < 0) ||
(audrecsetdivision(AUDDIVOTHER) < 0) ||
(addstringssect(mystring) < 0))
{
perror("audit record failure");
}
else
{
if (audrecwrite() < 0)
{
perror("audit write failure");
}
}
audrecdiscard();
DIAGNOSTICS
Returns 0 on success, -1 on error.
On error, errno will be set by malloc(3C) or realloc(3C).
SEE ALSO
dgauditwrite(2), malloc(3C), realloc(3C).
Licensed material--property of copyright holder(s) 4