dg_auditwrite(2) DG/UX B2 Security R4.12MU02 dg_auditwrite(2)
NAME
dgauditwrite - write a record to the audit trail
SYNOPSIS
#include <sys/audit.h>
#include <sys/auditevents.h>
int dgauditwrite(audrechandlet rechandle);
where:
rechandle The address of the structure that describes the record
to be written to the audit trail.
DESCRIPTION
The dgauditwrite system call writes non-kernel audit records. The
audit record is written to the current audit trail file if auditing
is on, the header record given by rechandle is valid, and the
effective audit mask of the calling process enables the auditing of
the event-class given in rechandle. Because this function may not
require privilege, no indication is given when a record is discarded
because auditing is off or the effective audit mask blocks it. This
prevents it from being used to determine whether auditing is on or
which events are being audited.
The audit record is created from the header record and any optional
record section(s) in the user buffer defined by rechandle. Before
writing the record, dgauditwrite adds a record tail and fills in
some fields of the headers as described below.
The record header contains the following fields which are filled in
as described:
Name Description
hdr A structure of type struct audhdrhdr, filled in by
dgauditwrite, containing the magic number
AUDRECORDHEADERMAGIC and the length of the audit
record.
audtv The current time, filled in by dgauditwrite.
audpid The ID of the process that initiated the event being
audited. When this field is 0, dgauditwrite sets it
to the ID of the calling process and sets the audauid
field to the authentication ID of the user associated
with the process. Appropriate privilege is required to
pass this field with a non zero value.
audauid The authentication ID of the user associated with the
process given by audpid. If audpid is 0, then this
field is set to the AUTHID of the calling process. If
audpid is not 0, this field is assumed to have been
set by the caller.
audeventid This field is set by the caller to the event number of
the event being audited.
Only user level auditable events may be audited via
this function. That is, auditable events generated by
the kernel cannot be audited via this function. The
event numbers reserved by the kernel are defined in
<sys/auditevents.h>, from AUD_ET_KERNEL_BASE to
AUD_ET_KERNEL_BASE + AUD_NUM_KERNEL_EVENTS inclusive.
audreason This field is set by the caller to one of the audit
reasons defined in <sys/audit.h>.
audclass The audit class to which the event audeventid is
mapped. An audit class represents a grouping of
related auditable events and the audit reasons for
auditing the class. This field is set by dgauditwrite
to the class to which audeventid is mapped. See the
AUDSETCMDSETMAP, AUDSETISVETMAP and
AUDSETSITEETMAP options of auditctl(2).
auderror This field is set by the caller to the error code
generated by the event being audited.
Optionally the header record is followed by an array of struct
audsectheader elements, which typically contains the arguments and
results needed to understand the event and its outcome. The
audsectheader contains the following fields:
Name Description
divtype The division type. This type associates the data in the
section with one of the entities involved in the operation
being audited. This field must be one of the following:
AUDDIVSAME This record contains data associated with
the previous entity. The header record
contains data about the subject (the
process and its user) and so a header
record followed by this division contains
information about the subject.
AUDDIVOBJECT The first record containing information
about an object involved in the event.
AUDDIVOPAQUE The beginning of event-specific data.
AUDDIVOTHER The beginning of other event-specific
data. This is currently the same as
AUD_DIV_OPAQUE.
AUDDIVTAIL The last entry in the audit record.
secttype The type of the data that follows this header. The number
of data entries in this section is given by the size of
the entries and the length of the section. Note that some
of these sections are used by features that may not be
configured on your system. Valid entries for this field
and their contents are:
Entry Field
AUDSECTOPAQUE One or more event-specific
entries
AUDSECTPATH One or more null terminated
pathnames
AUDSECTIDS One or more process
credentials (IDS), ex.,
uids, gids, supplementary
groups, etc.
AUDSECTACL One or more access control
lists (ACLs)
AUDSECTMAC One or more MAC
(sensitivity) labels
AUDSECTMACRANGE One or more MAC range
values
AUDSECTCAP One or more Capability sets
AUDSECTCAPREQ One or more Capability
required sets
AUDSECTGID One or more group IDs
AUDSECTUID One or more user IDs
AUDSECTSIGNAL One or more signal numbers
AUDSECTUSERNAME One or more strings
representing user names
AUDSECTFDS One or more file
descriptors
AUDSECTPID One or more process IDs
AUDSECTUFID One or more unique file IDs
AUDSECTMODE One or more access modes
AUDSECTDEV One or more device numbers
AUDSECTAUDITMASK One or more audit masks
AUDSECTERRNO One or more error numbers
AUDSECTSTRINGS One or more strings
AUDSECTINTS One or more integers
AUDSECTSHORTS One or more 16-bit values
AUDSECTBYTES One or more 8-bit values
AUDSECTHEX One or more integers,
displayed in hexadecimal
AUDSECTEXERRNO One or more extended error
number values
AUDSECTRVAL One or more return values
AUDSECTTRAILSPEC One or more audit trail
specifications
AUDSECTAUID One or more authentication
IDs
AUDSECTIPADDR One or more host IP
addresses
AUDSECTRMREQD The minimum number of calls
to the reference monitor
the call should have made
AUDSECTRMMADE The actual number of calls
made to the reference
monitor
AUDSECTCAPSUSED The capabilities
successfully used
AUDSECTCAPSATTEMPTED The capabilities checked
for that were NOT held
AUDSECTOVERRIDDENRMSTATUS The last reference monitor
status which was legally
overridden by the kernel
code
AUDSECTRESOLVEDPATH The actual pathname to
which a provided pathname
was resolved.
AUDSECTTAIL The header of the audit
tail record
sectlen The length of the section, including the header and any
padding added to align the next section on a 4 bytes
boundary. This entry must contain a value greater than or
equal to sizeof(audsectheader).
ACCESS CONTROL
Depending on per-site configuration, the caller may need appropriate
privilege.
For systems supporting the DG/UX Capability Option, appropriate
privilege is defined as having one or more specific capabilities
enabled in the effective capability set of the calling process. See
capdefaults(5) for the default capability for this system call.
On systems without the DG/UX Capability Option, appropriate privilege
means that the process has an effective UID of root. See the
appropriateprivilege(5) man page for more information.
RETURN VALUE
0 Successful completion
-1 An error occurred. errno is set to indicate the error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EFAULT The memory buffer specified by rechandle is not accessible
by the caller.
EPERM The call is configured to require appropriate privilege on
this system, and the caller lacks this privilege.
EPERM The caller attempted to specify the pid/authid for the audit
record, but lacks appropriate privilege to do so.
EINVAL Invalid event number. The given number is not a valid, non-
kernel, audit event number.
ENOMEM The operating system could not allocate the memory needed to
complete this request.
SEE ALSO
audadmin(1M), audclassmap(1M), dgauditctl(2), dgsetsmask(2),
sysconf(2), capdefaults(5).
Licensed material--property of copyright holder(s)