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:
A set of
generic events
which are relevant at a global distributed system level.
Examples of such events are end-user system sign-on and the initiation
and termination of communication sessions.
A common
portable audit record format
to allow audit information from multiple components at the
distributed system level to be merged and analyzed.
Operational services
which are provided by a number of
Application Programming Interfaces (APIs).
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
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.
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''
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:
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).
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:
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.
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:
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:
Allocate and initialize an audit record descriptor.
The value returned indicates to the caller whether the event requires auditing
under the current filtering criteria.
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.