audit_intro(3) Open Software Foundation audit_intro(3)
NAME [Toc] [Back]
audit_intro - Introduction to the DCE Audit API runtime.
DESCRIPTION [Toc] [Back]
This introduction gives general information about the DCE Audit
Application Programming Interface (API) and an overview of the
following parts of the DCE Audit API runtime:
+ Runtime services
+ Environment variables
+ Data types and structures
+ Permissions required
Runtime Services [Toc] [Back]
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.
dce_aud_close()
Closes an audit trail (client/server applications, audit trail
analysis and examination tools).
dce_aud_commit()
Performs the audit action(s) (client/server applications).
dce_aud_discard()
Discards an audit record which releases the memory (client/server
applications, audit trail analysis and examination tools).
dce_aud_free_ev_info()
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).
dce_aud_free_header()
Frees the memory allocated to a designated audit record header
structure (audit trail analysis and examination tools).
dce_aud_get_ev_info()
Gets the event-specific information of a specified audit record
(audit trail analysis and examination tools).
dce_aud_get_header()
Gets the header of a specified audit record (audit trail analysis
and examination tools).
Hewlett-Packard Company - 1 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
audit_intro(3) Open Software Foundation audit_intro(3)
dce_aud_length()
Gets the length of a specified audit record (client/server
applications, audit trail analysis and examination tools).
dce_aud_next()
Reads the next audit record from a specified audit trail into a
buffer (audit trail analysis and examination tools).
dce_aud_open()
Opens a specified audit trail for read or write (client/server
applications, audit trail analysis and examination tools).
dce_aud_print()
Formats an audit record into a human-readable form (audit trail
analysis and examination tools).
dce_aud_put_ev_info()
Adds event-specific information to a specified audit record buffer
(client/server applications).
dce_aud_set_trail_size_limit()
Sets a limit to the audit trail size (client/server
applications).
dce_aud_start()
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
applications).
dce_aud_start_with_name()
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).
dce_aud_start_with_pac()
Determines whether a specified 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).
Hewlett-Packard Company - 2 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
audit_intro(3) Open Software Foundation audit_intro(3)
dce_aud_start_with_server_binding()
Determines whether a specified 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).
dce_aud_start_with_uuid()
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 [Toc] [Back]
The following subsections list the data types and structures used by
applications to perform auditing and to analyze audit trails.
Event-Specific Information [Toc] [Back]
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;
Hewlett-Packard Company - 3 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
audit_intro(3) Open Software Foundation audit_intro(3)
The format field of the above data structure defines formatting
information 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.
Audit Record Header Data Structure [Toc] [Back]
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;
Hewlett-Packard Company - 4 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
audit_intro(3) Open Software Foundation audit_intro(3)
char *addr;
uuid_t *groups;
} dce_aud_hdr_t;
format Contains the version 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 information.
For example, the event-specific information of an event may
initially be defined to be a 32-bit integer, and later
changed to a character string. Format version 0 (zero) is
assigned to the initial format for each event.
server Contains the UUID of the server that generates the audit
record.
event Contains the event number.
outcome Indicates whether the event failed or succeeded. If the
event failed, the reason for the failure is given.
authz_st
Indicates how the client is authorized: by a name or by a
DCE Privilege Attribute Certificate (PAC).
client Contains the UUID of the client.
cell Contains the UUID of the client's cell.
num_groups
Contains the number of local group privileges the client
used for access.
groups 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.
time 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
Hewlett-Packard Company - 5 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
audit_intro(3) Open Software Foundation audit_intro(3)
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.
addr Records the client's address (port address of the caller).
Port addresses are not authenticated. 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.
Audit Record Descriptor [Toc] [Back]
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 descriptor. 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().
Audit Trail Descriptor [Toc] [Back]
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 descriptor; and dce_aud_commit() commits an audit
record from and to an opened audit trail through this descriptor.
The dce_aud_close() function disposes of this descriptor.
Environment Variables [Toc] [Back]
Hewlett-Packard Company - 6 OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96
audit_intro(3) Open Software Foundation audit_intro(3)
The Audit API routines use the following environment variables:
DCEAUDITOFF If this environment variable is defined at the
time the application is started, auditing is
turned off.
DCEAUDITFILTERON If this environment variable is defined, filtering
is enabled.
DCEAUDITTRAILSIZE Sets the limit of the audit trail size. This
variable overrides the limit set by the
dce_aud_set_trail_size_limit() function.
Permissions Required [Toc] [Back]
To use an Audit daemon's audit record logging service, you need the
log (l) permission to the Audit daemon.
RELATED INFORMATION [Toc] [Back]
Books: OSF DCE Administration Reference, OSF DCE Application
Development Guide.
RELATED INFORMATION [Toc] [Back]
Books: OSF DCE Administration Reference, OSF DCE Application
Development Guide.
Hewlett-Packard Company - 7 -OSF DCE 1.1/HP DCE 1.8 PHSS_26394-96 [ Back ] |
