Wherever these XDAS-API C-bindings describe structured data, only fields that must be provided by all XDAS-API implementations are documented. Individual implementations may provide additional fields, either for internal use within XDAS-API routines, or for use by non-portable applications.
-
-
OM_uint32 32-bit unsigned integer
Where guaranteed minimum bit-count is important, this portable
data type is used by the XDAS-API routine definitions.
Individual XDAS-API implementations include appropriate
typedef
definitions to map this type onto a built-in data type.
-
-
typedef struct xdas_buffer_desc_struct{
size_t length;
void *value;
} xdas_buffer_desc, *xdas_buffer_t;
Storage for data passed to the application by a XDAS-API routine
using the
xdas_buffer_t
Field | Type | |
---|---|---|
Header: | "HDR" | |
<length_in_bytes> | Digits 0-9 | |
<version> | Digits 0-9 | |
<time_offset> | Hexadecimal | |
<time_uncertainty_interval> | Hexadecimal | |
<time_uncertainty_indicator> | Hexadecimal | |
<time_source> | Alphanumeric | |
<time_zone> | Alphanumeric | |
<event_number>: | Hexadecimal | |
<outcome> | Hexadecimal | |
Originator | "ORG" | |
<org_location_name> | Alphanumeric | |
<org_location_address> | Alphanumeric | |
<org_service-type> | Alphanumeric | |
<org_auth_authority> | Alphanumeric | |
<org_principal_name> | Alphanumeric | |
<org_principal_id> | Alphanumeric | |
Initiator | "INT" | |
<int_auth_authority> | Alphanumeric | |
<int_domain_specific_name> | Alphanumeric | |
<int_domain_specific_id> | Alphanumeric | |
Target | "TGT" | |
<tgt_location_name> | Alphanumeric | |
<tgt_location_address> | Alphanumeric | |
<tgt_service-type> | Alphanumeric | |
<tgt_auth_authority> | Alphanumeric | |
<tgt_principal_name> | Alphanumeric | |
<tgt_principal_id> | Alphanumeric | |
Source | "SRC" | |
<pointer_to_source_domain> | Alphanumeric | |
Event | "EVT" | |
<event_specific_information> | Alphanumeric | |
End | "END" |
The strings HDR, ORG, INT, TGT, SRC and EVT are included to support
syntax checking. All fields shall be included in the audit record, with
separators, even if they are empty (e.g., ::).
The following structure is defined for returning an audit event record
record_number,
OM_uint32 length,
OM_uint32 version,
OM_uint32 time_offset,
OM_uint32 time_uncertainty_interval,
OM_unit32 time_uncertainty_indicator,
xdas_buffer_t *time_source,
xdas_buffer_t *time_zone,
OM_unit32 event_number,
OM_unit32 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;
The components of the audit record structure are:
A composite name is the concatenation of the components of the name from left to right with the XDAS component separator character ('/') separating each component.
The minimum requirement for all XDAS implementations is to support UTF-8 for communication of name strings.
The notations used are as follows:
Symbol | Meaning |
---|---|
::= | Is defined to be |
| | Alternatively |
<text> | Non-terminal element |
"" | Literal expression |
* | The preceding syntactic unit can appear 0 or more times. |
+ | The preceding syntactic unit can appear 1 or more times. |
{} | The enclosed syntactic units are grouped as a single syntactic unit (can be nested). |
The XDAS composite name syntax in BNF is as follows.
std offset [dst [offset] [rule]]
Where:
hh[:mm[:ss]]
The minutes (mm) and seconds (ss) are optional. The hour
(hh) is required and may be a single digit. The offset
following std is required. If no offset follows dst, the
alternative time is assumed to be one hour ahead of
standard time. One or more digits may be used; the value
is always interpreted as a decimal number. The hour is
between zero and 24, and the minutes (and seconds) if
present between zero and 59. Use of values outside these
ranges causes undefined behaviour. If preceded by a -,
the timezone is east of the Prime Meridian; otherwise it
is west (which may be indicated by an optional preceding
+).
start_date[/time], end_date[/time]
where the first date describes when the change from
standard to alternative time occurs and the second date
describes when the change back happens. Each time field
describes when, in current local time, the change to the
other time is made.
The format of date is one of the following:
The time has the same format as offset except that no leading sign (- or +) is allowed. The default, if time is not given, is 02:00:00.
A filter expression is defined as a
xdas_buffer_t
data type containing UTF-8 characters. It is a sequence of variable length
fields, separated
by a ":" delimiter, as set out below. Note that if a colon is part of
an alphanumeric string, then it shall be escaped.
( See
Field | |
---|---|
Include/Exclude Flag | |
Attribute | |
Operator | |
Value |
The Include/Exclude flag, Attribute and Operator fields are the manifest
names defined in
A filter may be defined with a list of filter expressions which shall be evaluated in the sequence in which they are listed. The intention is that a subsequent expression may define exceptions to a previous expression. Thus an expression may exclude a set of events based on event class, but a subsequent expression, based on event number, may specifically include a subset of the events otherwise excluded by reference to event class.
A filter action is defined as a
xdas_buffer_t
data type containing UTF-8 characters. It is a sequence of variable length
fields, separated
by a ":" delimiter, as set out below. Note that if a colon is part of
an alphanumeric string, then it shall be escaped.
( See
Field | |
---|---|
Action Mask | |
Text String |
The components of the action mask are the manifest
names defined in
A filter may be defined with a list of filter actions which shall be executed in the sequence in which they are listed.
Name | Value in | Meaning | |
---|---|---|---|
Field | |||
[XDAS_S_CALL_INACCESSIBLE_READ] | 1 | A required input argument cannot be read. | |
[XDAS_S_CALL_INACCESSIBLE_WRITE] | 2 | A required output argument cannot be written. | |
[XDAS_S_CALL_BAD_STRUCTURE] | 3 | An argument is malformed. |
Name | Value in | Meaning | |
---|---|---|---|
Field | |||
[XDAS_S_COMPLETE] | 0 | Successful completion. | |
[XDAS_S_AUTHORIZATION_FAILURE] | 1 | The caller does not possess | |
the required authority. | |||
[XDAS_S_BUFF_TOO_SMALL] | 2 | The buffer allocated by the caller is too | |
small to hold a single audit record. | |||
[XDAS_S_END] | 3 | The end of the audit stream has been | |
reached. | |||
[XDAS_S_FAILURE] | 4 | An implementation specific error or | |
failure has occurred. | |||
[XDAS_S_INCOMPLETE_RECORD | 5 | The audit record has not been fully | |
populated by the caller. | |||
[XDAS_S_INVALID_ACTION_LIST] | 6 | The action list supplied is not | |
valid. | |||
[XDAS_S_INVALID_AUDIT_STREAM] | 7 | The audit stream supplied is not valid. | |
[XDAS_S_INVALID_DAS_REF] | 8 | The audit service handle supplied does | |
not refer to a valid audit service. | |||
[XDAS_S_INVALID_EVENT_INFO] | 9 | The specified audit event information | |
is not valid. | |||
[XDAS_S_INVALID_EVENT_NO] | 10 | The event number supplied is not | |
valid. | |||
[XDAS_S_INVALID_FILTER | 11 | The filter name supplied is not valid. | |
[XDAS_S_INVALID_FILTER_EXPR] | 12 | The filter expression supplied is | |
not valid. | |||
[XDAS_S_INVALID_FILTER_LIST] | 13 | The list of filter names supplied is | |
not valid. | |||
[XDAS_S_INVALID_FILTER_TYPE] | 14 | The filter type supplied is not | |
valid. | |||
[XDAS_S_INVALID_INITIATOR_INFO] | 15 | The initiator information has a syntax | |
error. | |||
[XDAS_S_INVALID_ORIG_INFO] | 16 | The originator information has a syntax | |
error. | |||
[XDAS_S_INVALID_OUTCOME] | 17 | The specified outcome is invalid. | |
[XDAS_S_INVALID_RECORD_DESCRIPTOR] | 18 | The specified audit record | |
descriptor is not valid. | |||
[XDAS_S_INVALID_RECORD_NUMBER] | 19 | The specified audit record | |
number is not valid. | |||
[XDAS_S_INVALID_SECURITY_CONTEXT] | 20 | The security context supplied is | |
invalid. | |||
[XDAS_S_INVALID_TARGET_INFO] | 21 | The target information has a syntax error. | |
[XDAS_S_NO_AUDIT] | 22 | The event does not need to be audited. | |
[XDAS_S_NO_DECISION_YET] | 23 | The audit service has insufficient | |
information to decide if the event requires | |||
auditing. | |||
[XDAS_S_NOT_SUPPORTED] | 24 | The called function is not supported by | |
this implementation | |||
[XDAS_S_RECORD_SYNTAX_ERROR] | 24 | A syntax error has been detected | |
in an input record. | |||
[XDAS_S_STORAGE_FAILURE] | 25 | The audit record cannot be | |
written to stable storage. | |||
[XDAS_S_SERVICE_FAILURE] | 26 | There has been an audit service | |
failure. |
All [XDAS_S_*] symbols equate to complete OM_uint32 status codes, rather than to bit-field values. For example, the actual value of the symbol [XDAS_S_CALL_BAD_STRUCTURE] (value 3 in the Calling Error field) is 3 << 16. The macros:
Name | Value | Meaning |
---|---|---|
XDAS_C_NO_BUFFER | NULL | No buffer is supplied or returned. |
String Value | Purpose | |
---|---|---|
HDR | Start of header data | |
ORG | Start of originator data | |
INT | Start of initiator data | |
TGT | Start of target data | |
SRC | Start of pointer to source record | |
EVT | Start of event specific data | |
END | End of record |
Given an event number, its format can be determined from its four high-order bits. Format-A event numbers, which are allocated to organizations such as the OpenGroup itself and major vendors which need more than 16 bits for event-number assignment, devote 7 bits to set-id and 24 bits to event-id. Format-B event numbers are allocated to intermediate-size vendors which need 8 to 16 bits for event-number assignment. Format-C event numbers are allocated to small-size vendors which need less than 8 bits for event number assignments. Format-D event numbers are not administered by the OpenGroup and can be used freely for local security domain-specific events. The use of these event numbers might not be unique across cells and should be avoided by servers which may be installed in more than one cells. Format-E event numbers are reserved for future use.
The following table defines the generic set of XDAS events numbers.
XDAS conforming implementations are required to handle all these defined audit events as valid. An application or system developer that submits or imports security domain specific events to the XDAS service must map those events to these XDAS generic events or register their own set of audit events with the OpenGroup.
Request to register audit events should be made by sending email to dce-registry@osf.org
Refer to the following URL for a list of registered events and event classes:
http://www.camb.opengroup.org/tech/rfc/rfc81.2.html
An XDAS implementation is required to document the procedures for configuring additional registered audit events into the XDAS service as valid audit events.
Event | Value | Description | |
---|---|---|---|
XDAS_AE_CREATE_ACCOUNT | 0x01000001 | Create account | |
XDAS_AE_DELETE_ACCOUNT | 0x01000002 | Delete account | |
XDAS_AE_DISABLE_ACCOUNT | 0x01000003 | Disable account | |
XDAS_AE_ENABLE_ACCOUNT | 0x01000004 | Enable account | |
XDAS_AE_QUERY_ACCOUNT | 0x01000005 | Query account attributes | |
XDAS_AE_MODIFY_ACCOUNT | 0x01000006 | Modify account attributes | |
XDAS_AE_CREATE_SESSION | 0x01000007 | Create a user session | |
XDAS_AE_TERMINATE_SESSION | 0x01000008 | Terminate a user session | |
XDAS_AE_QUERY_SESSION | 0x01000009 | Query a user session attributes | |
XDAS_AE_MODIFY_SESSION | 0x0100000A | Modify user session attributes | |
XDAS_AE_CREATE_DATA_ITEM | 0x0100000B | Create data item | |
XDAS_AE_DELETE_DATA_ITEM | 0x0100000C | Delete data item | |
XDAS_AE_QUERY_DATA_ITEM_ATT | 0x0100000D | Query data item attributes | |
XDAS_AE_MODIFY_DATA_ITEM_ATT | 0x0100000E | Modify data item attributes | |
XDAS_AE_INSTALL_SERVICE | 0x0100000F | Install service or application | |
XDAS_AE_REMOVE_SERVICE | 0x01000010 | Remove service or application | |
XDAS_AE_QUERY_SERVICE_CONFIG | 0x01000011 | Query configuration of service | |
or application | |||
XDAS_AE_MODIFY_SERVICE_CONFIG | 0x01000012 | Modify configuration of service | |
or application | |||
XDAS_AE_DISABLE_SERVICE | 0x01000013 | Disable service or application | |
XDAS_AE_ENABLE_SERVICE | 0x01000014 | Enable service or application | |
XDAS_AE_INVOKE_SERVICE | 0x01000015 | Invoke service or application | |
XDAS_AE_TERMINATE_SERVICE | 0x01000016 | Terminate service or application | |
XDAS_AE_QUERY_PROCESS_CONTEXT | 0x01000017 | Query processing context | |
XDAS_AE_MODIFY_PROCESS_CONTEXT | 0x01000018 | Modify processing context | |
XDAS_AE_CREATE_PEER_ASSOC | 0x01000019 | Create an association with a peer | |
XDAS_AE_TERMINATE_PEER_ASSOC | 0x0100001A | Terminate an association with | |
a peer | |||
XDAS_AE_QUERY_ASSOC_CONTEXT | 0x0100001B | Query an association context | |
XDAS_AE_MODIFY_ASSOC_CONTEXT | 0x0100001C | Modify an association context | |
XDAS_AE_RECEIVE_DATA_VIA_ASSOC | 0x0100001D | Receive data via an association | |
XDAS_AE_SEND_DATA_VIA_ASSOC | 0x0100001E | Send data via an association | |
XDAS_AE_CREATE_DATA_ITEM_ASSOC | 0x0100001F | Create association with data item | |
XDAS_AE_TERMINATE_DATA_ITEM_ASSOC | 0x01000020 | Terminate association with data | |
item | |||
XDAS_AE_QUERY_DATA_ITEM_ASSOC_CONTEXT | 0x01000021 | Query context of association | |
with data item | |||
XDAS_AE_MODIFY_DATA_ITEM_ASSOC_CONTEXT | 0x01000022 | Modify context of association | |
with data item | |||
XDAS_AE_QUERY_DATA_ITEM_CONTENTS | 0x01000023 | Query data item contents | |
XDAS_AE_MODIFY_DATA_ITEM_CONTENTS | 0x01000024 | Modify data item contents | |
XDAS_AE_START_SYS | 0x01000024 | Start system | |
XDAS_AE_SHUTDOWN_SYS | 0x01000025 | Shutdown system | |
XDAS_AE_RESOURCE_EXHAUST | 0x01000026 | Resource exhaustion | |
XDAS_AE_RESOURCE_CORRUPT | 0x01000027 | Resource corruption | |
XDAS_AE_BACKUP_DATASTORE | 0x01000028 | Backup datastore | |
XDAS_AE_RECOVER_DATASTORE | 0x01000029 | Recover datastore | |
XDAS_AE_AUD_CONFIG | 0x0100002A | Configure audit service | |
XDAS_AE_AUD_DS_FULL | 0x0100002B | Audit datastore full | |
XDAS_AE_AUD_DS_CORR | 0x0100002C | Audit datastore corrupted |
The set of event classes may be extended by registration with The OpenGroup, in a similar way to event numbers.
An XDAS implementation is required to document the procedures for configuring additional registered audit event classes into the XDAS service as valid audit event classes.
Event Class | Value | Description | |
---|---|---|---|
XDAS_AEC_ACCOUNT_MANAGEMENT | 0x01000001 | Account management events | |
XDAS_AEC_USER_SESSION | 0x01000002 | User session events | |
XDAS_AEC_DATA_ITEM_MANAGEMENT | 0x01000003 | Data item and resource element | |
management events | |||
XDAS_AEC_SERVICE_MANAGEMENT | 0x01000004 | Service or application | |
management events | |||
XDAS_AEC_SERVICE_UTILIZE | 0x01000005 | Service and application | |
utilization events | |||
XDAS_AEC_PEER_ASSOC_MANAGEMENT | 0x01000006 | Peer association management events | |
XDAS_AEC_DATA_ITEM_CONTENT_ACCESS | 0x01000007 | Data item or resource element | |
content access events | |||
XDAS_AEC_EXCEPTIONAL | 0x01000008 | Exceptional events | |
XDAS_AEC_AUDIT_SERVICE | 0x01000009 | Audit service management events |
Name | Value | Meaning | |
---|---|---|---|
[XDAS_OUT_SUCCESS] | 0x00000000 | Successful Event | |
[XDAS_OUT_PRIV_USED] | 0x00000100 | Privilege used | |
[XDAS_OUT_PRIV_GRANTED] | 0x00000200 | Privilege granted | |
[XDAS_OUT_PRIV_REVOKED] | 0x00000400 | Privilege revoked | |
[XDAS_OUT_PRESELECT_CRITERIA_SET] | 0x00000800 | Preselection criteria set | |
or modified | |||
[XDAS_OUT_THRESHOLDS_SET] | 0x00001000 | Thresholds set | |
[XDAS_OUT_ACTIONS_SET] | 0x00002000 | Actions set for alarms | |
[XDAS_OUT_THRESHOLD_EXCEEDED] | 0x00004000 | Pre-set thresholds exceeded | |
[XDAS_OUT_FAILURE] | 0x00000001 | Non security relevant failure | |
[XDAS_OUT_SERVICE_UNAVAILABLE] | 0x00000101 | Service not available | |
[XDAS_OUT_SERVICE_FAILURE] | 0x00000201 | Service failure | |
[XDAS_OUT_HARDWARE_FAILURE] | 0x00000401 | Hardware failure or exception condition | |
[XDAS_OUT_LOST_ASSOCIATION] | 0x00001001 | Service, user or device already enabled | |
[XDAS_OUT_ALREADY_DISABLED] | 0x00002001 | Service, user or device already disabled | |
[XDAS_OUT_SERVICE_ERROR] | 0x00004001 | Service returns an error | |
[XDAS_OUT_BUSY] | 0x00008001 | Service or device busy | |
[XDAS_OUT_DISABLED] | 0x00010001 | Service or device disabled | |
[XDAS_OUT_INVALID_INPUT] | 0x00020001 | Input supplied invalid | |
[XDAS_OUT_ENTITY_EXISTS] | 0x00040001 | Attempt to create an entity which already | |
exists | |||
[XDAS_OUT_ENTITY_NON-EXISTENT] | 0x00080001 | Attempt to access a non-existent | |
entity | |||
[XDAS_OUT_DENIAL] | 0x00000002 | Security relevant failure | |
[XDAS_OUT_INSUFFICIENT_PRIVILEGE] | 0x00000102 | Not sufficient privilege | |
[XDAS_OUT_INVALID_IDENTITY] | 0x00000202 | Identity supplied not valid | |
[XDAS_OUT_INVALID_USER_CREDENTIALS] | 0x00000402 | User credentials supplied | |
are invalid |
The outcome 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.
Name | Value | Meaning | |
---|---|---|---|
XDAS_C_SUBMIT | 1 | Filters for event submission interface | |
XDAS_C_IMPORT | 2 | Filters for event import interface |
Name | Value | Meaning | |
---|---|---|---|
XDAS_C_INCLUDE | 1 | Include events matching the following rule | |
XDAS_C_EXCLUDE | 2 | Exclude events matching the following rule |
Name | Value | ||
---|---|---|---|
XDAS_VERSION | 1 | XDAS Version number | |
XDAS_TIME_OFFSET | 2 | Time offset from start of epoch | |
XDAS_TIME_UNCERT_INTER | 3 | Time uncertainty interval | |
XDAS_TIME_UNCERT_INDIC | 4 | Time uncertainty indicator | |
XDAS_TIME_SOURCE | 5 | Source of time | |
XDAS_TIME_TIME_ZONE | 6 | Time Zone | |
XDAS_EVENT_NUMBER | 7 | Event number | |
XDAS_OUTCOME | 8 | Event outcome | |
XDAS_ORG_LOC_NAME | 9 | Originator location name | |
XDAS_ORG_LOC_ADD | 10 | Originator location address | |
XDAS_ORG_SERV_TYPE | 11 | Originator service type | |
XDAS_ORG_AUTH_AUTH | 12 | Originator authentication authority | |
XDAS_ORG_PRINC_NAME | 13 | Originator principal name | |
XDAS_ORG_PRINC_IDENTITY | 14 | Originator principal identity | |
XDAS_INT_AUTH_AUTH | 15 | Initiator authentication authority | |
XDAS_INT_PRINC_NAME | 16 | Initiator principal name | |
XDAS_INT_PRINC_IDENTITY | 17 | Initiator principal identity | |
XDAS_TGT_LOC_NAME | 18 | Target location name | |
XDAS_TGT_LOC_ADD | 19 | Target location address | |
XDAS_TGT_SERV_TYPE | 20 | Target service type | |
XDAS_TGT_AUTH_AUTH | 21 | Target authentication authority | |
XDAS_TGT_PRINC_NAME | 22 | Target principal name | |
XDAS_TGT_PRINC_IDENTITY | 23 | Target principal identity |
Operator | Value | Meaning | |
---|---|---|---|
XDAS_O_EQ | 1 | Equal | |
XDAS_O_NE | 2 | Not equal | |
XDAS_O_GT | 3 | Greater than | |
XDAS_O_LT | 4 | Less than | |
XDAS_O_GE | 5 | Greater than or equal | |
XDAS_O_LE | 6 | Less than or equal | |
XDAS_O_BT | 7 | Bitwise test | |
XDAS_O_SS | 8 | Substring |
Name | Value | Meaning | |
---|---|---|---|
XDAS_ACT_LOG | 1 | Record in Audit Stream | |
XDAS_ACT_ALARM | 2 | Submit event to Event Management System | |
XDAS_ACT_ACTION | 4 | Execute specified command |
Contents | Next section | Index |