I'm self sponsoring this case. I believe it qualifies for self-review
and am marking it "closed approved automatic." I'm happy to turn it into a
fast-track and set the timer if anyone believes I've misjudged.
The case proposes the addition of a new interface to the suite defined in
PSARC/2000/517, Thread-safe audit API. It requests a Patch Release Binding
and a Contracted Project Private Interface Taxonomy. Both are in line with
2000/517 and the associated PSARC/2003/397, Contracted audit interfaces for
open source case. I'm submitting the case primarily to record the interface
and its taxonomy. I believe it could almost be viewed as an Internal
interface.
A complete prototype man page is in the case directory as well as
in the text of the case proposal. This man page is not shipped.
None of the 2000/517 interfaces are public. None ship man pages.
Man pages are written only for the purposes architectural review.
Gary..
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Background:
==========
PSARC/2000/517, Thread-safe audit API, introduced the Solaris Audit API
for all projects that need to record events to the Solaris Audit trail.
As initially delivered, it was limited in the way that new audit records
could be created. The plan and architecture had never intended these
limitations to remain. For example, initially, new audit records needed to
be hand created outside of the Solaris build process and hand integrated
into the source for the Solaris Audit library (libbsm). CR 6522311,
adt_ interfaces need automated build process, corrected that. However,
adding new audit records still requires building a new libbsm from source.
Problem:
=======
The Solaris Audit API audit records are defined in an event translation
table complied into libbsm. This requires building libbsm from source to
add an audit record definitions.
Proposal:
========
Provide an interface to load audit record event translation tables that
are not precompiled into libbsm.
Details:
=======
The flow for generating an audit record is to create an audit session,
allocate an audit event structure, populate that structure, write that
audit record, free the event structure and session.
The record definition event translation table describes the audit record
structure for an event. If the event isn't one built into libbsm, an
alternate event translation table must be supplied. This case proposes a new
function, adt_load_table(), to supply alternate event translation tables.
No change is needed to any of the existing use of the Solaris Audit API.
This case should not be viewed as a proposal for promoting the Solaris
Audit API Interface Taxonomy or removing the need for building Sun deliver
audit events from the event table compiled into libbsm.
This case merely proposes adding the only visible (and still Contracted
Project Private) interface that the project team believes is needed
to allow an event table not built into libbsm to be used to with the
Solaris Audit API. It provides no means to build such a table.
To anticipate questions about completeness or motivation for bringing this
case at this time. There is a pressing business consideration. As all the
Solaris Audit API interfaces are Contracted Project Private, the project
team doesn't judge completeness as an issue.
An Audit event translation table is an array of opaque adt_translation_t
structures and an associated initialization function. With the integration
of 6522311, the table built into libbsm is generated as part of the build
process.
If an audit event translation table were built, this case proposes the
adt_load_table() function to enable its use without compiling it into
libbsm.
adt_load_table:
===============
Library Functions adt_load_table(3adt)
NAME
adt_load_table - load an alternate event translation table
SYNOPSIS
cc [ flag...] file ... -lbsm [library ...]
#include <bsm/adt.h>
void adt_load_table(const adt_session_data_t *session_handle,
adt_translation_t **xlate_table, void (*preload)(au_event_t,
adt_event_data_t *));
DESCRIPTION
adt_load_table() loads an alternate event translation table
for use during audit record generation for the session.
It is required only for events not delivered by -lbsm.
Such events would be generated by special agreement and use
of the Solaris Audit Record Definition translator.
adt_load_table() must be called before adt_alloc_event().
session_handle is the handle returned by adt_start_session().
xlate_table is the address of the beginning of the translation
table created by the translation the Solaris Audit Record Definition
file describing the alternate audit events. preload is the address
of the event preload function created by translation from the
Solaris Audit Record Definition file describing the alternate
audit events.
EXAMPLES
if (adt_start_session(adt_session_data_t &ah, NULL,
ADT_USE_PROC_DATA) != 0) {
perror("can't start audit session");
exit(1);
}
adt_load_table(ah, &my_xlate_table[0], &my_preload);
my_event = adt_alloc_event(ah, MY_event_id);
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Contract Project Private |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
adt_alloc_event(3adt), adt_end_session(3adt), adt_free_event(3adt),
adt_put_event(3adt), adt_start_session(3adt), attributes(5)
NOTES
If auditing is not configured on the system this function may
still be called with no ill effects.
This function is not for use with the delivered -lbsm events.
----- End Included Message -----
