diff options
Diffstat (limited to 'src/include/krb5/kadm5_auth_plugin.h')
| -rw-r--r-- | src/include/krb5/kadm5_auth_plugin.h | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/src/include/krb5/kadm5_auth_plugin.h b/src/include/krb5/kadm5_auth_plugin.h new file mode 100644 index 000000000000..d514e99beb93 --- /dev/null +++ b/src/include/krb5/kadm5_auth_plugin.h @@ -0,0 +1,306 @@ +/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ +/* + * Copyright (C) 2017 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. + */ + +/* + * Declarations for kadm5_auth plugin module implementors. + * + * The kadm5_auth pluggable interface currently has only one supported major + * version, which is 1. Major version 1 has a current minor version number of + * 1. + * + * kadm5_auth plugin modules should define a function named + * kadm5_auth_<modulename>_initvt, matching the signature: + * + * krb5_error_code + * kadm5_auth_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 maj_ver: + * maj_ver == 1: Cast to krb5_kadm5_auth_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_KADM5_AUTH_PLUGIN_H +#define KRB5_KADM5_AUTH_PLUGIN_H + +#include <krb5/krb5.h> +#include <krb5/plugin.h> + +/* An abstract type for kadm5_auth module data. */ +typedef struct kadm5_auth_moddata_st *kadm5_auth_moddata; + +/* + * A module can optionally include <kadm5/admin.h> to inspect principal or + * policy records from requests that add or modify principals or policies. + * Note that fields of principal and policy structures are only valid if the + * corresponding bit is set in the accompanying mask parameter. + */ +struct _kadm5_principal_ent_t; +struct _kadm5_policy_ent_t; + +/* + * A module can optionally generate restrictions when checking permissions for + * adding or modifying a principal entry. Restriction fields will only be + * honored if the corresponding mask bit is set. The operable mask bits are + * defined in <kadmin/admin.h> and are: + * + * - KADM5_ATTRIBUTES for require_attrs, forbid_attrs + * - KADM5_POLICY for policy + * - KADM5_POLICY_CLR to require that policy be unset + * - KADM5_PRINC_EXPIRE_TIME for princ_lifetime + * - KADM5_PW_EXPIRATION for pw_lifetime + * - KADM5_MAX_LIFE for max_life + * - KADM5_MAX_RLIFE for max_renewable_life + */ +struct kadm5_auth_restrictions { + long mask; + krb5_flags require_attrs; + krb5_flags forbid_attrs; + krb5_deltat princ_lifetime; + krb5_deltat pw_lifetime; + krb5_deltat max_life; + krb5_deltat max_renewable_life; + char *policy; +}; + +/*** Method type declarations ***/ + +/* + * Optional: Initialize module data. acl_file is the realm's configured ACL + * file, or NULL if none was configured. Return 0 on success, + * KRB5_PLUGIN_NO_HANDLE if the module is inoperable (due to configuration, for + * example), and any other error code to abort kadmind startup. Optionally set + * *data_out to a module data object to be passed to future calls. + */ +typedef krb5_error_code +(*kadm5_auth_init_fn)(krb5_context context, const char *acl_file, + kadm5_auth_moddata *data_out); + +/* Optional: Release resources used by module data. */ +typedef void +(*kadm5_auth_fini_fn)(krb5_context context, kadm5_auth_moddata data); + +/* + * Each check method below should return 0 to explicitly authorize the request, + * KRB5_PLUGIN_NO_HANDLE to neither authorize nor deny the request, and any + * other error code (such as EPERM) to explicitly deny the request. If a check + * method is not defined, the module will neither authorize nor deny the + * request. A request succeeds if at least one kadm5_auth module explicitly + * authorizes the request and none of the modules explicitly deny it. + */ + +/* Optional: authorize an add-principal operation, and optionally generate + * restrictions. */ +typedef krb5_error_code +(*kadm5_auth_addprinc_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target, + const struct _kadm5_principal_ent_t *ent, long mask, + struct kadm5_auth_restrictions **rs_out); + +/* Optional: authorize a modify-principal operation, and optionally generate + * restrictions. */ +typedef krb5_error_code +(*kadm5_auth_modprinc_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target, + const struct _kadm5_principal_ent_t *ent, long mask, + struct kadm5_auth_restrictions **rs_out); + +/* Optional: authorize a set-string operation. */ +typedef krb5_error_code +(*kadm5_auth_setstr_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target, + const char *key, const char *value); + +/* Optional: authorize a change-password operation. */ +typedef krb5_error_code +(*kadm5_auth_cpw_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, krb5_const_principal target); + +/* Optional: authorize a randomize-keys operation. */ +typedef krb5_error_code +(*kadm5_auth_chrand_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target); + +/* Optional: authorize a set-key operation. */ +typedef krb5_error_code +(*kadm5_auth_setkey_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target); + +/* Optional: authorize a purgekeys operation. */ +typedef krb5_error_code +(*kadm5_auth_purgekeys_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target); + +/* Optional: authorize a delete-principal operation. */ +typedef krb5_error_code +(*kadm5_auth_delprinc_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target); + +/* Optional: authorize a rename-principal operation. */ +typedef krb5_error_code +(*kadm5_auth_renprinc_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal src, + krb5_const_principal dest); + +/* Optional: authorize a get-principal operation. */ +typedef krb5_error_code +(*kadm5_auth_getprinc_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target); + +/* Optional: authorize a get-strings operation. */ +typedef krb5_error_code +(*kadm5_auth_getstrs_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target); + +/* Optional: authorize an extract-keys operation. */ +typedef krb5_error_code +(*kadm5_auth_extract_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, + krb5_const_principal target); + +/* Optional: authorize a list-principals operation. */ +typedef krb5_error_code +(*kadm5_auth_listprincs_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client); + +/* Optional: authorize an add-policy operation. */ +typedef krb5_error_code +(*kadm5_auth_addpol_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, const char *policy, + const struct _kadm5_policy_ent_t *ent, long mask); + +/* Optional: authorize a modify-policy operation. */ +typedef krb5_error_code +(*kadm5_auth_modpol_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, const char *policy, + const struct _kadm5_policy_ent_t *ent, long mask); + +/* Optional: authorize a delete-policy operation. */ +typedef krb5_error_code +(*kadm5_auth_delpol_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, const char *policy); + +/* Optional: authorize a get-policy operation. client_policy is the client + * principal's policy name, or NULL if it does not have one. */ +typedef krb5_error_code +(*kadm5_auth_getpol_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client, const char *policy, + const char *client_policy); + +/* Optional: authorize a list-policies operation. */ +typedef krb5_error_code +(*kadm5_auth_listpols_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client); + +/* Optional: authorize an iprop operation. */ +typedef krb5_error_code +(*kadm5_auth_iprop_fn)(krb5_context context, kadm5_auth_moddata data, + krb5_const_principal client); + +/* + * Optional: receive a notification that the most recent authorized operation + * has ended. If a kadm5_auth module is also a KDB module, it can assume that + * all KDB methods invoked between a kadm5_auth authorization method invocation + * and a kadm5_auth end invocation are performed as part of the authorized + * operation. + * + * The end method may be invoked without a preceding authorization method in + * some cases; the module must be prepared to ignore such calls. + */ +typedef void +(*kadm5_auth_end_fn)(krb5_context context, kadm5_auth_moddata data); + +/* + * Optional: free a restrictions object. This method does not need to be + * defined if the module does not generate restrictions objects, or if it + * returns aliases to restrictions objects contained from within the module + * data. + */ +typedef void +(*kadm5_auth_free_restrictions_fn)(krb5_context context, + kadm5_auth_moddata data, + struct kadm5_auth_restrictions *rs); + +/* kadm5_auth vtable for major version 1. */ +typedef struct kadm5_auth_vtable_st { + const char *name; /* Mandatory: name of module. */ + kadm5_auth_init_fn init; + kadm5_auth_fini_fn fini; + + kadm5_auth_addprinc_fn addprinc; + kadm5_auth_modprinc_fn modprinc; + kadm5_auth_setstr_fn setstr; + kadm5_auth_cpw_fn cpw; + kadm5_auth_chrand_fn chrand; + kadm5_auth_setkey_fn setkey; + kadm5_auth_purgekeys_fn purgekeys; + kadm5_auth_delprinc_fn delprinc; + kadm5_auth_renprinc_fn renprinc; + + kadm5_auth_getprinc_fn getprinc; + kadm5_auth_getstrs_fn getstrs; + kadm5_auth_extract_fn extract; + kadm5_auth_listprincs_fn listprincs; + + kadm5_auth_addpol_fn addpol; + kadm5_auth_modpol_fn modpol; + kadm5_auth_delpol_fn delpol; + kadm5_auth_getpol_fn getpol; + kadm5_auth_listpols_fn listpols; + + kadm5_auth_iprop_fn iprop; + + kadm5_auth_end_fn end; + + kadm5_auth_free_restrictions_fn free_restrictions; + /* Minor version 1 ends here. */ +} *kadm5_auth_vtable; + +#endif /* KRB5_KADM5_AUTH_PLUGIN_H */ |