Intro(3xdas)

Intro -- distributed audit service (XDAS) library functions

Description

The Distributed Audit Service (XDAS) standard specifies a set of security audit services. XDAS specifies the following features:

XDAS events

An event number identifies an event set as well as a unique event. The Open Group will assign a set of event numbers to an organization or a vendor on request. The organization or vendor then has the authority to use event numbers within that set. Conceptually, each event number is a pair: (set-id, event-id). set-id identifies an event set, and the event-id identifies an event within the event set. In practice, each event number must have one of the formats illustrated in ``Event ID formats''. See http://www.camb.opengroup.org/tech/rfc/rfc81.2.html for a list of registered events and event classes.

NOTE: To define your own XDAS events, add them to /etc/defaults/xdas. You can then register them by sending an email to dce-registry@osf.org

Event ID formats

Format Bit number
0 1 2 3 4 5 -- 7 8 -- 15 16 -- 23 24 -- 31
A 0 set-id event-id
B 1 0 set-id event-id
C 1 1 0 set-id event-id
D 1 1 1 0 event-id
E 1 1 1 1 1 reserved 

 Format                        Bit number
          0   1   2   3   4   5  7   8  15   16  23    24  31
   A      0          set-id                  event-id
   B      1   0            set-id                event-id
   C      1   1   0              set-id               event-id
   D      1   1   1   0                 event-id
   E      1   1   1   1   1               reserved
Given an event number, its format can be determined from its four high-order bits:

Format A
Allocated to organizations such as the Open Group itself and major vendors who need more than 16 bits for event-number assignment. 7 bits are allocated to set-id and 24 bits to event-id.

Format B
Allocated to intermediate-size vendors who need up to 16 bits for event-number assignment.

Format C
Allocated to small-size vendors who need 8 bits or fewer for event number assignments.

Format D
Not administered by the Open Group. These event numbers can be used freely for local security domain-specific events. The use of these numbers might not be unique across cells and should be avoided by servers which may be installed in more than one cell.

Format E
Reserved for future use.
The following list defines the generic set of XDAS event IDs.

XDAS_AE_CREATE_ACCOUNT
create account

XDAS_AE_DELETE_ACCOUNT
delete account

XDAS_AE_DISABLE_ACCOUNT
disable account

XDAS_AE_ENABLE_ACCOUNT
enable account

XDAS_AE_QUERY_ACCOUNT
query account attributes

XDAS_AE_MODIFY_ACCOUNT
modify account attributes

XDAS_AE_CREATE_SESSION
create a user session

XDAS_AE_TERMINATE_SESSION
terminate a user session

XDAS_AE_QUERY_SESSION
query a user session attributes

XDAS_AE_MODIFY_SESSION
modify user session attributes

XDAS_AE_CREATE_DATA_ITEM
create data item

XDAS_AE_DELETE_DATA_ITEM
delete data item

XDAS_AE_QUERY_DATA_ITEM_ATT
query data item attributes

XDAS_AE_MODIFY_DATA_ITEM_ATT
modify data item attributes

XDAS_AE_INSTALL_SERVICE
install service or application

XDAS_AE_REMOVE_SERVICE
remove service or application

XDAS_AE_QUERY_SERVICE_CONFIG
query configuration of service or application

XDAS_AE_MODIFY_SERVICE_CONFIG
modify configuration of service or application

XDAS_AE_DISABLE_SERVICE
disable service or application

XDAS_AE_ENABLE_SERVICE
enable service or application

XDAS_AE_INVOKE_SERVICE
invoke service or application

XDAS_AE_TERMINATE_SERVICE
terminate service or application

XDAS_AE_QUERY_PROCESS_CONTEXT
query processing context

XDAS_AE_MODIFY_PROCESS_CONTEXT
modify processing context

XDAS_AE_CREATE_PEER_ASSOC
create an association with a peer

XDAS_AE_TERMINATE_PEER_ASSOC
terminate an association with a peer

XDAS_AE_QUERY_ASSOC_CONTEXT
query an association context

XDAS_AE_MODIFY_ASSOC_CONTEXT
modify an association context

XDAS_AE_RECEIVE_DATA_VIA_ASSOC
receive data via an association

XDAS_AE_SEND_DATA_VIA_ASSOC
send data via an association

XDAS_AE_CREATE_DATA_ITEM_ASSOC
create association with data item

XDAS_AE_TERMINATE_DATA_ITEM_ASSOC
terminate association with data item

XDAS_AE_QUERY_DATA_ITEM_ASSOC_CONTEXT
query context of association with data item

XDAS_AE_MODIFY_DATA_ITEM_ASSOC_CONTEXT
modify context of association with data item

XDAS_AE_QUERY_DATA_ITEM_CONTENTS
query data item contents

XDAS_AE_MODIFY_DATA_ITEM_CONTENTS
modify data item contents

XDAS_AE_START_SYS
start system

XDAS_AE_SHUTDOWN_SYS
shut down system

XDAS_AE_RESOURCE_EXHAUST
resource exhaustion

XDAS_AE_RESOURCE_CORRUPT
resource corruption

XDAS_AE_BACKUP_DATASTORE
back up datastore

XDAS_AE_RECOVER_DATASTORE
recover datastore

XDAS_AE_AUD_CONFIG
configure audit service

XDAS_AE_AUD_DS_FULL
audit datastore full

XDAS_AE_AUD_DS_CORR
audit datastore corrupted

XDAS generic logging events

The following table defines the set of XDAS event ID numbers that EELS defines for generic logging. These events define a set of severity levels that the caller can use when logging messages. See also the Section 3eels manual pages in Section 3eels manual pages for a description of the non XDAS generic logging capabilities of the EELS system.

EELS event IDs

Event Severity Description
EELS_LOG_CODE_BLUE High A critical error has occurred that made part or all of a system unusable. Administrative intervention is needed.
EELS_LOG_ALERT Medium An event has occurred that may make part or all of a system unusable if administrative action is not taken.
EELS_LOG_ERROR Lowest A non-fatal error has occurred. This will not make part or all of a system unusable.
EELS_LOG_FYI None Information messages.
EELS_LOG_DEBUG None Debugging messages from an application, kernel driver, or kernel module. 

 +-------------------+----------+-----------------------+
 |Event              | Severity | Description           |
 +-------------------+----------+-----------------------+
 |EELS_LOG_CODE_BLUE | High     | A critical error has  |
 |                   |          | occurred that made    |
 |                   |          | part or all of a      |
 |                   |          | system unusable.      |
 |                   |          | Administrative        |
 |                   |          | intervention is       |
 |                   |          | needed.               |
 +-------------------+----------+-----------------------+
 |EELS_LOG_ALERT     | Medium   | An event has occurred |
 |                   |          | that may make part or |
 |                   |          | all of a system       |
 |                   |          | unusable if           |
 |                   |          | administrative action |
 |                   |          | is not taken.         |
 +-------------------+----------+-----------------------+
 |EELS_LOG_ERROR     | Lowest   | A non-fatal error has |
 |                   |          | occurred. This will   |
 |                   |          | not make part or all  |
 |                   |          | of a system unusable. |
 +-------------------+----------+-----------------------+
 |EELS_LOG_FYI       | None     | Information messages. |
 +-------------------+----------+-----------------------+
 |EELS_LOG_DEBUG     | None     | Debugging messages    |
 |                   |          | from an application,  |
 |                   |          | kernel driver, or     |
 |                   |          | kernel module.        |
 +-------------------+----------+-----------------------+

XDAS event outcome codes

The outcome codes defined by XDAS are shown in the following list. The codes are structured into sets for SUCCESS, FAILURE, and DENIAL. Multiple codes from within one of these sets may be returned by a single call by combining them using a bitwise OR, but it is not permitted for outcome codes from the different sets to be returned by a single call. That is, multiple SUCCESS codes may returned by one call, but SUCCESS and FAILURE codes may not be returned by a single call.

XDAS_OUT_SUCCESS
successful event

XDAS_OUT_PRIV_USED
privilege used

XDAS_OUT_PRIV_GRANTED
privilege granted

XDAS_OUT_PRIV_REVOKED
privilege revoked

XDAS_OUT_PRESELECT_CRITERIA_SET
preselection criteria set or modified

XDAS_OUT_THRESHOLDS_SET
thresholds set

XDAS_OUT_ACTIONS_SET
actions set for alarms

XDAS_OUT_THRESHOLD_EXCEEDED
pre-set thresholds exceeded

XDAS_OUT_FAILURE
non security relevant failure

XDAS_OUT_SERVICE_UNAVAILABLE
service not available

XDAS_OUT_SERVICE_FAILURE
service failure

XDAS_OUT_HARDWARE_FAILURE
hardware failure or exception condition

XDAS_OUT_LOST_ASSOCIATION
service, user or device already enabled

XDAS_OUT_ALREADY_DISABLED
service, user or device already disabled

XDAS_OUT_SERVICE_ERROR
service returns an error

XDAS_OUT_BUSY
service or device busy

XDAS_OUT_DISABLED
service or device disabled

XDAS_OUT_INVALID_INPUT
input supplied invalid

XDAS_OUT_ENTITY_EXISTS
attempt to create an entity which already exists

XDAS_OUT_ENTITY_NON-EXISTENT
attempt to access a non-existent entity

XDAS_OUT_DENIAL
security relevant failure

XDAS_OUT_INSUFFICIENT_PRIVILEGE
not sufficient privilege

XDAS_OUT_INVALID_IDENTITY
identity supplied not valid

XDAS_OUT_INVALID_USER_CREDENTIALS
user credentials supplied are invalid

Portable audit record format

The audit event record format is defined as an ordered UTF-8 character encoding in an xdas_buffer_t structure, as follows:

Field Type Description
Header ``HDR''
length_in_bytes digits 0-9 length in bytes of the retrieved record
version digits 0-9 version number of the XDAS service that created the audit record
time_offset hexadecimal time at which the audit record was committed or was timestamped by a specific function call
time_uncertainty_interval hexadecimal interval of time by which the time recorded for this event is uncertain
time_uncertainty_indicator hexadecimal percentage of confidence in the time_uncertainty_interval value
time_source alphanumeric name or address of the source of the time recorded for this event
time_zone alphanumeric time zone applicable to the domain in which the event occurred
event_number hexadecimal number defining the type of event
outcome hexadecimal outcome code recorded for the event
Originator ``ORG''
org_location_name alphanumeric name of the location of the originator domain
org_location_address alphanumeric address of the location of the originator domain
org_service_type alphanumeric server type of the originator domain
org_auth_authority alphanumeric name of the authentication authority for the originator principal
org_principal_name alphanumeric name of the originator principal
org_principal_id alphanumeric identifier of the originator principal
Initiator ``INT''
int_auth_authority alphanumeric name of the authentication authority for the initiator principal
int_domain_specific_name alphanumeric name of the initiator principal
int_domain_specific_id alphanumeric identity of the initiator principal
Target ``TGT''
tgt_location_name alphanumeric name of the location of the target domain
tgt_location_address alphanumeric address of the location of the target domain.
tgt_service_type alphanumeric service type of the target domain
tgt_auth_authority alphanumeric name of the authentication authority for the target principal
tgt_principal_name alphanumeric name of the principal target
tgt_principal_id alphanumeric identity of the target principal
Source ``SRC''
pointer_to_source_domain alphanumeric for an imported record, the pointer to the original record within the originating domain
Event ``EVT''
event_specific_information alphanumeric event-specific information recorded for the record
End ``END'' 

 Field                        Type           Description
 Header                       ``HDR''
 length_in_bytes              digits 0-9     length in bytes of
                                             the retrieved record
 version                      digits 0-9     version number of
                                             the XDAS service
                                             that created the
                                             audit record
 time_offset                  hexadecimal    time at which the
                                             audit record was
                                             committed or was
                                             timestamped by a
                                             specific function
                                             call
 time_uncertainty_interval    hexadecimal    interval of time by
                                             which the time
                                             recorded for this
                                             event is uncertain
 time_uncertainty_indicator   hexadecimal    percentage of
                                             confidence in the
                                             time_uncertainty_interval
                                             value
 time_source                  alphanumeric   name or address of the
                                             source of the time
                                             recorded for this event
 time_zone                    alphanumeric   time zone applicable to
                                             the domain in which the
                                             event occurred
 event_number                 hexadecimal    number defining the type
                                             of event
 outcome                      hexadecimal    outcome code recorded for
                                             the event
 Originator                   ``ORG''
 org_location_name            alphanumeric   name of the location of
                                             the originator domain
 org_location_address         alphanumeric   address of the location
                                             of the originator domain
 org_service_type             alphanumeric   server type of the
                                             originator domain
 org_auth_authority           alphanumeric   name of the
                                             authentication authority
                                             for the originator
                                             principal
 org_principal_name           alphanumeric   name of the originator
                                             principal
 org_principal_id             alphanumeric   identifier of the
                                             originator principal
 Initiator                    ``INT''
 int_auth_authority           alphanumeric   name of the
                                             authentication authority
                                             for the initiator
                                             principal
 int_domain_specific_name     alphanumeric   name of the initiator
                                             principal
 int_domain_specific_id       alphanumeric   identity of the initiator
                                             principal
 Target                       ``TGT''
 tgt_location_name            alphanumeric   name of the location of
                                             the target domain
 tgt_location_address         alphanumeric   address of the location
                                             of the target domain.
 tgt_service_type             alphanumeric   service type of the
                                             target domain
 tgt_auth_authority           alphanumeric   name of the
                                             authentication authority
                                             for the target principal
 tgt_principal_name           alphanumeric   name of the principal
                                             target
 tgt_principal_id             alphanumeric   identity of the target
                                             principal
 Source                       ``SRC''
 pointer_to_source_domain     alphanumeric   for an imported record,
                                             the pointer to the
                                             original record within
                                             the originating domain
 Event                        ``EVT''
 event_specific_information   alphanumeric   event-specific
                                             information recorded for
                                             the record
 End                          ``END''
The strings ``HDR'', ``ORG'', ``INT'', ``TGT'', ``SRC'', ``EVT'' and ``END'' are included in order to support syntax checking. An audit record must include all the listed fields, even if they are empty. The field separator is the colon (:). An empty field is represented by two colons (::). The escape character is the %.

The following structure defines an audit event record: 

   typedef struct xdas_audit_record_desc_struct(
       const OM_uint32 record_number,
       OM_uint32 length,
       OM_uint32 version,
       OM_uint32 time_offset,
       OM_uint32 time_uncertainty_interval,
       OM_uint32 time_uncertainty_indicator,
       xdas_buffer_t *time_source,
       xdas_buffer_t *time_zone,
       OM_uint32 event_number,
       OM_uint32 outcome,
       xdas_buffer_t *org_location_name,
       xdas_buffer_t *org_location_address,
       xdas_buffer_t *org_service_type,
       xdas_buffer_t *org_auth_authority,
       xdas_buffer_t *org_principal_name,
       xdas_buffer_t *org_principal_identity,
       xdas_buffer_t *int_auth_authority,
       xdas_buffer_t *int_principal_name,
       xdas_buffer_t *int_principal_identity,
       xdas_buffer_t *tgt_location_name,
       xdas_buffer_t *tgt_location_address,
       xdas_buffer_t *tgt_service_type,
       xdas_buffer_t *tgt_auth_authority,
       xdas_buffer_t *tgt_principal_name,
       xdas_buffer_t *tgt_principal_identity,
       xdas_buffer_t *source_reference,
       xdas_buffer_t *event_info
   ) xdas_audit_record_desc, *xdas_audit_record_t;

XDAS APIs

XDAS defined the following APIs:

General Audit Service API

The General Audit Service API allows applications to submit events to XDAS. This API is composed of the following functions:

xdas_initialise_session(3xdas) Initialize a session with XDAS. This call will fail unless the caller possesses at least one XDAS authority. Note that event logging sessions can also be initialized using eels_initialise(3eels).
xdas_terminate_session(3xdas) Terminate an XDAS session. 

 +-------------------------------+----------------------------------------+
 |xdas_initialise_session(3xdas) | Initialize a session with XDAS.  This  |
 |                               | call will fail unless the caller       |
 |                               | possesses at least one XDAS authority. |
 |                               | Note that event logging sessions can   |
 |                               | also be initialized using              |
 |                               | eels_initialise(3eels)                 |
 +-------------------------------+----------------------------------------+
 |xdas_terminate_session(3xdas)  | Terminate an XDAS session.             |
 +-------------------------------+----------------------------------------+
A caller must initiate a session with the XDAS audit service. This authenticates the caller's identity, establishes their XDAS authorities as an audit client, and sets up a session between the caller and XDAS. The caller is returned a handle to the XDAS service which they can use for all XDAS APIs and generic logging APIs functions, refer to the Section 3eels manual pages in Section 3eels manual pages.

After initiating a session, a caller may use the XDAS APIs to log events, to configure the audit service, or to analyze audit streams. These activities may be restricted by the XDAS authorities that have been assigned to the caller.

On completion, the caller must terminate the XDAS session.

NOTE: If a client dies or exits without terminating a session the user virtual memory previously allocated by the XDAS API might not be released.

These interfaces are available to privileged callers who possess the XDAS_AUDIT_SERVICE authority.

Audit Read API

The Audit Read API allows audit records to be copied into buffers where the contents can be examined. This API is composed of the following functions:

xdas_open_audit_stream(3xdas) Open an XDAS audit stream for reading.
xdas_get_next(3xdas) Read the next set of audit records from the specified audit trail into a buffer. The caller supplies the buffer length and the maximum number of records to be returned. As many records are returned as will fit into the buffer up to the specified maximum. The caller can then parse the buffer to extract individual records.
xdas_parse_record(3xdas) Parse an audit event record in an audit record buffer.
xdas_release_buffer(3xdas) Free the storage associated with a buffer.
xdas_rewind_audit_stream(3xdas) Rewind an XDAS audit stream.
xdas_close_audit_stream(3xdas) Close an XDAS audit stream. 

 +--------------------------------+------------------------------------------+
 |xdas_open_audit_stream(3xdas)   | Open an XDAS audit stream for reading.   |
 +--------------------------------+------------------------------------------+
 |xdas_get_next(3xdas)            | Read the next set of audit records from  |
 |                                | the specified audit trail into a buffer. |
 |                                | The caller supplies the buffer length    |
 |                                | and the maximum number of records to be  |
 |                                | returned.  As many records are returned  |
 |                                | as will fit into the buffer up to the    |
 |                                | specified maximum.  The caller can then  |
 |                                | parse the buffer to extract individual   |
 |                                | records.                                 |
 +--------------------------------+------------------------------------------+
 |xdas_parse_record(3xdas)        | Parse an audit event record in an audit  |
 |                                | record buffer.                           |
 +--------------------------------+------------------------------------------+
 |xdas_release_buffer(3xdas)      | Free the storage associated with a       |
 |                                | buffer.                                  |
 +--------------------------------+------------------------------------------+
 |xdas_rewind_audit_stream(3xdas) | Rewind an XDAS audit stream.             |
 +--------------------------------+------------------------------------------+
 |xdas_close_audit_stream(3xdas)  | Close an XDAS audit stream.              |
 +--------------------------------+------------------------------------------+
These functions are used to extract records from the XDAS audit stream for analysis.

These interfaces are available to privileged callers who possess the XDAS_AUDIT_READ authority.

Audit Log Import API

The Audit Log Import API allows audit data to be imported from another audit service into the XDAS audit stream. This API is composed of the following function:

xdas_import_event_records(3xdas) Import audit event records from another audit service. 

 +---------------------------------+-----------------------------------------+
 |xdas_import_event_records(3xdas) | Import audit event records from another |
 |                                 | audit service.                          |
 +---------------------------------+-----------------------------------------+
This function allows imported audit records in the XDAS common audit event record format to be aggregated and analyzed at the distributed system level.

This interface is available to privileged callers who possess the XDAS_AUDIT_IMPORT authority.

Audit Event Service Client API

The Audit Event Service Client API allows applications to configure event preselection criteria for submission of events to XDAS. This API is composed of the following functions:

xdas_start_record(3xdas) Allocate and initialize an audit record descriptor. The value returned indicates to the caller whether the event requires auditing under the current filtering criteria.
xdas_put_event_info(3xdas) Add event-specific information to an initialized audit record.
xdas_commit_record(3xdas) Write an audit record to the audit log.
xdas_timestamp_record(3xdas) Control the time at which a record is timestamped.
xdas_discard_record(3xdas) Discard an audit record. 

 +-----------------------------+-----------------------------------------+
 |xdas_start_record(3xdas)     | Allocate and initialize an audit record |
 |                             | descriptor.  The value returned         |
 |                             | indicates to the caller whether the     |
 |                             | event requires auditing under the       |
 |                             | current filtering criteria.             |
 +-----------------------------+-----------------------------------------+
 |xdas_put_event_info(3xdas)   | Add event-specific information to an    |
 |                             | initialized audit record.               |
 +-----------------------------+-----------------------------------------+
 |xdas_commit_record(3xdas)    | Write an audit record to the audit log. |
 +-----------------------------+-----------------------------------------+
 |xdas_timestamp_record(3xdas) | Control the time at which a record is   |
 |                             | timestamped.                            |
 +-----------------------------+-----------------------------------------+
 |xdas_discard_record(3xdas)   | Discard an audit record.                |
 +-----------------------------+-----------------------------------------+
These functions allow audit records to be created, filed and committed to the audit log in a common standard format, that can be used by EELS.

These interfaces are available to privileged callers who possess the XDAS_AUDIT_SUBMIT authority.

Generic logging APIs

In addition to the XDAS functions, the Enhanced Event Logging System implements a series of generic logging functions, in which the operations controlled by the xdas_initialise_session(3xdas) function and the Event Submission API, are replaced by a single funtion call. Refer to the Section 3eels manual pages in Section 3eels manual pages for details.

Authorization policy

The authorization policy in the XDAS APIs is defined on the principle of the separation of duties. The granting of XDAS authorities is under the control of authorization security services. The following XDAS authorities are defined:

XDAS_AUDIT_SERVICE
This authority is required to initialize or terminate an XDAS audit service session using the General Audit Service API.

XDAS_AUDIT_READ
This authority is required to use the Audit Read API.

XDAS_AUDIT_IMPORT
This authority is required to import audit events records from a domain specific audit service using the Audit Log Import API.

XDAS_AUDIT_SUBMIT
This authority is required to use the audit logging interfaces of the Audit Event Service Client API.

XDAS_AUDIT_CONTROL
Super User (root) authority is required to use the Audit Event Management API.
Functions in the XDAS APIs return the value XDAS_S_AUTHORISATION_FAILURE if a caller does not possess the required authority.

References

Intro(3eels), xdas_close_audit_stream(3xdas), xdas_commit_record(3xdas), xdas_discard_record(3xdas), xdas_get_next(3xdas), xdas_import_event_records(3xdas), xdas_initialise_session(3xdas), xdas_open_audit_stream(3xdas), xdas_parse_record(3xdas), xdas_put_event_info(3xdas), xdas_release_buffer(3xdas), xdas_rewind_audit_stream(3xdas), xdas_start_record(3xdas), xdas_terminate_session(3xdas), xdas_timestamp_record(3xdas)

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004