KDC Audit infrastructure and plugin implementation

Per project http://k5wiki.kerberos.org/wiki/Projects/Audit

The purpose of this project is to create an Audit infrastructure to monitor
security related events on the KDC.

The following events are targeted in the initial version:
- startup and shutdown of the KDC;
- AS_REQ and TGS_REQ exchanges.  This includes client address and port, KDC
  request and request ID, KDC reply, primary and derived ticket and their
  ticket IDs, second ticket ID, cross-realm referral, was ticket renewed and
  validated, local policy violation and protocol constraints, and KDC status
  message.

Ticket ID is introduced to allow to link tickets to their initial TGT at any
stage of the Kerberos exchange. For the purpose of this project it is a private
to KDC ticket ID: each successfully created ticket is hashed and recorded
into audit log. The administrators can correlate the primary and derived
ticket IDs after the fact.

Request ID is a randomly generated alpha-numeric string. Using this ID an
administrator can easily correlate multiple audit events related to a single
request. It should be informative both in cases when the request is sent to
multiple KDCs, or to the same KDC multiple times.

For the purpose of testing and demo of the Audit, the JSON based modules are
implemented: "test" and "simple" audit modules respectively.
The file plugins/audit/j_dict.h is a dictionary used in this implememtations.

The new Audit system is build-time enabled and run-time pluggable.

[kaduk@mit.edu: remove potential KDC crashes, minor reordering]

ticket: 7712
target_version: 1.12

2 files changed, 272 insertions, 1 deletions

diff --git a/src/include/k5-int.h b/src/include/k5-int.h
index 2eda47cf37..623f09e655 100644
--- a/src/include/k5-int.h
+++ b/src/include/k5-int.h
@@ -1077,7 +1077,8 @@ struct plugin_interface {
 #define PLUGIN_INTERFACE_CCSELECT    4
 #define PLUGIN_INTERFACE_LOCALAUTH   5
 #define PLUGIN_INTERFACE_HOSTREALM   6
-#define PLUGIN_NUM_INTERFACES        7
+#define PLUGIN_INTERFACE_AUDIT       7
+#define PLUGIN_NUM_INTERFACES        8
 
 /* Retrieve the plugin module of type interface_id and name modname,
  * storing the result into module. */
diff --git a/src/include/krb5/audit_plugin.h b/src/include/krb5/audit_plugin.h
new file mode 100644
index 0000000000..b6e90649a0
--- /dev/null
+++ b/src/include/krb5/audit_plugin.h
@@ -0,0 +1,270 @@
+/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/* include/krb5/audit_plugin.h - Audit plugin interface */
+/*
+ * Copyright (C) 2013 by the Massachusetts Institute of Technology.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in
+ *   the documentation and/or other materials provided with the
+ *   distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+ * OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+/*
+ * NOTE: This is a private interface and may change incompatibly
+ *       between versions.
+ */
+/*
+ * Declarations for KDC audit plugin module implementers.  Audit modules allow
+ * the KDC to produce log output or audit records in any desired form.
+ *
+ * The audit interface has a single supported major version, which is 1.  Major
+ * version 1 has a current minor version of 1.  Audit modules should define a
+ * function named audit_<modulename>_initvt, matching the signature:
+ *
+ *   krb5_error_code
+ *   audit_modname_initvt(krb5_context context, int maj_ver, int min_ver,
+ *                        krb5_plugin_vtable vtable);
+ *
+ * The initvt function should:
+ *
+ * - Check that the supplied maj_ver number is supported by the module, or
+ *   return KRB5_PLUGIN_VER_NOTSUPP if it is not.
+ *
+ * - Cast the vtable pointer as appropriate for the interface and maj_ver:
+ *   maj_ver == 1: Cast to krb5_audit_vtable
+ *
+ * - Initialize the methods of the vtable, stopping as appropriate for the
+ *   supplied min_ver.  Optional methods may be left uninitialized.
+ *
+ * Memory for the vtable is allocated by the caller, not by the module.
+ */
+
+#ifndef KRB5_AU_PLUGIN_H_INCLUDED
+#define KRB5_AU_PLUGIN_H_INCLUDED
+#include <krb5/krb5.h>
+
+/** KDC processing steps */
+#define AUTHN_REQ_CL 1 /**< Authenticate request and client */
+#define SRVC_PRINC   2 /**< Determine service principal */
+#define VALIDATE_POL 3 /**< Validate local and protocol policies */
+#define ISSUE_TKT    4 /**< Issue ticket */
+#define ENCR_REP     5 /**< Encrypt reply */
+
+/** Types of violations */
+#define PROT_CONSTRAINT 1 /**< Protocol constraint */
+#define LOCAL_POLICY    2 /**< Local policy violation */
+
+#define REQID_LEN 32 /* Size of the alpha-numeric request ID */
+
+/** KDC audit state structure and declarations */
+typedef struct _krb5_audit_state {
+    krb5_kdc_req *request;
+    krb5_kdc_rep *reply;
+    krb5_address *cl_addr; /**< client address */
+    krb5_ui_4 cl_port;     /**< client port */
+    int stage;             /**< step in KDC processing */
+    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 */
+    /** for s4u2proxy - evidence ticket ID; for u2u - second ticket ID */
+    char *evid_tkt_id;
+    char req_id[REQID_LEN];  /**< request ID */
+    krb5_data *cl_realm;     /**< referrals: remote client's realm */
+    krb5_principal s4u2self_user; /**< impersonated user */
+    int violation;           /**< local or protocol policy problem */
+} krb5_audit_state;
+
+/** An abstract type for audit module data. */
+typedef struct krb5_audit_moddata_st *krb5_audit_moddata;
+
+/*
+ * Mandatory:
+ * - krb5_audit_open_fn,
+ * Open connection to the audit system and initialize audit module data.  If
+ * the underlying (OS or third party) audit facility fails to open, no
+ * auditable KDC events should be recorded.
+ */
+typedef krb5_error_code
+(*krb5_audit_open_fn)(krb5_audit_moddata *auctx);
+
+/*
+ * Mandatory:
+ * - krb5_audit_close_fn.
+ * Close connection to the underlying audit system.
+ */
+typedef krb5_error_code
+(*krb5_audit_close_fn)(krb5_audit_moddata auctx);
+
+/**
+ * Log KDC-start event.
+ *
+ * @param [in] auctx       Audit context
+ * @param [in] ev_success  Success/failure of the event being audited
+ *
+ * @note Optional.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+typedef krb5_error_code
+(*krb5_audit_kdc_start_fn)(krb5_audit_moddata auctx, krb5_boolean ev_success);
+
+/**
+ * Log KDC-stop event.
+ *
+ * @param [in] auctx       Audit context
+ * @param [in] ev_success  Success/failure of the event being audited
+ *
+ * @note Optional.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+typedef krb5_error_code
+(*krb5_audit_kdc_stop_fn)(krb5_audit_moddata auctx, krb5_boolean ev_success);
+
+/**
+ * Log AS exchange event.
+ *
+ * @param [in] auctx       Audit context
+ * @param [in] ev_success  Success/failure of the event being audited
+ * @param [in] state       AS-request related auditable information
+ *
+ * The @a state provides the following data:
+ * - Full information about KDC request, assigned request ID, client address
+ *   and port, and stage of the AS exchange
+ * - If available, the information about the encryption types of the short- and
+ *   long-term keys, non-local client's referral realm, KDC status, the TGT
+ *   and its ticket ID
+ *
+ * @note Optional.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+typedef krb5_error_code
+(*krb5_audit_as_req_fn)(krb5_audit_moddata auctx,
+                        krb5_boolean ev_success, krb5_audit_state *state);
+
+/**
+ * Log TGS exchange event.
+ *
+ * @param [in] auctx       Audit context
+ * @param [in] ev_success  Success/failure of the event being audited
+ * @param [in] state       TGS-request related auditable information
+ *
+ * The @a state provides the following data:
+ * - Full information about KDC request, assigned request ID, primary ticket
+ *   ID, client address and port, and stage of the TGS exchange
+ * - If available, the information about the encryption types of the short- and
+ *   long-term keys, KDC status, KDC reply, and the output ticket ID
+ *
+ * @note Optional.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+typedef krb5_error_code
+(*krb5_audit_tgs_req_fn)(krb5_audit_moddata auctx,
+                         krb5_boolean ev_success, krb5_audit_state *state);
+
+/**
+ * Log S4U2SELF event.
+ *
+ * @param [in] auctx       Audit context
+ * @param [in] ev_success  Report on success or failure
+ * @param [in] state       s4u2self related auditable information
+ *
+ * The @a state provides the following data:
+ * - Full information about KDC request, assigned request ID, client address
+ *   and port, and stage of the TGS exchange
+ * - Requesting server's TGT ID, impersonated user principal name, and service
+ *   "to self" ticket or referral TGT ID
+ * - If available, KDC status, local policy violation or S4U protocol
+ *   constraints
+ *
+ * @note Optional.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+typedef krb5_error_code
+(*krb5_audit_s4u2self_fn)(krb5_audit_moddata auctx,
+                          krb5_boolean ev_success, krb5_audit_state *state);
+
+/**
+ * Log S4U2PROXY event.
+ *
+ * @param [in] auctx       Audit context
+ * @param [in] ev_success  Report on success or failure
+ * @param [in] state       s4u2proxy related auditable information
+ *
+ * The @a state provides the following data:
+ * - Full information about request, assigned request ID, client address and
+ *   port, and stage of the TGS exchange
+ * - Requesting server's TGT ID, delegated user principal name, and evidence
+ *   ticket ID
+ * - If available, KDC status, local policy violation or S4U protocol
+ *   constraints
+ *
+ * @note Optional.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+typedef krb5_error_code
+(*krb5_audit_s4u2proxy_fn)(krb5_audit_moddata auctx,
+                           krb5_boolean ev_success, krb5_audit_state *state);
+
+/**
+ * Log U2U event.
+ *
+ * @param [in] auctx       Audit context
+ * @param [in] ev_success  Report on success or failure
+ * @param [in] state       user-to-user related auditable information
+ *
+ * The @a state provides the following data:
+ * - Full information about request, assigned request ID, client address and
+ *   port, and stage of the TGS exchange,
+ * - Requestor's TGT ID, service ticket ID, and client's principal name in the
+ *   second ticket
+ * - If available, KDC status
+ *
+ * @note Optional.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+typedef krb5_error_code
+(*krb5_audit_u2u_fn)(krb5_audit_moddata auctx,
+                     krb5_boolean ev_success, krb5_audit_state *state);
+
+/* vtable declaration */
+typedef struct krb5_audit_vtable_st {
+    /* Mandatory: name of module. */
+    char                   *name;
+    krb5_audit_open_fn      open;
+    krb5_audit_close_fn     close;
+    krb5_audit_kdc_start_fn kdc_start;
+    krb5_audit_kdc_stop_fn  kdc_stop;
+    krb5_audit_as_req_fn    as_req;
+    krb5_audit_tgs_req_fn   tgs_req;
+    krb5_audit_s4u2self_fn  tgs_s4u2self;
+    krb5_audit_s4u2proxy_fn tgs_s4u2proxy;
+    krb5_audit_u2u_fn       tgs_u2u;
+} *krb5_audit_vtable;
+
+#endif /* KRB5_AU_PLUGIN_H_INCLUDED */