View source for Projects/Audit

{{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 (JSON based) ===

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

==== KDC facing API ====

 /* Load/unload Audit plugin */
 krb5_error_code 
 load_audit_plugin(krb5_context context);
 krb5_error_code 
 unload_audit_plugin(krb5_context context);
 
 /* Record KDC event.
  * Here 'event_id' is an assigned ID of the auditable event and
  * 'status' indicates whether the event succeeded or failed. 
  */
 krb5_error_code 
 kau_kdc_event(krb5_context context, const int event_id, const int status, const char *audit_str);

 /* Helpers */
 
 /* Check if Audit plugin is loaded */
 krb5_boolean
 kau_isloaded(krb5_context context);
 
 /* Create a ticket ID */
 krb5_error_code
 kau_make_tkt_id(const krb5_keyblock sk, char **out);
 
 /* Basic serialization functions. */
 krb5_error_code
 kau_jenc_shandle(krb5_context context, int event_id, int status,
                  struct server_handle shdl, char **out);
 krb5_error_code
 kau_jenc_asreq(krb5_context context, int event_id, int status,
                struct as_req_state *state, char **out);
 krb5_error_code
 kau_jenc_tgsreq(krb5_context context, int event_id, int status,
                 struct tgs_reg_state *state, char **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);

==== Dictionary of the field names ====

One needs to define a dictionary of the field names to be used to describe the events in some unified way. 

The possible field names are:

* "tkt_id" for ticket ID;
* "client" and "server" for client and server principal names;
* "port" for client's port;
* "pa_error" for pre-authentication error;
* "ktype" and "avail_ktypes" for available key types and used keytype;
* "sesskey_cleared" to indicate that session key was cleared;
* "tkt_start", "tkt_end" and "tkt_renewtill" for the ticket's start/end/renewed-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.

Also, "event_id" and "event_status" for audit event ID and to indicate if the event is reported on success or failure. (Most likely these two already have some standard names)
                            
==== Example ====

The typical call on KDC side (AS-REQ):

 krb5_error_code rc = 0;
 char *aud_str = NULL;
 struct as_req_state *state;
 ...
 if (kau_isloaded(kdc_context) == TRUE) {
    /* JSON encode as_req_state */
    rc = kau_jenc_asreq(kdc_context, AS_REQ, 0, state, &aud_str);   
    if (!rc && aud_str != NULL) {
       rc = kau_kdc_event(kdc_context, AS_REQ, 0, aud_str)
       free(aud_str);
    }
 }


=== Design 1 (one-API-per-event) ===

This design exercises the idea of one-API-per-KDC-event.  The benefit of this approach is it's very low cost to KDC.

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