diff options
Diffstat (limited to 'src/include/krb5')
| -rw-r--r-- | src/include/krb5/audit_plugin.h | 270 |
1 files changed, 270 insertions, 0 deletions
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 */ |