dg_auditwrite(2) DG/UX B2 Security R4.12MU02 dg_auditwrite(2)
NAME
dg_auditwrite - write a record to the audit trail
SYNOPSIS
#include <sys/audit.h>
#include <sys/audit_events.h>
int dg_auditwrite(audrec_handle_t rec_handle);
where:
rec_handle The address of the structure that describes the record
to be written to the audit trail.
DESCRIPTION
The dg_auditwrite 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 rec_handle is valid, and the
effective audit mask of the calling process enables the auditing of
the event-class given in rec_handle. 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 rec_handle. Before
writing the record, dg_auditwrite 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 aud_hdr_hdr, filled in by
dg_auditwrite, containing the magic number
AUD_RECORD_HEADER_MAGIC and the length of the audit
record.
aud_tv The current time, filled in by dg_auditwrite.
aud_pid The ID of the process that initiated the event being
audited. When this field is 0, dg_auditwrite sets it
to the ID of the calling process and sets the aud_auid
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.
aud_auid The authentication ID of the user associated with the
process given by aud_pid. If aud_pid is 0, then this
field is set to the AUTHID of the calling process. If
aud_pid is not 0, this field is assumed to have been
set by the caller.
aud_event_id 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/audit_events.h>, from AUD_ET_KERNEL_BASE to
AUD_ET_KERNEL_BASE + AUD_NUM_KERNEL_EVENTS inclusive.
aud_reason This field is set by the caller to one of the audit
reasons defined in <sys/audit.h>.
aud_class The audit class to which the event aud_event_id 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 dg_auditwrite
to the class to which aud_event_id is mapped. See the
AUD_SET_CMDS_ET_MAP, AUD_SET_ISV_ET_MAP and
AUD_SET_SITE_ET_MAP options of auditctl(2).
aud_error 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
aud_sect_header elements, which typically contains the arguments and
results needed to understand the event and its outcome. The
aud_sect_header contains the following fields:
Name Description
div_type 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:
AUD_DIV_SAME 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.
AUD_DIV_OBJECT The first record containing information
about an object involved in the event.
AUD_DIV_OPAQUE The beginning of event-specific data.
AUD_DIV_OTHER The beginning of other event-specific
data. This is currently the same as
AUD_DIV_OPAQUE.
AUD_DIV_TAIL The last entry in the audit record.
sect_type 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
AUD_SECT_OPAQUE One or more event-specific
entries
AUD_SECT_PATH One or more null terminated
pathnames
AUD_SECT_IDS One or more process
credentials (IDS), ex.,
uids, gids, supplementary
groups, etc.
AUD_SECT_ACL One or more access control
lists (ACLs)
AUD_SECT_MAC One or more MAC
(sensitivity) labels
AUD_SECT_MAC_RANGE One or more MAC range
values
AUD_SECT_CAP One or more Capability sets
AUD_SECT_CAP_REQ One or more Capability
required sets
AUD_SECT_GID One or more group IDs
AUD_SECT_UID One or more user IDs
AUD_SECT_SIGNAL One or more signal numbers
AUD_SECT_USERNAME One or more strings
representing user names
AUD_SECT_FDS One or more file
descriptors
AUD_SECT_PID One or more process IDs
AUD_SECT_UFID One or more unique file IDs
AUD_SECT_MODE One or more access modes
AUD_SECT_DEV One or more device numbers
AUD_SECT_AUDITMASK One or more audit masks
AUD_SECT_ERRNO One or more error numbers
AUD_SECT_STRINGS One or more strings
AUD_SECT_INTS One or more integers
AUD_SECT_SHORTS One or more 16-bit values
AUD_SECT_BYTES One or more 8-bit values
AUD_SECT_HEX One or more integers,
displayed in hexadecimal
AUD_SECT_EX_ERRNO One or more extended error
number values
AUD_SECT_RVAL One or more return values
AUD_SECT_TRAILSPEC One or more audit trail
specifications
AUD_SECT_AUID One or more authentication
IDs
AUD_SECT_IP_ADDR One or more host IP
addresses
AUD_SECT_RM_REQD The minimum number of calls
to the reference monitor
the call should have made
AUD_SECT_RM_MADE The actual number of calls
made to the reference
monitor
AUD_SECT_CAPS_USED The capabilities
successfully used
AUD_SECT_CAPS_ATTEMPTED The capabilities checked
for that were NOT held
AUD_SECT_OVERRIDDEN_RM_STATUS The last reference monitor
status which was legally
overridden by the kernel
code
AUD_SECT_RESOLVED_PATH The actual pathname to
which a provided pathname
was resolved.
AUD_SECT_TAIL The header of the audit
tail record
sect_len 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(aud_sect_header).
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
cap_defaults(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
appropriate_privilege(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 rec_handle 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), dg_auditctl(2), dg_setsmask(2),
sysconf(2), cap_defaults(5).
Licensed material--property of copyright holder(s)