audit_intro(3)audit_intro(3)NAMEaudit_intro - Introduction to the DCE Audit API runtime.
DESCRIPTION
This introduction gives general information about the DCE Audit Appli‐
cation Programming Interface (API) and an overview of the following
parts of the DCE Audit API runtime: Runtime services Environment vari‐
ables Data types and structures Permissions required
Runtime Services
The following is an alphabetical list of the Audit API routines. With
each routine name is its description. The types of application program
that will most likely call the routine are enclosed in parentheses.
Closes an audit trail (client/server applications, audit trail analysis
and examination tools). Performs the audit action(s) (client/server
applications). Discards an audit record which releases the memory
(client/server applications, audit trail analysis and examination
tools). Frees the memory allocated for an event information structure
returned from calling the dce_aud_get_ev_info() function (audit trail
analysis and examination tools). Frees the memory allocated to a des‐
ignated audit record header structure (audit trail analysis and exami‐
nation tools). Gets the event-specific information of a specified
audit record (audit trail analysis and examination tools). Gets the
header of a specified audit record (audit trail analysis and examina‐
tion tools). Gets the length of a specified audit record
(client/server applications, audit trail analysis and examination
tools). Reads the next audit record from a specified audit trail into
a buffer (audit trail analysis and examination tools). Opens a speci‐
fied audit trail for read or write (client/server applications, audit
trail analysis and examination tools). Formats an audit record into a
human-readable form (audit trail analysis and examination tools). Adds
event-specific information to a specified audit record buffer
(client/server applications). Sets a limit to the audit trail size
(client/server applications). Determines whether a specified event
should be audited given the client's binding information and the event
outcome. If the event should be audited or if it is not yet known
whether the event should be audited because the event outcome is still
unknown, memory for the audit record descriptor is allocated and the
address of this memory is returned to the caller (client/server appli‐
cations). Determines whether a specified event should be audited given
the client/server name and the event outcome. If the event should be
audited or if it is not yet known whether the event should be audited
because the event outcome is still unknown, memory for the audit record
descriptor is allocated and the address of this memory is returned to
the caller (client/server applications). Determines whether a speci‐
fied event should be audited given the client's Privilege Attribute
Certificate (PAC) and the event outcome. If the event should be
audited or if it is not yet known whether the event should be audited
because the event outcome is still unknown, memory for the audit record
descriptor is allocated and the address of this memory is returned to
the caller (client/server applications). Determines whether a speci‐
fied event should be audited given the server's binding information and
the event outcome. If the event should be audited or if it is not yet
known whether the event should be audited because the event outcome is
still unknown, memory for the audit record descriptor is allocated and
the address of this memory is returned to the caller (client/server
applications). Determines whether a specified event should be audited
given the client/server UUID and the event outcome. If the event must
be audited, or if the outcome of the event is not yet known, the memory
for the audit record descriptor is allocated and the address of this
structure is returned to the caller (client/server applications).
Audit Data Types
The following subsections list the data types and structures used by
applications to perform auditing and to analyze audit trails. The
Audit APIs allow applications to include event-specific information in
audit records. Event-specific information must be represented as
information items using the following data type. typedef struct {
unsigned16 format;
union {
idl_small_int small_int;
idl_short_int short_int;
idl_long_int long_int;
idl_hyper_int hyper_int;
idl_usmall_int usmall_int;
idl_ushort_int ushort_int;
idl_ulong_int ulong_int;
idl_uhyper_int uhyper_int;
idl_short_float short_float;
idl_long_float long_float;
idl_boolean boolean;
uuid_t uuid;
utc_t utc;
sec_acl_t * acl;
idl_byte * byte_string;
idl_char * char_string;
} data; } dce_aud_ev_info_t;
The format field of the above data structure defines formatting infor‐
mation that is used to determine the type of the data referenced by the
data field. The following table shows possible values of the format
field, their corresponding data types, and their sizes.
┌──────────────────────────────────────────────────────────────┐
│ Event Data Format Specifiers — intro(3) │
├───────────────────────────┬─────────────────┬────────────────┤
│Specifier │ Data Type │ Size │
├───────────────────────────┼─────────────────┼────────────────┤
│aud_c_evt_info_small_int │ idl_small_int │ 1 byte │
│aud_c_evt_info_short_int │ idl_short_int │ 2 bytes │
│aud_c_evt_info_long_int │ idl_long_int │ 4 bytes │
│aud_c_evt_info_hyper_int │ idl_hyper_int │ 8 bytes │
│aud_c_evt_info_usmall_int │ idl_usmall_int │ 1 bytes │
│aud_c_evt_info_ushort_int │ idl_ushort_int │ 2 bytes │
│aud_c_evt_info_ulong_int │ idl_ulong_int │ 4 bytes │
│aud_c_evt_info_uhyper_int │ idl_uhyper_int │ 8 bytes │
│aud_c_evt_info_short_float │ idl_short_float │ 4 bytes │
│aud_c_evt_info_long_float │ idl_long_float │ 8 bytes │
│aud_c_evt_info_boolean │ idl_boolean │ 1 byte │
│aud_c_evt_info_uuid │ uuid_t │ 16 bytes │
│aud_c_evt_info_utc │ utc_t │ 16 bytes │
│aud_c_evt_info_acl │ sec_acl_t * │ variable size │
│aud_c_evt_info_byte_string │ idl_byte * │ variable size │
│aud_c_evt_info_char_string │ idl_char * │ variable size │
└───────────────────────────┴─────────────────┴────────────────┘
Byte strings and character strings are terminated with a 0 (zero) byte.
New data types can be added to this list if they are used frequently.
Servers could use the pickling service of the IDL compiler to encode
complex data types into byte strings that are to be included in an
audit record. The following data structure is used to store header
information obtained from an audit record. This structure is normally
only used by audit trail analysis and examination tools. That is, it
is hidden from client/server applications. typedef struct {
unsigned32 format;
uuid_t server;
unsigned32 event;
unsigned16 outcome;
unsigned16 authz_st;
uuid_t client;
uuid_t cell;
unsigned16 num_groups;
utc_t time;
char *addr;
uuid_t *groups; } dce_aud_hdr_t; Contains the ver‐
sion number of the tail format of the event used for the event-specific
information. With this format version number, the audit analysis tools
can accommodate changes in the formats of the event-specific informa‐
tion. For example, the event-specific information of an event may ini‐
tially be defined to be a 32-bit integer, and later changed to a char‐
acter string. Format version 0 (zero) is assigned to the initial for‐
mat for each event. Contains the UUID of the server that generates the
audit record. Contains the event number. Indicates whether the event
failed or succeeded. If the event failed, the reason for the failure
is given. Indicates how the client is authorized: by a name or by a
DCE Privilege Attribute Certificate (PAC). Contains the UUID of the
client. Contains the UUID of the client's cell. Contains the number
of local group privileges the client used for access. Contains the
UUIDs of the local group privileges that are used by the client for the
access. By default, the group information is not be included in the
header (num_groups is set to 0 in this case), to minimize the size of
the audit records. If the group information is deemed as important, it
can be included.
Information about foreign groups (global groups that do not belong to
the same cell where the client is registered) is not included in this
version of audit header but may be included in later versions when
global groups are supported. Contains a timestamp of utc_t type that
records the time when the server committed the audit record (that is,
after providing the event information through audit API function
calls). Recording this time, rather than recording the time when the
audit record is appended to an audit trail, will better maintain the
sequence of events. The implementation of the audit subsystem may
involve communication between the server and a remote audit daemon,
incurring indefinite delays by network problems or intruders. The
inaccuracy in the utc_t timestamp may be useful for correlating events.
When searching for events in an audit trail that occur within a time
interval, if the results of the comparisons between the time of an
event and the interval's starting and ending times is maybe (because of
inaccuracies), then the event should be returned. Records the client's
address (port address of the caller). Port addresses are not authenti‐
cated. A caller can provide a fraudulent port address to a DCE server.
However, if this unauthenticated port address is deemed to be useful
information, a DCE server can record this information using this field.
The identity of the server cell is not recorded in the header, because
of the assumption that all audit records in an audit trail are for
servers within a single cell, and implicitly, the server cell is the
local cell. An opaque data type, dce_aud_rec_t, is used to represent
an audit record descriptor. An audit record descriptor may be created,
manipulated, or disposed of by the following functions: The functions
dce_aud_start(), dce_aud_start_with_pac(), dce_aud_start_with_name(),
dce_aud_start_with_server_binding(), and dce_aud_next() return a record
descriptor. The function dce_aud_put_ev_info() adds event information
to an audit record through a record descriptor. The functions
dce_aud_get_header(), dce_aud_get_ev_info(), and dce_aud_length() get
the event and record information through a record descriptor. The
function dce_aud_commit() commits an audit record through its descrip‐
tor. The function dce_aud_discard() disposes of a record descriptor.
The function dce_aud_discard() is necessary only after reading the
record (that is, after invoking dce_aud_next(). An opaque data type,
dce_aud_trail_t, is used to represent an audit trail descriptor. The
dce_aud_open() function opens an audit trail and returns a trail
descriptor; dce_aud_next() obtains an audit record from this descrip‐
tor; and dce_aud_commit() commits an audit record from and to an opened
audit trail through this descriptor. The dce_aud_close() function dis‐
poses of this descriptor.
Environment Variables
The Audit API routines use the following environment variables: If this
environment variable is defined at the time the application is started,
auditing is turned off. If this environment variable is defined, fil‐
tering is enabled. Sets the limit of the audit trail size. This vari‐
able overrides the limit set by the dce_aud_set_trail_size_limit()
function.
Permissions Required
To use an Audit daemon's audit record logging service, you need the log
(l) permission to the Audit daemon.
RELATED INFORMATION
Books: OSF DCE Administration Reference, OSF DCE Application Develop‐
ment Guide.
RELATED INFORMATION
Books: OSF DCE Administration Reference, OSF DCE Application Develop‐
ment Guide.
audit_intro(3)