/* -*- 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 */