2013-07-29T15:26:26Z

Tsitkova:

{{project-early}}

== 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 and flexible, so it could be easily replaced with the OS specific and third-parties implementations;

== Events ==

(Common Criteria Class FIA)

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

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

2. AS_REQ and TGS_REQ:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Phase
! style="padding-left: 2em; padding-right: 2em;" | Data to be logged
! AS_REQ
! TGS_REQ
|-
|rowspan=3|Authenticate request content and client
| client’s address and port || ✔ || ✔
|-
| original KDC request and [[#Request ID| request ID ]] || ✔ || ✔
|-
| primary [[#Ticket ID|ticket ID]] || ✗ ||(S4U:front-end server's) TGT
|-
|rowspan=3|Determine service principal
| modified KDC request and [[#Request ID|request ID]] ||✔ || ✔
|-
| cross-realm referral || ✗ || service principal, TGS
|-
| user-to-user: client in the 2nd ticket || ✗ ||✔
|-
|rowspan=2|Validate policies
| local policy violation ||✔ || ✔
|-
| protocol constraints ||✗ || S4U2Proxy, S4U2Self
|-
|rowspan=5|Issue ticket
| ticket renewed ||✗ || ✔
|-
| ticket validated ||✗ || ✔
|-
| session key enctype (short-term) ||✔ || ✔
|-
| enctype of the service's long-term key||✗ || ✔
|-
| derived [[#Ticket ID|ticket ID]]|| TGT || service or referral TGT
|-
|rowspan=2|Encrypt reply
| KDC reply ||✔ || ✔
|-
| Reply-encrypting key enctype (long-term) ||✔ || ✔
|-
|rowspan=1|All phases
| KDC status || on error ||on error and "ISSUE"
|-
|}

The implementors of audit plugin will be able to extract the following auditable information:

KDC request:
: requested service principal;
: client’s principal;
: KDC options;
: requested ticket start, end and renew_till times;
: list of requested addresses;
: requested enctypes;
: preauth types

KDC reply:
: preauth types;
: TGT, referral TGT or service ticket with the following level of details:
::client and server principals;
::flags;
::start, end and renew_till times;
::authtime;
::authentication path - encoded list of transited realms for service ticket or referral TGT (for TGS only);

Other events to consider for the future development:

3. Policy
:Policies violation - event description, reason and how to fix it;
4. Secrets (Common Criteria FCS_CKM.1, FCS_CKM.4);
:long- and short-term keys creation, manipulation, cleaning.

== Design details ==

====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.

For the purpose of this project we will create a private to KDC ticket ID: each successfully created ticket will be hashed and recorded into audit log. The administrators will correlate the primary and derived ticket IDs after the fact.

For the future, however, we need a more complex system that would allow to tie the tickets from a successful AS_REQ all the way to the application server. It is marked as an action item in [[#Future work|this]] section.

====Request ID====
Request ID - hash of the request is recorded as part of audit messages. Using this piece of information an administrator can easily correlate multiple audit events related to a single request.

=== 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);
krb5_boolean
kau_isloaded(krb5_context context);
/* event specific functions */
krb5_error_code
kau_kdc_start(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_kdc_stop(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_asreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_tgsreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2self(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2proxy(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_u2u(krb5_context context, const int event_id, const int status, audit_state *state);
/* utilities */
krb5_error_code
kau_init_kdc_req(krb5_context context, krb5_kdc_req *request, const krb5_fulladdr *from, audit_state **au_state);
krb5_error_code
kau_make_tkt_id(krb5_context context, const krb5_ticket *ticket, char **out);
krb5_error_code
kau_make_req_id(krb5_context context, const krb5_kdc_req *request, char **out);

where ''event_id'' references to the ''Phase'' (left column of [[#Events| events]] table), and ''audit_state'' structure holds the following information:

typedef struct _audit_state {
krb5_kdc_req *req_in; /* request in the original form */
krb5_kdc_req *req_mod; /* modified (per protocol) request */
krb5_kdc_rep *reply;
const krb5_fulladdr *from;
const char *status; /* KDC status message */
char *tkt_in_id; /* primary (TGT) ticket ID */
char *tkt_out_id; /* derived (service or referral TGT) ticket ID */
char *evid_tkt_id; /* for s4u2proxy - user's evidence ticket ID, for u2u - TGT ticket ID */
char *req_in_id; /* original-request ID */
char *req_mod_id; /* modified-request ID */
krb5_int32 sess_etype; /* session key enctype */
krb5_int32 srv_etype; /* enctype of the long-term key of service */
krb5_int32 rep_etype; /* reply-encrypting key enctype */
krb5_boolean tkt_renewed;
krb5_boolean tkt_validated;
/* referrals */
krb5_data *cl_realm; /* remote client's realm */
/* s4u and u2u */
krb5_principal s4u2self_user; /* impersonated user */
krb5_principal s4u2proxy_user; /* delegated user */
krb5_principal u2u_user; /* client for the second ticket */
char *violation; /* local or protocol policy problem */
} audit_state;

=== Pluggable interface ===

/* Audit plugin vtable */
typedef struct krb5_audit_vtable_st {
/* Mandatory: name of module. */
char *name;
int conf_options;
kau_open_fn open;
kau_close_fn close;
kau_kdc_start_fn kdc_start;
kau_kdc_stop_fn kdc_stop;
kau_as_req_fn as_req;
kau_tgs_req_fn tgs_req;
kau_s4u2self_fn tgs_s4u2self;
kau_s4u2proxy_fn tgs_s4u2proxy;
kau_u2u_fn tgs_u2u;;
} *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);
typedef krb5_error_code
(*kau_kdc_start_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_kdc_stop_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_as_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_tgs_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2self_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2proxy_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_u2u_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);

== Dictionary==

The following are proposed basic field names for JSON parsing:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Key
! style="padding-left: 2em; padding-right: 2em;" | Type
! Comments
|-
| tkt_id_in || style="padding-left: 2em "| STR || primary (TGT) ticket ID
|-
| tkt_id_out || style="padding-left: 2em "| STR || derived (service or referral TGT) ticket ID
|-
| client || style="padding-left: 2em "| STR|| client’s principal
|-
| service || style="padding-left: 2em "| STR|| requested service principal
|-
| kdc_status || style="padding-left: 2em "| STR|| KDC status (“ISSUE” on success)
|-
| full_address || style="padding-left: 2em "| STR || Alternative to "fromport"/"fromaddr"
|-
|sess_etype || style="padding-left: 2em "| NUM || enctype of session key
|-
|rep_etype || style="padding-left: 2em "| NUM || enctype of reply-encrypting key
|-
|srv_etype || style="padding-left: 2em "| NUM || enctype of long-term key of the service key
|-
|tkt_renewed|| style="padding-left: 2em "| BOOL || was ticket renewed
|-
|tkt_validated|| style="padding-left: 2em "| BOOL || was ticket validated
|-
|req.addresses || style="padding-left: 2em "| STR || requested addresses
|-
|req.avail_etypes || style="padding-left: 2em "| STR || requested/available enc types
|-
|req.kdc_options || style="padding-left: 2em "| NUM || KDC options (forwardable, allow_postdate etc)
|-
|req.pa_type || style="padding-left: 2em "| STR|| preauth types
|-
|req.tkt_start || style="padding-left: 2em "| NUM || requested ticket start time
|-
|req.tkt_end || style="padding-left: 2em "| NUM || requested ticket end time
|-
|req.tkt_renew_till || style="padding-left: 2em "| NUM || requested ticket renew-till time
|-
|req.tkt_authtime || style="padding-left: 2em "| NUM || requested ticket authtime
|-
| req.sectkt_cname|| style="padding-left: 2em "| STR || client principal in the second ticket (U2U etc)
|-
| req.sectkt_sname|| style="padding-left: 2em "| STR || service principal in the second ticket
|-
| req.sectkt_flags|| style="padding-left: 2em "| NUM || second ticket flags
|-
| req.sectkt_start|| style="padding-left: 2em "| NUM || second ticket start time
|-
| req.sectkt_end|| style="padding-left: 2em "| NUM || second ticket end time
|-
| req.sectkt_authtime|| style="padding-left: 2em "| NUM || second ticket authtime
|-
| req.sectkt_etype|| style="padding-left: 2em "| NUM || second ticket key type
|-
|req.sname || style="padding-left: 2em "| STR || requested service principal
|-
| req.cname || style="padding-left: 2em "| STR || client's principal
|-
|rep.sname || style="padding-left: 2em "| STR || service principal in ticket
|-
| rep.cname || style="padding-left: 2em "| STR || client principal in ticket
|-
| rep.pa_type || style="padding-left: 2em "| STR || reply preauth types
|-
| rep.rep_flags || style="padding-left: 2em "| NUM || ticket flags
|-
| rep.rep_authtime || style="padding-left: 2em "| NUM || ticket authtime
|-
| rep.tkt_start || style="padding-left: 2em "| NUM || ticket start time
|-
| rep.tkt_end || style="padding-left: 2em "| NUM || ticket end time
|-
| rep.tkt_renew_till|| style="padding-left: 2em "| NUM || ticket renewed-till time
|-
|rep.tr_contents|| style="padding-left: 2em "| STR|| ticket transited-realms list
|-
|}

== 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.

==Future work==

# Standardize a Ticket_ID;
# Make reporting auditable events configurable. For example, one can choose to report TGS_REQ, but not AS_REQ;
# Sanitize ''KDC request'' and ''KDC reply'' before passing them to the concrete audit implementation: security sensitive information should not leave KDC boundaries;
# Develop Audit system for Preauth and Authdata mechanisms.

== 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 ==

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

2013-05-29T18:26:29Z

Tsitkova: Extended Dictionary section

{{project-early}}

== 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===
:: Startup and shutdown of the KDC must be recorded by audit system;

===Authentication===
(Common Criteria Class FIA)

====AS exchange====
:: [[#Ticket ID|ticket ID]] (if available);
:: KDC time;
:: client’s principal;
:: requested service principal;
:: KDC status message (“ISSUE” on success);
:: client’s address and port;
:: PA error;
:: chosen by KDC enctype;
:: session key cleared (Common Criteria FCS_CKM.1, FCS_CKM.4);
:: kdc request:
::: kdc options;
::: requested ticket start/end/renew_till times;
::: requested/available enctypes;
::: 2nd [[#Ticket details|ticket]];
::: AD type;
::: PA type;
::: addresses;
:: kdc reply:
::: [[#Ticket details|ticket]];
::: client principal;
::: PA type.

====TGS exchange====
:: [[#Ticket ID|ticket ID]] (if available);
:: KDC time;
:: KDC status message (“ISSUE” on success);
:: client’s address and port;
:: chosen by KDC enctype;
:: session key cleared (Common Criteria FCS_CKM.1, FCS_CKM.4);
:: client’s flags;
:: cross realm name;
:: alternate client principal;
:: alternate server principal;
:: u2u requested server principal;
:: is it referral request;
:: was ticket renewed;
:: kdc request:
::: requested service principal;
::: client’s principal;
::: addresses;
::: requested/available enctypes;
::: KDC options;
::: number of second [[#Ticket details|tickets]];
::: requested ticket start/end/renew_till times;
::: AD type;
::: PA type;
:: kdc reply:
::: client principal;
::: PA type;
::: [[#Ticket details|ticket]].

====Policy====
:: Policies violation when processing requests;
::AS request;
::TGS request;
::S4U2PROXY request.

====Ticket details====
::client and server principals;
::flags;
::start/end/renew_till times;
::authtime;
::transited encoding type and contents;
::key type;
::addresses.

== Design details ==

The following are highlights of this new feature:

====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.

====Hybrid====
The proposal is a hybrid of variadic key-type-value triplet (KTV) and one-API-per-event approaches.

On the KDC side call audit event-specific functions, whose input consists of the event-id, event-status and event-specific structure. If event-specific callback is implemented by the audit plugin, strip the event-specific structure from the security sensitive information and then pass the pointer to the event-specific structure to the plugin. Otherwise, fallback to the generic function with variadic KTV arguments. In the latter case all non-string values should be converted into the strings and the key-types serve as a hint to the plugin implementor about 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 */
"req.msg_type", TYPE_STR, state->req_msg_type,
"req.client", TYPE_STR, state->req_client,
"req.server", TYPE_STR, state->req_server,
"req.kdc_options", TYPE_STR, state->req_kdc_options,
"req.start", TYPE_NUM, req_from, // state->req_from
"req.end", TYPE_NUM, req_end, // state->req_end
"req.renew_till", TYPE_NUM, req_time, // state->req_rtime
/* reply */
"rep.msg_type", TYPE_STR,state->rep_msg_type,
"rep.client", TYPE_STR, state->rep_client,
"rep.server", TYPE_STR, state->rep_server,
"rep.tkt.server", TYPE_STR, state->rep_tkt_server,
"rep.tkt.flags", TYPE_NUM, rep_tkt_flags, // state->rep_tkt_flags
"rep.tkt.start", TYPE_NUM, rep_tarttime, // state->rep_tarttime
"rep.tkt.end", TYPE_NUM, rep_endtime, // pstate->rep_endtime,
"rep.tkt.renew_till", TYPE_NUM, rep_renew_till, // state->rep_renew_till
"rep.tkt.authtime", TYPE_NUM, rep_authtime, // state->rep_authtime,
"rep.tkt.tr_type", TYPE_NUM, rep_transited_type // state->rep_transited_type
"rep.tkt.skey_etype", TYPE_NUM, rep_session_enctype, // state->rep_session_enctype
"rep.tkt.caddrs", TYPE_STR, state->rep_caddrs
);
return rc;
}

== Dictionary==

The possible basic field names are:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Key
! style="padding-left: 2em; padding-right: 2em;" | Type
! Comments
|-
| tkt_id || style="padding-left: 2em "| STR || ticket ID
|-
| kdc_time || style="padding-left: 2em "| NUM || KDC time
|-
| client || style="padding-left: 2em "| STR|| client’s principal
|-
| service || style="padding-left: 2em "| STR|| requested service principal
|-
| kdc_status || style="padding-left: 2em "| TR|| KDC status (“ISSUE” on success)
|-
| fromaddr || style="padding-left: 2em "| STR|| client’s address
|-
|fromport || style="padding-left: 2em "| NUM || client’s port
|-
| full_address || style="padding-left: 2em "| STR|| Alternative to "fromport"/"fromaddr"
|-
| pa_err || style="padding-left: 2em "| NUM || PA error
|-
|skey_etype || style="padding-left: 2em "| NUM || chosen by KDC session key enc type
|-
|skey_cleared || style="padding-left: 2em "| BOOL || was session key cleared
|-
|xrealm|| style="padding-left: 2em "| STR || cross realm name
|-
|altc_princ|| style="padding-left: 2em "| STR || alternate client principal
|-
|alts_princ || style="padding-left: 2em "| STR || alternate server principal
|-
|server2 || style="padding-left: 2em "| STR || u2u requested server principal
|-
|is_referral|| style="padding-left: 2em "| BOOL || is it referral request
|-
|tkt_renewed|| style="padding-left: 2em "| BOOL || was ticket renewed
|-
|req.addresses || style="padding-left: 2em "| STR || requested addresses
|-
|req.avail_etypes || style="padding-left: 2em "| STR || requested/available enc types
|-
|req.kdc_options || style="padding-left: 2em "| NUM || KDC options (forwardable, allow_postdate etc)
|-
|req.pa_type || style="padding-left: 2em "| STR|| PA type
|-
|req.ad_type || style="padding-left: 2em "| STR || AD type
|-
|req.tkt_start || style="padding-left: 2em "| NUM || requested ticket start time
|-
|req.tkt_end || style="padding-left: 2em "| NUM || requested ticket end time
|-
|req.tkt_renew_till || style="padding-left: 2em "| NUM || requested ticket renew-till time
|-
| req.num_secondtkt|| style="padding-left: 2em "| NUM || number of second tickets (U2U etc)
|-
|req.sname || style="padding-left: 2em "| STR || requested service principal
|-
| req.cname || style="padding-left: 2em "| STR || client's principal
|-
|rep.sname || style="padding-left: 2em "| STR || service principal in ticket
|-
| rep.cname || style="padding-left: 2em "| STR || client principal in ticket
|-
| rep.pa_type || style="padding-left: 2em "| STR || reply PA type
|-
| rep.caddrs || style="padding-left: 2em "| STR || addresses in ticket
|-
| rep.rep_flags || style="padding-left: 2em "| NUM || ticket flags
|-
| rep.ad_type || style="padding-left: 2em "| STR || ticket AD type
|-
| rep.rep_authtime || style="padding-left: 2em "| NUM || ticket authtime
|-
| rep.tkt_start || style="padding-left: 2em "| NUM || ticket start time
|-
| rep.tkt_end || style="padding-left: 2em "| NUM || ticket end time
|-
| rep.tkt_renew_till|| style="padding-left: 2em "| NUM || ticket renewed-till time
|-
|rep.tr_type|| style="padding-left: 2em "| NUM || ticket transited type
|-
|rep.tr_contents|| style="padding-left: 2em "| STR|| ticket transited-realms list
|-
|}

== 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.

== Future work ==

# Make reporting auditable events configurable. For example, one can choose to report TGS_REQ, but not AS_REQ etc;
# Define and make configurable the DETAILED and BASIC levels of the events.

== 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 ==

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

Projects/Audit

2013-05-28T16:12:27Z

Tsitkova: Add "Future work" and more details on events

Projects/Reputation

2013-05-22T17:25:18Z

Tsitkova: initial version

{{project-early}}

== Use Case ==

Client requests an anonymous ticket. The client is known to KDC, but he wants to stay anonymous with the application server. KDC calculates the client's "reputation" score and issues the ticket that contains this score (together with all other useful information). The factors that can contribute to the score are, for example, the client's history, various behavioral/network patterns, privileges etc. Based on this knowledge the receiver of the anonymous ticket may decide on the timing or content of the service, etc.

The other use cases are feasible.

==Purpose==

Create a pluggable Client Reputation infrastructure that would allow to associate a "trustworthy" score with a client.

== Score and weights ==

The contributing factors into the score calculation and their weights should be configurable and may consist of:

#. When the user account was created;
#. How active is the user;
#. user's privileges;
#. DNS/network topology history;

2013-02-11T17:10:37Z

Tsitkova: New design based on serialization.

{{project-early}}

== 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 basic information: 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:
::Basic information: client principal name; requested service name; remote port; selected keytype for the ticket session key; pre-authentication error; KDC status message;
::On success: ticket id; returned ticket start, end and renew until times; ticket flags;
:TGS exchange:
::TGS
:::Basic information: ticket id; client principal name; requested service name; remote port; authtime timestamp; selected keytype for the ticket session key; KDC status message; if the request is for referral ticket indicate to which server;
:::On success: returned ticket start, end and renew until times; ticket flags; if the request was to renew ticket – indicate that ticket was renewed;
::Alternate
:::Basic information: ticket id; client principal name; requested service name; authtime timestamp; KDC status message;
:::On success: alternate TGT
::Cross-realm
:::Basic information: ticket id; client principal name; requested service name, remote port; authtime timestamp; KDC status message;
:::On success: cross-realm TGT
::U2U
:::Basic information: ticket id; client principal name; requested service name; authtime timestamp; KDC status message;
:::On success: second ticket client and server name
:Policy: Policies violation when processing requests - TBD;
::AS request; TGS request; S4U2PROXY request
;Session keys :
:(Common Criteria FCS_CKM.1, FCS_CKM.4):
: AS and TGS exchange: ticket id; client principal name; requested service name, remote port; authtime timestamp; keytype list in request and selected keytype for the ticket session key;
: AS and TGS exchange: ticket id; session key cleaning;

== Design details ==

=== 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.

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

=== Design 2 (newer) ===

This approach is based on serialization of the KDC auditable events.

==== 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);

/* Record KDC event */
krb5_error_code
kau_kdc_event(krb5_context context, int event_id, int status, char *audit_str);

/* Helpers */
/* Check if audit plugin is loaded */
krb5_boolean
kau_isloaded(krb5_context context);

/* Basic serialization functions */
krb5_error_code
kau_jenc_shandle(krb5_context context, int event_id, int status,
struct server_handle shdl, char **str_out);

krb5_error_code
kau_jenc_asreq(krb5_context context, int event_id, int status,
struct as_req_state *state, char **str_out);

krb5_error_code
kau_jenc_tgsreq(krb5_context context, int event_id, int status,
struct tgs_reg_state *state, char **str_out);

==== 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_record_fn record;
} *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);

typedef krb5_error_code
(*kau_record_fn)(kau_ctx au_ctx, const int event_id, const int status,
const char *audit_string);

=== Design 1 (older) ===

This design exercises the idea of one-API-per-KDC-event.

==== 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);

/* KDC started /stopped */
krb5_error_code
kau_kdc_start(krb5_context context, int status);
krb5_error_code
kau_kdc_stop(krb5_context context, krb5_error_code status);

/* AS exchange: Successful (status=1) or unsuccessful (status=0) attempt */
krb5_error_code
kau_as_req(krb5_context context, struct as_req_state *state, int status);
krb5_error_code
kau_as_req_pa(krb5_context context, struct as_req_state *state, int status);

/* TGS exchange: Successful (status=1) or unsuccessful (status=0) attempt; alternate, u2u, s4u and cross-realm TGS */
krb5_error_code
kau_tgs(krb5_context context,
struct tgs_req_audit_state *state, int status);
krb5_error_code
kau_tgs_alt(krb5_context context,
struct tgs_req_audit_state *state, int status);
krb5_error_code
kau_tgs_u2u(krb5_context context, struct tgs_req_audit_state *state,
krb5_principal cl2, int status);
krb5_error_code
kau_tgs_xrealm(krb5_context context, struct tgs_req_audit_state *state,
char* xrealm, int status);

/* Policy driven events - TBD */
krb5_error_code
kau_policy_as_req(krb5_context context, struct as_req_state *state,
krb5_error_code status);
krb5_error_code
kau_policy_s4u2proxy_req(krb5_context context, struct tgs_req_audit_state *state,
krb5_db_entry *st_client, krb5_error_code status);
krb5_error_code
kau_policy_tgs_req(krb5_context context, struct tgs_req_audit_state *state,
krb5_ticket *header_ticket, krb5_error_code status);

/* Session key generation and cleaning up */
krb5_error_code
kau_sesskey_as_generated(krb5_context context,
struct as_req_state *state, int status);
krb5_error_code
kau_sesskey_as_cleared(krb5_context context,
struct as_req_state *state, int status);
krb5_error_code
kau_sesskey_tgs_generated(krb5_context context,
struct tgs_req_audit_state *state,int status);
krb5_error_code
kau_sesskey_tgs_cleared(krb5_context context,
struct tgs_req_audit_state *state, int status);

/* Name of audit module */
krb5_error_code
kau_plugin_name(krb5_context context, char **name);

struct as_req_state {
loop_respond_fn respond;
void *arg;
...
kdc_realm_t *active_realm;
krb5_error_code preauth_err;
char *tkt_id;
};

struct tgs_req_audit_state {
krb5_kdc_req *request;
krb5_timestamp authtime;
char *sname, *cname, *s4u_name, *u2ucname;
krb5_principal altprinc;
char *xrealm;
const krb5_fulladdr *from;
unsigned int c_flags;
const char *status; /* KDC status message */
krb5_enctype useenctype;
krb5_boolean tkt_renewed;
krb5_boolean is_referral;
char *tkt_id;
};

==== 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_kdc_start_fn kdc_start;
kau_kdc_stop_fn kdc_stop;
kau_as_req_fn as_req;
kau_tgs_fn tgs;
kau_tgs_alt_fn tgs_alt;
kau_tgs_u2u_fn tgs_u2u;
kau_tgs_xrealm_fn tgs_xrealm;
kau_policy_as_req_fn policy_as_req;
kau_policy_tgs_req_fn policy_tgs_req;
kau_policy_s4u2proxy_req_fn policy_s4u2proxy_req;
kau_sesskey_as_generated_fn sesskey_as_generated;
kau_sesskey_as_cleared_fn sesskey_as_cleared;
kau_sesskey_tgs_generated_fn sesskey_tgs_generated;
kau_sesskey_tgs_cleared_fn sesskey_tgs_cleared;
} *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);

typedef krb5_error_code
(*kau_kdc_start_fn)(kau_ctx au_ctx,
krb5_deltat clockskew, const char *realm_port,
krb5_boolean allow_weak_crypto,
const char *plugins, const char *plugin_dir, int status);

typedef krb5_error_code
(*kau_kdc_stop_fn)(kau_ctx au_ctx, krb5_error_code status);

typedef krb5_error_code
(*kau_as_req_fn)(kau_ctx au_ctx, const char *tkt_id,
const char *cname, const char *sname,
const int from_port, krb5_enctype sesskey_etype,
krb5_flags tkt_flags, const char *tkt_cname,
krb5_deltat tkt_start_time, krb5_deltat tkt_end_time, krb5_deltat tkt_renew_till,
const char *kdc_status, int status);

typedef krb5_error_code
(*kau_tgs_fn)(kau_ctx au_ctx, const char *tkt_id,
krb5_timestamp authtime,
const char *cname, const char *sname,
const int from_port, krb5_enctype session_key_etype,
const int is_referral, const int tkt_renewed,
krb5_flags tkt_flags, krb5_deltat tkt_start_time,
krb5_deltat tkt_end_time, krb5_deltat tkt_renew_till,
const char *kdc_status, int status);

typedef krb5_error_code
(*kau_tgs_alt_fn)(kau_ctx au_ctx, const char *tkt_id,
krb5_timestamp authtime,
const char *cname, const char *sname, const char *altsrv,
const int from_port, const char *kdc_status, int status);

typedef krb5_error_code
(*kau_tgs_u2u_fn)(kau_ctx au_ctx, const char *tkt_id,
krb5_timestamp authtime,
const char *cname, const char *sname,
const char *cl2, const char *srv2,
const int from_port, const char *kdc_status, int status);

typedef krb5_error_code
(*kau_tgs_xrealm_fn)(kau_ctx au_ctx, const char *tkt_id,
krb5_timestamp authtime,
const char *cname, const char *sname, const char *xrealm,
krb5_flags c_flags, krb5_flags s_flags,
const int from_port, const char *kdc_status, int status);

typedef krb5_error_code
(*kau_sesskey_as_generated_fn)(kau_ctx au_ctx, const char *tkt_id,
const char *cname, const char *sname,
const int from_port,
const char * ktypes, krb5_enctype used_ktype,
const char *kdc_status, int status);

typedef krb5_error_code
(*kau_sesskey_as_cleared_fn)(kau_ctx au_ctx, const char *tkt_id,
const char *cname, const char *sname,
const int from_port, krb5_enctype used_ktype,
const char *kdc_status, int status);

typedef krb5_error_code
(*kau_sesskey_tgs_generated_fn)(kau_ctx au_ctx, const char *tkt_id,
const char *cname, const char *sname,
const int from_port,
const char *ktypes, krb5_enctype used_ktype,
const char *kdc_status, int status);

typedef krb5_error_code
(*kau_sesskey_tgs_cleared_fn)(kau_ctx au_ctx, const char *tkt_id,
const char *cname, const char *sname,
const int from_port, krb5_enctype used_ktype,
const char *kdc_status, int status);

== 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 ==

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