1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 /* 3 * Copyright (C) 2017 by the Massachusetts Institute of Technology. 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 10 * * Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 13 * * Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * 18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 21 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 22 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 23 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 25 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 27 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 29 * OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 /* 33 * Declarations for kadm5_auth plugin module implementors. 34 * 35 * The kadm5_auth pluggable interface currently has only one supported major 36 * version, which is 1. Major version 1 has a current minor version number of 37 * 1. 38 * 39 * kadm5_auth plugin modules should define a function named 40 * kadm5_auth_<modulename>_initvt, matching the signature: 41 * 42 * krb5_error_code 43 * kadm5_auth_modname_initvt(krb5_context context, int maj_ver, int min_ver, 44 * krb5_plugin_vtable vtable); 45 * 46 * The initvt function should: 47 * 48 * - Check that the supplied maj_ver number is supported by the module, or 49 * return KRB5_PLUGIN_VER_NOTSUPP if it is not. 50 * 51 * - Cast the vtable pointer as appropriate for maj_ver: 52 * maj_ver == 1: Cast to krb5_kadm5_auth_vtable 53 * 54 * - Initialize the methods of the vtable, stopping as appropriate for the 55 * supplied min_ver. Optional methods may be left uninitialized. 56 * 57 * Memory for the vtable is allocated by the caller, not by the module. 58 */ 59 60 #ifndef KRB5_KADM5_AUTH_PLUGIN_H 61 #define KRB5_KADM5_AUTH_PLUGIN_H 62 63 #include <krb5/krb5.h> 64 #include <krb5/plugin.h> 65 66 /* An abstract type for kadm5_auth module data. */ 67 typedef struct kadm5_auth_moddata_st *kadm5_auth_moddata; 68 69 /* 70 * A module can optionally include <kadm5/admin.h> to inspect principal or 71 * policy records from requests that add or modify principals or policies. 72 * Note that fields of principal and policy structures are only valid if the 73 * corresponding bit is set in the accompanying mask parameter. 74 */ 75 struct _kadm5_principal_ent_t; 76 struct _kadm5_policy_ent_t; 77 78 /* 79 * A module can optionally generate restrictions when checking permissions for 80 * adding or modifying a principal entry. Restriction fields will only be 81 * honored if the corresponding mask bit is set. The operable mask bits are 82 * defined in <kadmin/admin.h> and are: 83 * 84 * - KADM5_ATTRIBUTES for require_attrs, forbid_attrs 85 * - KADM5_POLICY for policy 86 * - KADM5_POLICY_CLR to require that policy be unset 87 * - KADM5_PRINC_EXPIRE_TIME for princ_lifetime 88 * - KADM5_PW_EXPIRATION for pw_lifetime 89 * - KADM5_MAX_LIFE for max_life 90 * - KADM5_MAX_RLIFE for max_renewable_life 91 */ 92 struct kadm5_auth_restrictions { 93 long mask; 94 krb5_flags require_attrs; 95 krb5_flags forbid_attrs; 96 krb5_deltat princ_lifetime; 97 krb5_deltat pw_lifetime; 98 krb5_deltat max_life; 99 krb5_deltat max_renewable_life; 100 char *policy; 101 }; 102 103 /*** Method type declarations ***/ 104 105 /* 106 * Optional: Initialize module data. acl_file is the realm's configured ACL 107 * file, or NULL if none was configured. Return 0 on success, 108 * KRB5_PLUGIN_NO_HANDLE if the module is inoperable (due to configuration, for 109 * example), and any other error code to abort kadmind startup. Optionally set 110 * *data_out to a module data object to be passed to future calls. 111 */ 112 typedef krb5_error_code 113 (*kadm5_auth_init_fn)(krb5_context context, const char *acl_file, 114 kadm5_auth_moddata *data_out); 115 116 /* Optional: Release resources used by module data. */ 117 typedef void 118 (*kadm5_auth_fini_fn)(krb5_context context, kadm5_auth_moddata data); 119 120 /* 121 * Each check method below should return 0 to explicitly authorize the request, 122 * KRB5_PLUGIN_NO_HANDLE to neither authorize nor deny the request, and any 123 * other error code (such as EPERM) to explicitly deny the request. If a check 124 * method is not defined, the module will neither authorize nor deny the 125 * request. A request succeeds if at least one kadm5_auth module explicitly 126 * authorizes the request and none of the modules explicitly deny it. 127 */ 128 129 /* Optional: authorize an add-principal operation, and optionally generate 130 * restrictions. */ 131 typedef krb5_error_code 132 (*kadm5_auth_addprinc_fn)(krb5_context context, kadm5_auth_moddata data, 133 krb5_const_principal client, 134 krb5_const_principal target, 135 const struct _kadm5_principal_ent_t *ent, long mask, 136 struct kadm5_auth_restrictions **rs_out); 137 138 /* Optional: authorize a modify-principal operation, and optionally generate 139 * restrictions. */ 140 typedef krb5_error_code 141 (*kadm5_auth_modprinc_fn)(krb5_context context, kadm5_auth_moddata data, 142 krb5_const_principal client, 143 krb5_const_principal target, 144 const struct _kadm5_principal_ent_t *ent, long mask, 145 struct kadm5_auth_restrictions **rs_out); 146 147 /* Optional: authorize a set-string operation. */ 148 typedef krb5_error_code 149 (*kadm5_auth_setstr_fn)(krb5_context context, kadm5_auth_moddata data, 150 krb5_const_principal client, 151 krb5_const_principal target, 152 const char *key, const char *value); 153 154 /* Optional: authorize a change-password operation. */ 155 typedef krb5_error_code 156 (*kadm5_auth_cpw_fn)(krb5_context context, kadm5_auth_moddata data, 157 krb5_const_principal client, krb5_const_principal target); 158 159 /* Optional: authorize a randomize-keys operation. */ 160 typedef krb5_error_code 161 (*kadm5_auth_chrand_fn)(krb5_context context, kadm5_auth_moddata data, 162 krb5_const_principal client, 163 krb5_const_principal target); 164 165 /* Optional: authorize a set-key operation. */ 166 typedef krb5_error_code 167 (*kadm5_auth_setkey_fn)(krb5_context context, kadm5_auth_moddata data, 168 krb5_const_principal client, 169 krb5_const_principal target); 170 171 /* Optional: authorize a purgekeys operation. */ 172 typedef krb5_error_code 173 (*kadm5_auth_purgekeys_fn)(krb5_context context, kadm5_auth_moddata data, 174 krb5_const_principal client, 175 krb5_const_principal target); 176 177 /* Optional: authorize a delete-principal operation. */ 178 typedef krb5_error_code 179 (*kadm5_auth_delprinc_fn)(krb5_context context, kadm5_auth_moddata data, 180 krb5_const_principal client, 181 krb5_const_principal target); 182 183 /* Optional: authorize a rename-principal operation. */ 184 typedef krb5_error_code 185 (*kadm5_auth_renprinc_fn)(krb5_context context, kadm5_auth_moddata data, 186 krb5_const_principal client, 187 krb5_const_principal src, 188 krb5_const_principal dest); 189 190 /* Optional: authorize a get-principal operation. */ 191 typedef krb5_error_code 192 (*kadm5_auth_getprinc_fn)(krb5_context context, kadm5_auth_moddata data, 193 krb5_const_principal client, 194 krb5_const_principal target); 195 196 /* Optional: authorize a get-strings operation. */ 197 typedef krb5_error_code 198 (*kadm5_auth_getstrs_fn)(krb5_context context, kadm5_auth_moddata data, 199 krb5_const_principal client, 200 krb5_const_principal target); 201 202 /* Optional: authorize an extract-keys operation. */ 203 typedef krb5_error_code 204 (*kadm5_auth_extract_fn)(krb5_context context, kadm5_auth_moddata data, 205 krb5_const_principal client, 206 krb5_const_principal target); 207 208 /* Optional: authorize a list-principals operation. */ 209 typedef krb5_error_code 210 (*kadm5_auth_listprincs_fn)(krb5_context context, kadm5_auth_moddata data, 211 krb5_const_principal client); 212 213 /* Optional: authorize an add-policy operation. */ 214 typedef krb5_error_code 215 (*kadm5_auth_addpol_fn)(krb5_context context, kadm5_auth_moddata data, 216 krb5_const_principal client, const char *policy, 217 const struct _kadm5_policy_ent_t *ent, long mask); 218 219 /* Optional: authorize a modify-policy operation. */ 220 typedef krb5_error_code 221 (*kadm5_auth_modpol_fn)(krb5_context context, kadm5_auth_moddata data, 222 krb5_const_principal client, const char *policy, 223 const struct _kadm5_policy_ent_t *ent, long mask); 224 225 /* Optional: authorize a delete-policy operation. */ 226 typedef krb5_error_code 227 (*kadm5_auth_delpol_fn)(krb5_context context, kadm5_auth_moddata data, 228 krb5_const_principal client, const char *policy); 229 230 /* Optional: authorize a get-policy operation. client_policy is the client 231 * principal's policy name, or NULL if it does not have one. */ 232 typedef krb5_error_code 233 (*kadm5_auth_getpol_fn)(krb5_context context, kadm5_auth_moddata data, 234 krb5_const_principal client, const char *policy, 235 const char *client_policy); 236 237 /* Optional: authorize a list-policies operation. */ 238 typedef krb5_error_code 239 (*kadm5_auth_listpols_fn)(krb5_context context, kadm5_auth_moddata data, 240 krb5_const_principal client); 241 242 /* Optional: authorize an iprop operation. */ 243 typedef krb5_error_code 244 (*kadm5_auth_iprop_fn)(krb5_context context, kadm5_auth_moddata data, 245 krb5_const_principal client); 246 247 /* 248 * Optional: receive a notification that the most recent authorized operation 249 * has ended. If a kadm5_auth module is also a KDB module, it can assume that 250 * all KDB methods invoked between a kadm5_auth authorization method invocation 251 * and a kadm5_auth end invocation are performed as part of the authorized 252 * operation. 253 * 254 * The end method may be invoked without a preceding authorization method in 255 * some cases; the module must be prepared to ignore such calls. 256 */ 257 typedef void 258 (*kadm5_auth_end_fn)(krb5_context context, kadm5_auth_moddata data); 259 260 /* 261 * Optional: free a restrictions object. This method does not need to be 262 * defined if the module does not generate restrictions objects, or if it 263 * returns aliases to restrictions objects contained from within the module 264 * data. 265 */ 266 typedef void 267 (*kadm5_auth_free_restrictions_fn)(krb5_context context, 268 kadm5_auth_moddata data, 269 struct kadm5_auth_restrictions *rs); 270 271 /* kadm5_auth vtable for major version 1. */ 272 typedef struct kadm5_auth_vtable_st { 273 const char *name; /* Mandatory: name of module. */ 274 kadm5_auth_init_fn init; 275 kadm5_auth_fini_fn fini; 276 277 kadm5_auth_addprinc_fn addprinc; 278 kadm5_auth_modprinc_fn modprinc; 279 kadm5_auth_setstr_fn setstr; 280 kadm5_auth_cpw_fn cpw; 281 kadm5_auth_chrand_fn chrand; 282 kadm5_auth_setkey_fn setkey; 283 kadm5_auth_purgekeys_fn purgekeys; 284 kadm5_auth_delprinc_fn delprinc; 285 kadm5_auth_renprinc_fn renprinc; 286 287 kadm5_auth_getprinc_fn getprinc; 288 kadm5_auth_getstrs_fn getstrs; 289 kadm5_auth_extract_fn extract; 290 kadm5_auth_listprincs_fn listprincs; 291 292 kadm5_auth_addpol_fn addpol; 293 kadm5_auth_modpol_fn modpol; 294 kadm5_auth_delpol_fn delpol; 295 kadm5_auth_getpol_fn getpol; 296 kadm5_auth_listpols_fn listpols; 297 298 kadm5_auth_iprop_fn iprop; 299 300 kadm5_auth_end_fn end; 301 302 kadm5_auth_free_restrictions_fn free_restrictions; 303 /* Minor version 1 ends here. */ 304 } *kadm5_auth_vtable; 305 306 #endif /* KRB5_KADM5_AUTH_PLUGIN_H */ 307