lib/kadm5/kadm5-hook.h

   1 /*
   2  * Copyright 2010
   3  *     The Board of Trustees of the Leland Stanford Junior University
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * 3. Neither the name of the Institute nor the names of its contributors
  17  *    may be used to endorse or promote products derived from this software
  18  *    without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30  * SUCH DAMAGE.
  31  */
  32
  33 #ifndef KADM5_HOOK_H
  34 #define KADM5_HOOK_H 1
  35
  36 #define KADM5_HOOK_VERSION_V1 1
  37
  38 #include <heimbase-svc.h>
  39
  40 /*
  41  * Each hook is called before the operation using KADM5_STAGE_PRECOMMIT and
  42  * then after the operation using KADM5_STAGE_POSTCOMMIT. If the hook returns
  43  * failure during precommit, the operation is aborted without changes to the
  44  * database. All post-commit hook are invoked if the operation was attempted.
  45  *
  46  * Note that unlike libkrb5 plugins, returning success does not prevent other
  47  * plugins being called (i.e. it is equivalent to KRB5_PLUGIN_NO_HANDLE).
  48  */
  49 enum kadm5_hook_stage {
  50     KADM5_HOOK_STAGE_PRECOMMIT,
  51     KADM5_HOOK_STAGE_POSTCOMMIT
  52 };
  53
  54 #define KADM5_HOOK_FLAG_KEEPOLD     0x1 /* keep old password */
  55 #define KADM5_HOOK_FLAG_CONDITIONAL 0x2 /* only change password if different */
  56
  57 typedef struct kadm5_hook_ftable {
  58     HEIM_PLUGIN_FTABLE_COMMON_ELEMENTS(krb5_context);
  59
  60     const char *name;
  61     const char *vendor;
  62
  63     /*
  64      * Hook functions; NULL functions are ignored. code is only valid on
  65      * post-commit hooks and represents the result of the commit. Post-
  66      * commit hooks are not called if a pre-commit hook aborted the call.
  67      */
  68     krb5_error_code (KRB5_CALLCONV *chpass)(krb5_context context,
  69                                             void *data,
  70                                             enum kadm5_hook_stage stage,
  71                                             krb5_error_code code,
  72                                             krb5_const_principal princ,
  73                                             uint32_t flags,
  74                                             size_t n_ks_tuple,
  75                                             krb5_key_salt_tuple *ks_tuple,
  76                                             const char *password);
  77
  78     krb5_error_code (KRB5_CALLCONV *chpass_with_key)(krb5_context context,
  79                                                      void *data,
  80                                                      enum kadm5_hook_stage stage,
  81                                                      krb5_error_code code,
  82                                                      krb5_const_principal princ,
  83                                                      uint32_t flags,
  84                                                      size_t n_key_data,
  85                                                      krb5_key_data *key_data);
  86
  87     krb5_error_code (KRB5_CALLCONV *create)(krb5_context context,
  88                                             void *data,
  89                                             enum kadm5_hook_stage stage,
  90                                             krb5_error_code code,
  91                                             kadm5_principal_ent_t ent,
  92                                             uint32_t mask,
  93                                             const char *password);
  94
  95     krb5_error_code (KRB5_CALLCONV *modify)(krb5_context context,
  96                                             void *data,
  97                                             enum kadm5_hook_stage stage,
  98                                             krb5_error_code code,
  99                                             kadm5_principal_ent_t ent,
 100                                             uint32_t mask);
 101
 102     krb5_error_code (KRB5_CALLCONV *delete)(krb5_context context,
 103                                             void *data,
 104                                             enum kadm5_hook_stage stage,
 105                                             krb5_error_code code,
 106                                             krb5_const_principal princ);
 107
 108     krb5_error_code (KRB5_CALLCONV *randkey)(krb5_context context,
 109                                              void *data,
 110                                              enum kadm5_hook_stage stage,
 111                                              krb5_error_code code,
 112                                              krb5_const_principal princ);
 113
 114     krb5_error_code (KRB5_CALLCONV *rename)(krb5_context context,
 115                                             void *data,
 116                                             enum kadm5_hook_stage stage,
 117                                             krb5_error_code code,
 118                                             krb5_const_principal source,
 119                                             krb5_const_principal target);
 120
 121     krb5_error_code (KRB5_CALLCONV *set_keys)(krb5_context context,
 122                                               void *data,
 123                                               enum kadm5_hook_stage stage,
 124                                               krb5_error_code code,
 125                                               krb5_const_principal princ,
 126                                               uint32_t flags,
 127                                               size_t n_ks_tuple,
 128                                               krb5_key_salt_tuple *ks_tuple,
 129                                               size_t n_keys,
 130                                               krb5_keyblock *keyblocks);
 131
 132     krb5_error_code (KRB5_CALLCONV *prune)(krb5_context context,
 133                                            void *data,
 134                                            enum kadm5_hook_stage stage,
 135                                            krb5_error_code code,
 136                                            krb5_const_principal princ,
 137                                            int kvno);
 138
 139 } kadm5_hook_ftable;
 140
 141 /*
 142  * libkadm5srv expects a symbol named kadm5_hook_plugin_load that must be a
 143  * function of type kadm5_hook_plugin_load_t.
 144  */
 145 typedef krb5_error_code
 146 (KRB5_CALLCONV *kadm5_hook_plugin_load_t)(krb5_context context,
 147                                           krb5_get_instance_func_t *func,
 148                                           size_t *n_hooks,
 149                                           const kadm5_hook_ftable *const **hooks);
 150
 151 #endif /* !KADM5_HOOK_H */