The Content Server Audit Facility

Introduction

Auditing is a security feature of the Content Server which provides a permanent record of
“events” which have occurred. An event is either an operation performed on the Docbase
(such as a checkin of a document) or an action within an application (such as executing an
advanced search function in a custom application). The Content Server provides API methods
to manage the registration of events to be audited, to create audit entries for events,
and to remove audit entries. Many, but not all of these features can also be controlled
via the DFC interface xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager (we’ll see how to get around
those deficiencies later).

When an audit entry is created, a record is written to the Docbase detailing the event
being audited. This collection of audit records, referred to as an Audit Trail, is essential
to providing accountability for actions. It records in detail which operations were executed
by which users against which objects. In addition, this historical information can be
used to assess compliance with business rules, statistically track the access and usage patterns
of users to documents, track the state of critical documents, monitor workflows and lifecycles,
or monitor the activity of specific users.

Terminology

We’ll be referring to several concepts in this article, so let’s define them first.

• System Event:
  System-recognized actions performed on specific documents, folders, cabinets, or
  other objects. Content Server supports a large number of system-defined events, representing
  operations such as checkins, promotions, and demotions. Refer to the Audit section of the Content
  Server API Reference Manual for tables listing all System Events. Also, Appendix B (System Events)
  of the Content Server API Reference provides an exhaustive list of the System Events.
• Application Event:
  Actions which are not inherently recognized by the Content Server.
  Applications decide which of these non-system actions need to support audit and add code to
  specifically handle those actions. For example, an application may choose to provide audit
  capability for an advanced search function, capturing useful data in the audit such as the
  user executing the search and the search parameters.
• Event Target:
  The primary entity acted upon by an event. Examples of targets for System Events
  include specific instances of an object, types of an object, users, groups, policies, methods,
  workflows, activites, etc. Application Events have their targets defined by their application.
• Audit Event:
  An Audit Event is either a System Event or an Application Event. The term Audit Event is introduced
  as a generalization for convenience.
• Audit Method:
  An Audit Method is used to request an audit of a specific event. The arguments to the Audit
  Method specify the event to audit, the target of the event, and the names of the attributes
  whose values are to be audited. Audit methods can be used to request audits for System Events
  or Application Events. A user must have the extended privilege xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Config Audit in order to invoke
  an Audit Method.
• Audit Trail:
  An Audit Trail is the history of instances of an Audit Event. Each instance of an Audit Event
  results in the creation of one Audit Trail entry which stores information about the event (such as
  the time of the event, which objects were involved, who performed the actions, and which values were
  affected).
• Tamper-Evident Auditing:
  The Content Server provides the ability to “sign” each Audit Trail entry, which will cause a
  cryptographic hash to be computed for the contents of the entry. The hash itself is then encrypted
  using the Application Encryption Key (AEK) for the Content Server and stored back in the
  xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>audit_signature attribute of the entry. At any point in the future, a client can validate the entry,
  which will recompute the hash and compare it to the hash stored in the attribute. Due to the way
  hashes work, if any information in the entry has been changed since the original hash was computed,
  then the new hash will not match the original, and the client knows that the entry has been tampered.

Getting Started

Granting Extended User Privileges

Before you can do anything related to auditing, you are going to have to grant a user some
special privileges. There are three “extended” user privileges which the Content Server
uses to manage security authorization for audit requests: xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Config Audit,
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Purge Audit, and xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>View Audit. The extended privileges are stored
as an integer in the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>user_xprivileges attribute of the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_user
object. The following table defines the privileges and their values. Note that multiple
privileges are summed together instead of being hierarchical, so a xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Purge
Audit privilege does not imply a xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Config Audit privilege.

Note:
By default, neither the Docbase owner nor the Superuser have any of these extended permissions. In
addition, only Docbase owners and Superusers may grant/revoke extended user privileges, but they may
not grant or revoke these privileges for themselves.

Granting Audit Privileges Using Documentum Administrator

You can either login to the Documentum Administrator tool as the Docbase owner and grant
the privileges to the Superuser, or login as the Superuser and grant the privileges to the
Docbase owner, or create a new user and grant the privileges to that user. To grant the
privilege in the Documentum Administrator tool, go to the User Management->Users
node in the tree, locate the user in the right hand panel, edit the user’s properties by
clicking on the i, and set the user’s Extended Privileges using the dropdown menu. If
the extended privileges you need are not in the dropdown, then it is easiest to grant the
permissions using DQL (see next section).

Granting Audit Privileges Using DQL

You can grant the privileges in DQL by setting the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>user_xprivileges attribute
of the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_user object to an integer value. The value is the sum of the values
corresponding to the extended user privileges defined for the user. For example, to add
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Config Audit, xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Purge Audit, and xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>View Audit
privileges to the user dmadmin:

DQL> update dm_user objects set user_xprivileges = 56 where user_name = ‘dmadmin’;

Registering an Audit

To request that an event be audited, a user must somehow invoke the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Audit method. That can be
achieved via Documentum Administrator, a DFC call, or an API call. We’ll show examples of each. For
the example, we will register an audit for all Save events of a custom object xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>vendor_admin,
including any subtypes of xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>vendor_admin. In addition, we’ll want the Audit Trail to include the new
values for the attributes xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>va_name and xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>va_tax_id, which are attributes in the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>vendor_admin object.
Note that in all cases, the object type and event must be compatible. That is, the object type must
be a valid target of the given event.

Note:
As noted in the Default Auditing section, auditing an event
will result in an Audit Trail entry with the event name xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audit.

Registering an Audit Via Documentum Administrator

In Documentum Administrator, select the Audit Management node under Administration in the tree. In
the right panel you will see actions to register audits based on the object type, the object
instance, or for all objects in the docbase. Select the action to register based on type. In the
Starts With: control, enter “vendor_admin” and click Go. Select the vendor_admin checkbox in the
resulting list and click OK. The next panel has a table at the bottom that shows all the existing
audits registered for the vendor_admin type. You can select any of those and edit or unaudit
them. We want to add a new audit, so click Add Audit in the table header. The next panel allows us to enter
the audit info. Click the Include All Subtypes checkbox, since we want to audit subtypes. Click
the Select Attributes link, locate and select the va_name and va_tax_id attributes, Add them to
the right side of the panel, select the same two attributes from the right side, and click OK. You
should be back to the panel which allows you to enter the audit info. Now click Add in the header
of the event table at the bottom of the panel. Locate and select the “dm_save” event, Add it to
the right side, select it again on the right side and click OK. You should be back to the panel
which allows you to enter the audit info. Make sure it all looks good and click OK. You should
now see the panel which shows all the registered events for the object type and your event should be
in the table. Click OK one final time to get back to the main display.

Registering an Audit Via DFC

In DFC, you will use an instance of xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager to register the audit. You can obtain
an instance of xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager directly off of any xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfSession by calling
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>getAuditManager().
Please refer to the javadoc pages for xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager for more details on the methods it
supports. The following code snippet demonstrates how to register the example audit:

public void registerAudit(IDfSession session) throws DfException {
// Get an instance of the audit manager using the session
IDfAuditTrailManager auditMgr = session.getAuditTrailManager();
// Setup the request parameters
String objectType = "vendor_admin";
String eventName = "dm_save";
boolean auditSubTypes = true; // we want to audit subtypes also
boolean signAuditEntries = false; // disable tamper-evident Audit Trail
int authentication = 0; // we don't require user to authenticate
String description = "Save Vendor Admin"; // shows up in each audit entry
String[] auditAttrs = { "va_name, "va_tax_id" };
// Use the audit manager to register the audit.
// We do not care about controlling applications or workflows,
// so we pass null for those arguments.
auditMgr.registerEventForType(objectType,
eventName,
auditSubTypes,
null, // controllingApp
null, // policyId
null, // stateName
signAuditEntries,
authenticate,
description,
new DfList(attrs));
}

Registering an Audit Via API

All audit registrations go thru the “audit” API command, which is described in depth in the Content
Server API Reference guide. There are examples there for all the variants you will need to
understand. The syntax for the audit command is:

dmAPIExec("audit,session[,object_id],event_name
[,audit_subtypes][,controlling_app]
[,policy_id[,state_name]][,sign_audit][,authentication]
[,event_description][,attribute_list]")

Note:
This will NOT work for the DM_ALL event (see Content Server API Reference)

In order to audit all instances of an object type, we need to first identify the object
ID of the type’s xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_type object. So, our example requires two steps: one to retrieve the
ID of the type and one to register the audit based on that ID. Note the four empty arguments
in the second step, which are the missing optional values for the controlling app,
the policy ID, the state name, and the authentication.

API> retrieve,s0,dm_type where name='vendor_admin'
API> audit,s0,returned object ID,dm_save,T,,,,F,,'Save Vendor Admin','va_name,va_tax_id'

Wow, that sure was a lot simpler than the other two techiniques!

The Audit Registry

Every time an xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Audit method is successfully invoked, a new record is recorded in the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry object. The record stores the details of the audit request,
which are especially useful for managing the audit of Application Events
(see Auditing Application Events).

Default Auditing

The Content Server automatically performs audits for several System Events, without any user
having to register an audit. All of the resulting Audit Trail entries are stored in
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail objects. Only the User Login Failure auditing can be disabled.

The following shows the methods/actions which are audited by default and the values stored in the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>event_name attribute of their xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail entries:

Auditing System Events

After you register the audit for a System Event, then Content Server takes care of creating
the Audit Trail entries when the registered events occur. There is no other work which you
need to do to make that happen.

Auditing Application Events

It the responsibility of the application to know when an Application Event has occurred
and to manage the creation of Audit Trail entries. The recommended approach is that after
an Application Event has occurred, the application should check the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry to see if auditing is enabled for the Application Event. If it
is, then the application should create Audit Trail entry for the event using API
calls. Using this technique, clients can enable/disable auditing of the Application Event
by creating/destroying the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry object instead of changing runtime
configuration and/or recompiling the application.

DFC Application Event Bug

If you are auditing Application Events, there appears to be a bug in the DFC xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager
class which will prevent you from registering, unregistering, or querying audits on your custom events.
Why is this? For custom app events, there are no xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_type
objects which act as the target. So, you need to pass xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>null for the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>objectName
parameter to the registration/query methods in xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager. Unfortunately, that causes
the methods to blow up with a DfException.

The workaraound is to register your custom events using the API and to query them using a utility
method. Here is how you register a custom event named “my_custom_event” using the API:

API> audit,s0,0,my_custom_event

Here is how you register a custom event named “my_custom_event” in DFC using an xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfSession
to invoke an API call:

if (session.apiExec("audit","0,my_custom_event")) {
// registration succeeded
} else {
// registration failed
}

This will result in a xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry object being created whose
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>registered_id is ‘0000000000000000’ and whose xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>event is
‘my_custom_event’. The xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>registered_id value of ‘0000000000000000’ is special
and will help us to locate the registry object using a DQL select.

Note:
When doing this, you cannot specify any parameters after the event name. That implies you cannot
specify ‘T’ for the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>sign_audit parameter, which means that Application Events
can not be setup for signing when they are created. If you want to have the Content Server
sign your Application Events, then you should Set and Save the boolean xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>sign_audit
attribute of the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry record for the audited event.

Now that you have registered the audit event, you need to be able to programmatically check
for its registration when it comes time to create an audit entry for the custom event. To
do that, we write a special method which checks for the existence of a custom audit registration
in the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry with a matching xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>event name. Here is a simple
version:

public static boolean isAppEventAudited(IDfSession session,
String eventName) throws Exception {
IDfCollection col = null;
try {
// Construct a query to select the matching custom event.
// Note the special registered_id, which will pick up custom events.
IDfQuery query = new DfQuery();
query.setDQL("SELECT r_object_id FROM dmi_registry " +
"WHERE registered_id='0000000000000000' " +
"AND event_name='" + eventName + "'");
// Execute the query
col = query.execute(session, DfQuery.READ_QUERY);
// Return true if there are any matches
return col.next();
} finally {
// Be sure to close the IDfCollection
if (col != null) {
col.close();
}
}
}

Creating Application Event Audit Entries

We can now determine that an Application Event is being audited. The final step is to actually
create the Audit Trail entry for the event. I could not locate any DFC class to help in this
endeavor, so it looks like we are going to have to fall back on an API call invoked through DFC.
The API call available to us is Createaudit (see the Content Server API Reference for
full details). The syntax for the call is:

dmAPIGet("createaudit,session,audited_obj_id,event_name
[,string_1][,string_2][,string_3][,string_4]
[,string_5][,id_1][,id_2][,id_3][,id_4][,id_5]")

Notice that the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>audited_obj_id parameter is required. So, every
audit event has to have a valid object instance which is the target. Also, notice
that the call allows for up to five strings and five IDs to be recorded in the
entry. Applications are free to use these attributes to store whatever info is necessary.
Here is an example of an API call to create an Audit Trail entry for an event named
“advanced_search” which was run by “lsmith” (stored in xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>string_1) and
which returned 731 records (stored in xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>string_2):

API> createaudit,s0,5f638bd780000125,advanced_search,lsmith,731

In DFC, we could do this as:

if (session.apiExec("createaudit","5f638bd780000125,advanced_search,lsmith,731")) {
// entry created successfully
} else {
// entry creation failed
}

Disabling Auditing

In order to stop the audit of an event, a user must somehow invoke an xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Unaudit method.
That can be achieved via Documentum Administrator, a DFC call, or an API call. Invoking the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Unaudit method will cause the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry object corresponding to the event
to be deleted. If the event is a System Event, the removal of the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry object will cause the Content Server to stop auditing the event.
If the event is an Application Event and you wrote your application to query the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_registry to determine if auditing was enabled for the event, then this
will effectively stop your application from auditing the event.

Note:
As noted in the Default Auditing section, unauditing an event
will result in an Audit Trail entry with the event name xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_unaudit.

Stopping Auditing Via Documentum Administrator

In Documentum Administrator, select the Audit Management node under Administration in the tree. In
the right panel you will see actions to manage audits based on the object type, the object
instance, or for all objects in the docbase. Select the appropriate action based on what type of event you need
to disable audit for and enter the criteria necessary to locate the existing audits. The resulting panel
will have a table at the bottom that shows all the existing audits registered. Select the event you want
to disable and click Unaudit. Click OK one final time to get back to the main display.

Stopping Auditing Via DFC

In DFC, you will use an instance of xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager to disable the audit. You can obtain
an instance of xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager directly off of any xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfSession by calling
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>getAuditManager().
Please refer to the javadoc pages for xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager for more details on the methods it
supports. The following code snippet demonstrates how to disable an audit:

public void unregisterAudit(IDfSession session) throws DfException {
// Get an instance of the audit manager using the session
IDfAuditTrailManager auditMgr = session.getAuditTrailManager();
// Setup the request parameters
String objectType = "vendor_admin";
String eventName = "dm_save";
// Use the audit manager to disable the audit.
// We do not care about controlling applications or workflows,
// so we pass null for those arguments.
auditMgr.unregisterEventForType(objectType,
eventName,
null, // controllingApp
null, // policyId
null); // stateName
}

DFC Application Event Bug

If you are auditing Application Events, there appears to be a bug in the DFC xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager
class which will prevent you from registering, unregistering, or querying audits on your custom events.
Why is this? For custom app events, there are no xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_type
objects which act as the target. So, you need to pass xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>null for the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>objectName
parameter to the registration/query methods in xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfAuditTrailManager. Unfortunately, that causes
the methods to blow up with a DfException.

The workaraound is to unregister your custom events using the API.
Here is how you unregister a custom event named “my_custom_event” using the API:

API> unaudit,s0,0,my_custom_event

Stopping Auditing Via API

Use the “Unaudit” API command to stop auditing. Refer to the Content Server API Reference
for more details on this command. The syntax is:

dmAPIExec("unaudit,session[,object_id],event_name
[,controlling_app][,policy_id ][,state_name]]")

Here is how you unregister a custom event named “my_custom_event” using the API:

API> unaudit,s0,0,my_custom_event

Here is how you unregister a System Event named “dm_fetch” using the API:

API> unaudit,s0,03638bd78000017f,dm_fetch

Removing Audit Trail Entries

Over time, Audit Trail entries can take up a lot of space in your Docbase. You will need to
periodically archive the entries by copying them or moving them out of the Audit Trail.
After you have copied the entries to a safe place, you can remove them using a DQL call,
an API call, or by using the Audit Management Tool. Regardless of which technique you
use, the user performing the operation needs to have the extended privilege xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Purge Audit.
Please refer to the section Granting Extended User Privileges
for details on how to grant the privilege.

Note:
As noted in the Default Auditing section, any removal of an
audit entry will result in an Audit Trail entry the event name xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_purgeaudit.
In fact, there will be one entry created per transaction; when purging lots of entries, this
can result in numerous xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_purgeaudit entries.

Purging Audit Trail Entries Via DQL

The DQL command to purge entries is xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>purge_audit. The command is quite complex, so
we’ll only show a simple example here. For complete details, refer to PURGE_AUDIT in the
Content Server DQL Reference Manual.

This example deletes all Audit Trail entries generated from January 1, 2003 to January 1, 2004,
including unarchived entries. The number of entries deleted in each transaction is set to 500:

DQL> EXECUTE purge_audit WITH delete_mode='DATE_RANGE',
date_start='01/01/2003 00:00:00 AM',
date_end='01/01/2004 00:00:00 AM'
purge_non_archived=T,commit_size=500

Purging Audit Trail Entries Via API

The API command to purge entries is the administrative xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>apply command, passing
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>PURGE_AUDIT for the admin command name. So, this turns into a DQL xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>PURGE_AUDIT.
That command is quite complex, so we’ll only show a simple example here. For complete details, refer to
PURGE_AUDIT in the Content Server DQL Reference Manual.

This example deletes all Audit Trail entries generated from January 1, 2003 to January 1, 2004,
including unarchived entries. The number of entries deleted in each transaction is set to 500:

API> apply,c,NULL,PURGE_AUDIT,
DELETE_MODE,S,DATE_RANGE,
DATE_START,S,01/01/2003 00:00:00 AM,
DATE_END,S,01/01/2004 00:00:00 AM,
PURGE_NON_ARCHIVED,B,T,COMMIT_SIZE,I,500"

Audit Management Tool

The Audit Management Tool runs a xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_AuditMgt job, which in turn uses the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>PURGE_AUDIT administration method to remove the Audit Trail entries from the Docbase.
This tool has many options controlling its behaviour. Please refer to the Audit Management
section of Tools and Tracing in the Documentum Content Server Admin Guide for full
details on the tool and its execution.

Audit Trail Attributes

Audit Trail entries are persistent Docbase objects of one of the following types (depending on the
Audit event): xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">dm_audittrail, xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">dm_audittrail_acl, or xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">dm_audittrail_group.
Both xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">dm_audittrail_acl and xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">dm_audittrail_group extend xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">dm_audittrail.

Audit Trails

Audit Trail xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail objects are created for all Application Events and for all System Events
which do not pertain to an ACL or a group. Excepting the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>string_x and xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>id_x attributes, all of the
attributes in this object have a common purpose and are used by all the System Events. When the
event involves a SysObj, there are several attributes which identify the SysObj such as the object
ID, the chronicle ID, the vstamp, the Content Server host, and the Docbase. Of particular interest
is the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>attribute_list attribute, which is a comma-separated list of the audited attributes and their
values AFTER the event (for versioned objects, the value is the value of the attribute in the new
version). Please refer to Audit Trail section of the Documentum Content Server Object Reference for
details on the attributes in this object.

This object also contains five ID attributes and five String attributes which store special values
for certain System Events. These are referred to as the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>id_x and xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>string_x attributes. The contents
of these attributes and their values for the various System Events are spelled out in detail in
Auditing section of the Content Administrator’s Administration Guide. Applications can also map
special values onto these attributes when they are constructing Application Events (in which case,
it is up to the application to understand how to interpret the values when the Audit Trails are read
later).

All of the attributes in this object are available for use in Application Events.

Note:
There is an additional object of interest, xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_audittrail_attrs, which is used as an overflow
store when the list of audited attributes for a System Event is too large to fit in the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>attribute_list attribute of a xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail object. In that case, the audited attributes are
stored in a xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_audittrail_attrs object and the object ID of the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_audittrail_attrs object
is stored in the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>attribute_list_id attribute of the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail object. If you are processing
Audit Trails programmatically, you will need to check for this overflow condition and handle it
accordingly. Optionally, you can query the the computed attribute, xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>_attribute_list_values,
which will return all the attributes, including any stored in the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_audittrail_attrs object.

ACL Audit Trails

Audit Trail xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail_acl objects are created when a dm_save, dm_saveasnew, or dm_destroy
registered event occurs on an ACL. The audited ACL is identified by the inherited xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>audited_obj_id
attribute. Please refer to Audit Trail ACL section of the Documentum Content Server Object Reference
for details on the attributes in this object.

Group Audit Trails

Audit Trail xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail_group objects are created when a dm_save, saveasnew, or dm_destroy
registered event occurs on a group. The audited group is identified in the inherited xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>audited_obj_id
attribute. Please refer to Audit Trail Group section of the Documentum Content Server Object
Reference for details on the attributes in this object.

Accessing Audit Trail Data

In order to read an Audit Trail entry, a user must possess the extended privilege xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>View Audit.
Please refer to the section Granting Extended User Privileges
for details on how to grant the privilege.

Distributed Audit Trails

If your Content Server is running in a distributed environment, there are two situations
you need to be aware of in order to locate your Audit Trail. These are good to know even if
you are accessing your audits only through Documentum Administrator.

• Audit Trail entries are stored in the source Docbase. If a user accessing
  a remote Docbase causes an event to be audited for a document, the Audit Trail entry
  will be written to the document’s source Docbase. So, you will want to access the
  source Docbase to retrieve the Audit Trail.
• Virtual documents that have component documents stored in multiple Docbases are even more interesting.
  For these, the Assemble Audit Trail is written to the Docbase to which you are connected
  when the Assemble method is executed, but the Checkin Audit Trail for individual components is
  written to the corresponding source Docbase. So, the complete Audit Trail for the document is
  spread across multiple Docbases. To access the full Audit Trail for one compound
  document, you need to check multiple Audit Trails. Use the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>time_stamp_utc
  attribute of the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail object to merge the Audit Trails after you
  have queried each Docbase.

Audit Viewing Security

What you can view is determined by your privileges and the value in an Audit
Trail entry’s xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>i_audited_obj_class attribute. The following excerpt from the
Content Server Administrator Guide details the security
rules applied to the Audit Trail entries displayed in Documentum Administrator:

• Users with Superuser or View Audit privileges can view any Audit Trail entry.
• Users without Superuser or View Audit privileges can view Audit Trail entries for
  SysObject-related system events (i_audited_obj_class is set to 0) if they have at least
  Browse privileges for the audited object.
• Users without Superuser or View Audit privileges cannot view Audit Trail entries for
  ACL, group, and user-related events (i_audited_obj_class is set to 1, 2, or 3)
• Users who are the owner of an audited object can always view Audit Trail entries
  for the object.

All users, regardless of privilege level, can view Audit Trail entries for application events.
If you do not have Superuser or View Audit privileges, the following attributes of the
Audit Trail entries are excluded from view for both system and application events:

• acl_name
• acl_domain
• attribute_list
• attribute_list_id
• chronicle_id
• object_nameo
• object_type
• owner_name
• session_id
• version_label

Viewing Trails Using Documentum Administrator

In general, the easiest way to view an Audit Trail is to use the Documentum Administrator
tool. Log in as a user with xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>View Audit privilege. Select the Audit
Management node under Administration in the tree. In the right panel click
Search Audit. Fill out the details necessary to view the events you need to view
and click OK. The tool will then display all the entries which meet your search
criteria. You can see all the attributes of any entry by clicking the i link on its
row in the table.

Note:
I had trouble viewing Application Events using Documentum Administrator 5.2.2.148. I was unable to locate my
custom event names using the Selected Events link, which is not suprising since they are custom events.
However, when I typed my custom event name into the text box under Selected Events and performed the
search, the tool never returned any records. Most likely, this is a “User Error” issue.

Accessing Trails Via Queries

You can programmatically query Audit Trail entries by executing either a DQL SELECT
or an API Fetch command against any of the three Audit Trail objects. All of the
audit viewing security restrictions listed
above also apply to these techniques.
In addition, if you are accessing objects of type xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_audittrail_attrs,
then you must have xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Superuser or xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>View Audit privileges.
However, there is a neat trick you can use if you do not have those privileges:
query the computed attribute, xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>_attribute_list_values, and you will
get the audited attribute values for an event which you have permission to see,
including those stored in the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dmi_audittrail_attrs object.

Verifying Signed Audit Trail Entries

When you register an audit on an event, you can elect to have the Content Server sign the
contents of all Audit Trail entries created for that event. This involves computing a hash
for the contents, encrypting the hash with the Application Encryption Key (AEK) for the Content
Server, and storing the encrypted hash in the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>audit_signature attribute of
the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail entry. At any point in the future, a user may request that
the signed event be verified, in order to ensure that it has not been tampered with since
it was created. In order to verify the entry, the Content Server recomputes the encrypted
hash of the entry and compares it to the one stored in the record. If the hashes are not the
same, then the values in the Audit Trail entry have been modified since it was created.

Verifying Signed Audit Via API

The API call available to us is xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>Verifyaudit (see the Content Server API Reference for
full details). There are no special privileges required to make the call. The syntax for the call is:

dmAPIExec("verifyaudit,session,object_id")

where the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>object_id is the Object ID of the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail,
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail_acl, or xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail_group object being verified.
The following example will verify the audit entry whose ID is ‘5f638bd780000125’:

API> verifyaudit,s0,5f638bd780000125

Verifying Signed Audit Via DFC

There is no equivalent method in xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IdfAuditTrailManager to perform a verify,
so we have to invoke the API call from an xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>IDfSession.
The following example will verify the audit entry whose ID is ‘5f638bd780000125’:

if (session.apiExec("verifyaudit","5f638bd780000125")) {
// verify succeeded - entry is clean
} else {
// verify failed - entry has been tampered
}

Note:
Because the audit entries are signed with the AEK of the Content Server, problems can
arise if the Docbase has multiple servers. In that case, you should ensure that the AEKs
in all the Content Servers are the same. If that cannot be done, then the application
requesting the verify must request the verify operation off of the Content Server which
created the audit entry (the server which creates the entry is stored in the
xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>host_name attribute of the xmlns:xsi=”https://www.w3.org/2001/XMLSchema-instance”>dm_audittrail entry).

Conclusion

That ends our tour of the audit capabilities of the Content Server. Clearly, the facility
is quite powerful, especially when it comes to auditing your application-specific events.
The Documentum documentation is quite excellent for this feature set. I would recommend
starting with the Content Server Administration Guide if you are interested in
more details.