Projects/Audit

This is an early stage project for MIT Kerberos. It is being fleshed out by its proponents. Feel free to help flesh out the details of this project. After the project is ready, it will be presented for review and approval.

Purpose

Create an Audit infrastructure within MIT Kerberos to monitor security related events on the KDC. In future expand Kerberos Audit facility to the application servers, kadmin if it remains desirable.

Requirements

The new audit system should be:

• build-time enabled;
• run-time pluggable;
• simple, so it could be easily replaced with the OS specific implementations;

Events

This section details the categories of the auditable events and the associated information.

Audit module loaded/unloaded

Startup and shutdown of the audit system must be recorded by audit system;

KDC started/stopped

KDC start-up - list of KDC realms and corresponding ports on which the Kerberos server should listen for UDP and TCP requests; location and names of the plugins;

KDC stopped - no additional information;

Authentication (Common Criteria Class FIA)

AS exchange:

ticket ID (if available);

KDC status message;

kdc request: client and server principals, kdc options, start/end/renew_till times, available enctypes, 2nd ticket (see below ticket details), auth data type, pre-auth data type, addresses, message type,

kdc reply: client principal, ticket (see below ticket details), message type;

remote port;

pre-auth error;

chosen by KDC enctype (Common Criteria FCS_CKM.1, FCS_CKM.4);

session key cleared (Common Criteria FCS_CKM.1, FCS_CKM.4);

TGS exchange:

ticket ID (if available);

KDC status message;

kdc request: client and server principals, kdc options, start/end/renew_till times, available enctypes, 2nd ticket (see below ticket details), auth data type, pre-auth data type, addresses, message type,

kdc reply: client principal, ticket (see below ticket details), message type;

principals: (if applicable) alternate client and server principals, 2nd ticket server name;

full address;

is_referral;

xrealm name;

chosen by KDC enctype, u2u enctype (Common Criteria FCS_CKM.1, FCS_CKM.4);

session key cleared (Common Criteria FCS_CKM.1, FCS_CKM.4);

Policy: Policies violation when processing requests - TBD;

AS request; TGS request; S4U2PROXY request. Can be separate reports or part of AS/TGS request processing

Ticket details:

client and server principals, flags, ticket start/end/renew_till times, authtime, transited encoding type and contents, session key type, addresses;

Design details

The proposal is a hybrid of variadic key-value-pair (KVP) and one-API-per-event approaches.

The following are highlights of this new feature:

Flow

On the KDC side call audit event-specific functions, whose input consists of the event-id, event-status (success or failure) and event-specific structure. If event-specific callback is implemented by the audit plugin, pass the pointer to the event-specific structure to the plugin. Otherwise, fallback to the generic function with variadic KVP arguments;

Ticket ID

Ticket ID is recorded as part of audit messages. This allows to link tickets to their initial TGT at any stage of the Kerberos exchange.

Ticket ID is created as a hash of AS session key or client principal name plus timestamp or some other way;

TODO: Consider a new authorization data element AD_TKT_ID per http://tools.ietf.org/html/draft-ietf-krb-wg-cammac-04 draft to securely communicate ticket id between all Kerberos exchange participants.

Dictionary

Define the dictionary of the key names to be used in KVP to describe the events in the unified way. See below for details;

Sanitizing

Strip the event-specific structure from the security sensitive information before passing it to the plugin;

Variadic KVP

KVP is a triplet consisting of key-name, key-value and a hint about the type of the value. All key-values should be converted into the strings. The plugin implementor is hinted at the "original" type of the key-value.

KDC facing API

/* Audit plugin loaded/unloaded */
krb5_error_code 
load_audit_plugin(krb5_context context);
krb5_error_code 
unload_audit_plugin(krb5_context context);
/* event specific functions */
krb5_error_code 
kau_kdc_start(krb5_context context, struct server_handle shdl, int status);
krb5_error_code 
kau_kdc_stop(krb5_context context, krb5_error_code status);
krb5_error_code 
kau_as_req(krb5_context context, struct as_req_state *state, int status);
krb5_error_code 
kau_tgs(krb5_context context, struct tgs_req_audit_state *state, int status);

Pluggable interface

/* Audit plugin vtable */
typedef struct krb5_audit_vtable_st {
   /* Mandatory: name of module. */
   char             *name;
   kau_open_fn       open;
   kau_close_fn      close;
   kau_generic_fn    generic;
   kau_kdc_start_fn  kdc_start;
   kau_kdc_stop_fn   kdc_stop;
   kau_as_req_fn     as_req;
   kau_tgs_req_fn    tgs_req;
} *krb5_audit_vtable;

typedef krb5_error_code
(*kau_open_fn)(kau_ctx *au_ctx);

typedef krb5_error_code
(*kau_close_fn)(kau_ctx au_ctx);

/* general purpose interface to pass unspecified number of 
 *  key-type-value triplets to a plugable interface.
 */
typedef krb5_error_code
(*kau_generic_fn)(kau_ctx au_ctx, const int event_id, const int status, ... );

/* one-API-per-event surrogate */
typedef krb5_error_code
(*kau_kdc_start_fn)(kau_ctx au_ctx, const int event_id, const int status,
                    struct server_handle_san shdl);
typedef krb5_error_code
(*kau_kdc_stop_fn)(kau_ctx au_ctx, const int event_id, const int status);
typedef krb5_error_code
(*kau_as_req_fn)(kau_ctx au_ctx, const int event_id, const int status,
                 struct as_req_state_san *state);
typedef krb5_error_code
(*kau_tgs_fn)(kau_ctx au_ctx, const int event_id, const int status,
              struct tgs_req_state_san *state);

where new types server_handle_san, as_req_state_san and tgs_req_state_san are sanitized variants of server_handle, as_req_state and tgs_req_state structures respectively.

Example

krb5_error_code
kau_as_req(krb5_context context, struct as_req_state *state,
          krb5_error_code  status)
{
   krb5_error_code rc = 0;
   ...
   /* If audit plugin event-specific callback is implemented, call it */
   if (hdl->vt.as_req) {
       rc = hdl->vt.as_req(hdl->au_ctx, event_id, event_status, state);
       return rc;
   }
   /* Otherwise, try the generic one. */
   if (hdl->vt.generic)
       rc = rec_as_req(hdl->au_ctx, event_id, event_status, state);
   return rc;
}

static krb5_error_code
rec_as_req(krb5_context context, struct as_req_state_san *state,
          krb5_error_code status)
{
   krb5_error_code rc = 0;
   ...
   /* All values with TYPE_NUM type-hint are string representations of 
    * their numeric conterparts in 'state' structure.
    */
   hdl->vt.record(hdl->au_ctx, event_id, event_status,
                  "tkt_id",             TYPE_NUM, tkt_id,              // state->tkt_id 
                  "kdc_status",         TYPE_STR, state->status,
                  "full_address",       TYPE_STR, state->full_address,                 
                  "skey_etype",         TYPE_NUM, session_key_enctype, //  state->session_key_enctype
                  "pa_error",           TYPE_NUM, preauth_err,         //  state->preauth_err
                  /* request */
                  "kdcreq.msg_type",    TYPE_STR, state->req_msg_type,
                  "kdcreq.client",      TYPE_STR, state->req_client,   
                  "kdcreq.server",      TYPE_STR, state->req_server,  
                  "kdcreq.kdc_options", TYPE_STR, state->req_kdc_options,
                  "kdcreq.start",       TYPE_NUM, req_from,  // state->req_from
                  "kdcreq.end",         TYPE_NUM, req_end,   // state->req_end
                  "kdcreq.renew_till",  TYPE_NUM, req_time,  // state->req_rtime 
                  /* reply */
                  "kdcrep.msg_type",    TYPE_STR,state->rep_msg_type,
                  "kdcrep.client",      TYPE_STR, state->rep_client,
                  "kdcrep.server",      TYPE_STR, state->rep_server,
                  "kdcrep.tkt.server",  TYPE_STR, state->rep_tkt_server,
                  "kdcrep.tkt.flags",   TYPE_NUM, rep_tkt_flags,    // state->rep_tkt_flags
                  "kdcrep.tkt.start",   TYPE_NUM, rep_tarttime,     // state->rep_tarttime
                  "kdcrep.tkt.end",     TYPE_NUM, rep_endtime,      // pstate->rep_endtime,
                  "kdcrep.tkt.renew_till",  TYPE_NUM, rep_renew_till,      // state->rep_renew_till
                  "kdcrep.tkt.authtime",    TYPE_NUM, rep_authtime,        // state->rep_authtime,
                  "kdcrep.tkt.tr_type",     TYPE_NUM, rep_transited_type   // state->rep_transited_type
                  "kdcrep.tkt.skey_etype",  TYPE_NUM, rep_session_enctype, // state->rep_session_enctype
                  "kdcrep.tkt.caddrs",      TYPE_STR, state->rep_caddrs
   );
   return rc;
}

Dictionary of the field names

The possible basic field names are:

• "event_id" for audit event ID
• "event_status" to indicate if the event is reported on success or failure.
• "tkt_id" for ticket ID;
• "client" and "server" for client and service principal names;
• "full_address" for address and portport
• "pa_error" for pre-authentication error;
• "skey_etype" and "avail_etypes" for available key types and chosen enc type;
• "sesskey_cleared" to indicate that session key was cleared;
• "start", "end" and "renew_till" for the ticket's start/end/renew-until times;
• "rep_flags" for reply flags;
• "kdc_status" for KDC status message;
• "plugins" and "plugins_base_dir" for available plugins (reported on KDC startup);
• etc.

Configuration

The following ./configure option to be added:

--with-audit-plugin=simple

(For demo and testing purposes) Build the audit plugin "simple" and enable audit plugin.

Test implementation

We will use libaudit module available on Fedora, Debian, Suse for the first round.

Some "simple" audit plugin will be implemented and Python test system will become aware of its existence. New ./configure --with-audit-plugin option will be introduced to build "simple" audit plugin for testing purpose. If audit is enabled and audit plugin is available, "make check" will store audit messages into audit log file.

References

1. Common Criteria for Information Technology Security Evaluation http://www.commoncriteriaportal.org/files/ccfiles/CCPART2V3.1R4.pdf
2. Oracle Solaris Auditing http://docs.oracle.com/cd/E19963-01/html/821-1456/auditov-1.html
3. Understanding Linux Audit http://doc.opensuse.org/products/draft/SLES/SLES-security_sd_draft/cha.audit.comp.html
4. Advanced Security Audit Policy Settings http://technet.microsoft.com/en-us/library/dd772712(v=ws.10).aspx
5. Events Classification in Log Audit http://airccse.org/journal/nsa/0410ijnsa5.pdf
6. CEE Log Syntax (CLS) Encoding http://cee.mitre.org/language/1.0-beta1/cls.html