1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 /* include/krb5/audit_plugin.h - Audit plugin interface */ 3 /* 4 * Copyright (C) 2013 by the Massachusetts Institute of Technology. 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * * Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * 14 * * Redistributions in binary form must reproduce the above copyright 15 * notice, this list of conditions and the following disclaimer in 16 * the documentation and/or other materials provided with the 17 * distribution. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 24 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 26 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 28 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 30 * OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 /* 33 * NOTE: This is a private interface and may change incompatibly 34 * between versions. 35 */ 36 /* 37 * Declarations for KDC audit plugin module implementers. Audit modules allow 38 * the KDC to produce log output or audit records in any desired form. 39 * 40 * The audit interface has a single supported major version, which is 1. Major 41 * version 1 has a current minor version of 1. Audit modules should define a 42 * function named audit_<modulename>_initvt, matching the signature: 43 * 44 * krb5_error_code 45 * audit_modname_initvt(krb5_context context, int maj_ver, int min_ver, 46 * krb5_plugin_vtable vtable); 47 * 48 * The initvt function should: 49 * 50 * - Check that the supplied maj_ver number is supported by the module, or 51 * return KRB5_PLUGIN_VER_NOTSUPP if it is not. 52 * 53 * - Cast the vtable pointer as appropriate for the interface and maj_ver: 54 * maj_ver == 1: Cast to krb5_audit_vtable 55 * 56 * - Initialize the methods of the vtable, stopping as appropriate for the 57 * supplied min_ver. Optional methods may be left uninitialized. 58 * 59 * Memory for the vtable is allocated by the caller, not by the module. 60 */ 61 62 #ifndef KRB5_AU_PLUGIN_H_INCLUDED 63 #define KRB5_AU_PLUGIN_H_INCLUDED 64 #include <krb5/krb5.h> 65 66 /** KDC processing steps */ 67 #define AUTHN_REQ_CL 1 /**< Authenticate request and client */ 68 #define SRVC_PRINC 2 /**< Determine service principal */ 69 #define VALIDATE_POL 3 /**< Validate local and protocol policies */ 70 #define ISSUE_TKT 4 /**< Issue ticket */ 71 #define ENCR_REP 5 /**< Encrypt reply */ 72 73 /** Types of violations */ 74 #define PROT_CONSTRAINT 1 /**< Protocol constraint */ 75 #define LOCAL_POLICY 2 /**< Local policy violation */ 76 77 #define REQID_LEN 32 /* Size of the alphanumeric request ID */ 78 79 /** KDC audit state structure and declarations */ 80 typedef struct _krb5_audit_state { 81 krb5_kdc_req *request; 82 krb5_kdc_rep *reply; 83 krb5_address *cl_addr; /**< client address */ 84 krb5_ui_4 cl_port; /**< client port */ 85 int stage; /**< step in KDC processing */ 86 const char *status; /**< KDC status message */ 87 char *tkt_in_id; /**< primary (TGT) ticket ID */ 88 char *tkt_out_id; /**< derived (service or referral TGT) ticket ID */ 89 /** for s4u2proxy - evidence ticket ID; for u2u - second ticket ID */ 90 char *evid_tkt_id; 91 char req_id[REQID_LEN]; /**< request ID */ 92 krb5_data *cl_realm; /**< referrals: remote client's realm */ 93 krb5_principal s4u2self_user; /**< impersonated user */ 94 int violation; /**< local or protocol policy problem */ 95 } krb5_audit_state; 96 97 /** An abstract type for audit module data. */ 98 typedef struct krb5_audit_moddata_st *krb5_audit_moddata; 99 100 /* 101 * Mandatory: 102 * - krb5_audit_open_fn, 103 * Open connection to the audit system and initialize audit module data. If 104 * the underlying (OS or third party) audit facility fails to open, no 105 * auditable KDC events should be recorded. 106 */ 107 typedef krb5_error_code 108 (*krb5_audit_open_fn)(krb5_audit_moddata *auctx); 109 110 /* 111 * Mandatory: 112 * - krb5_audit_close_fn. 113 * Close connection to the underlying audit system. 114 */ 115 typedef krb5_error_code 116 (*krb5_audit_close_fn)(krb5_audit_moddata auctx); 117 118 /** 119 * Log KDC-start event. 120 * 121 * @param [in] auctx Audit context 122 * @param [in] ev_success Success/failure of the event being audited 123 * 124 * @note Optional. 125 * 126 * @retval 0 Success; otherwise - Kerberos error codes 127 */ 128 typedef krb5_error_code 129 (*krb5_audit_kdc_start_fn)(krb5_audit_moddata auctx, krb5_boolean ev_success); 130 131 /** 132 * Log KDC-stop event. 133 * 134 * @param [in] auctx Audit context 135 * @param [in] ev_success Success/failure of the event being audited 136 * 137 * @note Optional. 138 * 139 * @retval 0 Success; otherwise - Kerberos error codes 140 */ 141 typedef krb5_error_code 142 (*krb5_audit_kdc_stop_fn)(krb5_audit_moddata auctx, krb5_boolean ev_success); 143 144 /** 145 * Log AS exchange event. 146 * 147 * @param [in] auctx Audit context 148 * @param [in] ev_success Success/failure of the event being audited 149 * @param [in] state AS-request related auditable information 150 * 151 * The @a state provides the following data: 152 * - Full information about KDC request, assigned request ID, client address 153 * and port, and stage of the AS exchange 154 * - If available, the information about the encryption types of the short- and 155 * long-term keys, non-local client's referral realm, KDC status, the TGT 156 * and its ticket ID 157 * 158 * @note Optional. 159 * 160 * @retval 0 Success; otherwise - Kerberos error codes 161 */ 162 typedef krb5_error_code 163 (*krb5_audit_as_req_fn)(krb5_audit_moddata auctx, 164 krb5_boolean ev_success, krb5_audit_state *state); 165 166 /** 167 * Log TGS exchange event. 168 * 169 * @param [in] auctx Audit context 170 * @param [in] ev_success Success/failure of the event being audited 171 * @param [in] state TGS-request related auditable information 172 * 173 * The @a state provides the following data: 174 * - Full information about KDC request, assigned request ID, primary ticket 175 * ID, client address and port, and stage of the TGS exchange 176 * - If available, the information about the encryption types of the short- and 177 * long-term keys, KDC status, KDC reply, and the output ticket ID 178 * 179 * @note Optional. 180 * 181 * @retval 0 Success; otherwise - Kerberos error codes 182 */ 183 typedef krb5_error_code 184 (*krb5_audit_tgs_req_fn)(krb5_audit_moddata auctx, 185 krb5_boolean ev_success, krb5_audit_state *state); 186 187 /** 188 * Log S4U2SELF event. 189 * 190 * @param [in] auctx Audit context 191 * @param [in] ev_success Report on success or failure 192 * @param [in] state s4u2self related auditable information 193 * 194 * The @a state provides the following data: 195 * - Full information about KDC request, assigned request ID, client address 196 * and port, and stage of the TGS exchange 197 * - Requesting server's TGT ID, impersonated user principal name, and service 198 * "to self" ticket or referral TGT ID 199 * - If available, KDC status, local policy violation or S4U protocol 200 * constraints 201 * 202 * @note Optional. 203 * 204 * @retval 0 Success; otherwise - Kerberos error codes 205 */ 206 typedef krb5_error_code 207 (*krb5_audit_s4u2self_fn)(krb5_audit_moddata auctx, 208 krb5_boolean ev_success, krb5_audit_state *state); 209 210 /** 211 * Log S4U2PROXY event. 212 * 213 * @param [in] auctx Audit context 214 * @param [in] ev_success Report on success or failure 215 * @param [in] state s4u2proxy related auditable information 216 * 217 * The @a state provides the following data: 218 * - Full information about request, assigned request ID, client address and 219 * port, and stage of the TGS exchange 220 * - Requesting server's TGT ID, delegated user principal name, and evidence 221 * ticket ID 222 * - If available, KDC status, local policy violation or S4U protocol 223 * constraints 224 * 225 * @note Optional. 226 * 227 * @retval 0 Success; otherwise - Kerberos error codes 228 */ 229 typedef krb5_error_code 230 (*krb5_audit_s4u2proxy_fn)(krb5_audit_moddata auctx, 231 krb5_boolean ev_success, krb5_audit_state *state); 232 233 /** 234 * Log U2U event. 235 * 236 * @param [in] auctx Audit context 237 * @param [in] ev_success Report on success or failure 238 * @param [in] state user-to-user related auditable information 239 * 240 * The @a state provides the following data: 241 * - Full information about request, assigned request ID, client address and 242 * port, and stage of the TGS exchange, 243 * - Requestor's TGT ID, service ticket ID, and client's principal name in the 244 * second ticket 245 * - If available, KDC status 246 * 247 * @note Optional. 248 * 249 * @retval 0 Success; otherwise - Kerberos error codes 250 */ 251 typedef krb5_error_code 252 (*krb5_audit_u2u_fn)(krb5_audit_moddata auctx, 253 krb5_boolean ev_success, krb5_audit_state *state); 254 255 /* vtable declaration */ 256 typedef struct krb5_audit_vtable_st { 257 /* Mandatory: name of module. */ 258 const char *name; 259 krb5_audit_open_fn open; 260 krb5_audit_close_fn close; 261 krb5_audit_kdc_start_fn kdc_start; 262 krb5_audit_kdc_stop_fn kdc_stop; 263 krb5_audit_as_req_fn as_req; 264 krb5_audit_tgs_req_fn tgs_req; 265 krb5_audit_s4u2self_fn tgs_s4u2self; 266 krb5_audit_s4u2proxy_fn tgs_s4u2proxy; 267 krb5_audit_u2u_fn tgs_u2u; 268 } *krb5_audit_vtable; 269 270 #endif /* KRB5_AU_PLUGIN_H_INCLUDED */ 271