audit_library(3) DG/UX B2 Security R4.12MU02 audit_library(3)
NAME
audreccreate, audrecdiscard, audrecsetdivision, audrecwrite,
addgenericsect, addheadersect, 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 audrecsetdivision(division)
int division;
int audrecwrite()
#include <sys/auditevents.h>
int addgenericsect(section, dataptr, datalen)
audsectt section;
char *dataptr;
int datalen;
int addheadersect(event, reason, pid)
audeventt event;
audreasont reason;
pidt pid;
The following functions call addgenericsect(3):
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)
char *ptr;
int len;
addstringssect(string)
char *string;
addusernamesect(username)
char *username;
For other section types, call addgenericsect directly.
Parameters
bodysize 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 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 An event type from <sys/auditevents.h>
reason A reason code from <sys/audit.h>
pid 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 A pointer to an internal ACL structure.
maskarray An audit mask.
deviceptr The address of a device dev_t.
credptr The address of a credentials structure which holds
uids, gids and groups.
intptr The address of an integer or an array of integers.
count The number of integers at intptr.
modeptr The address of a mode which holds permission bits.
ptr The address of the data area to be put into the
section.
len The length in bytes of the ptr data area.
string A string to be put into the section.
username The username string to be put into the section.
DESCRIPTION
These routines, found in libtrust.a, create audit records.
audreccreate
This function must be the first function called when building an
audit record. It allocates memory in which to build an audit record
and does some internal initialization.
If bodysize is 0, memory will be allocated for a record of size
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(3) functions will
realloc(3C) more memory as they need it.
addheadersect
This 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.
addgenericsect
Fill in the body sections of the record using this routine 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.
audrecsetdivision
This function changes 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(3) for the subject ACL, then
audrecsetdivision(AUDDIVOBJECT), then addaclsect(3) 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.
audrecwrite
Use this function 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.
audrecdiscard
Use this routine to free the memory allocated by audreccreate.
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) ||
(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
audadmin(1M), dgauditctl(2), dgauditwrite(2), aalibrary(3),
acllibrary(3), caplibrary(3), maclibrary(3), malloc(3C),
realloc(3C), auditaliasdefs(4M), auditeventdefs(4M),
auditmaskdefs(4M).
Licensed material--property of copyright holder(s)