lib/krb5/krb5-plugin.7

   1 .\" Copyright (c) 1999 - 2005 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   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 .\" $Id$
  33 .\"
  34 .Dd December  21, 2011
  35 .Dt KRB5-PLUGIN 7
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5-plugin
  39 .Nd plugin interface for Heimdal
  40 .Sh SYNOPSIS
  41 .In krb5.h
  42 .In krb5/an2ln_plugin.h
  43 .In krb5/ccache_plugin.h
  44 .In krb5/db_plugin.h
  45 .In krb5/kuserok_plugin.h
  46 .In krb5/locate_plugin.h
  47 .In krb5/send_to_kdc_plugin.h
  48 .Sh DESCRIPTION
  49 Heimdal has a plugin interface.  Plugins may be statically linked into
  50 Heimdal and registered via the
  51 .Xr krb5_plugin_register 3
  52 function, or they may be dynamically loaded from shared objects present
  53 in the Heimdal plugins directories.
  54 .Pp
  55 Plugins consist of a C struct whose struct name is given in the
  56 associated header file, such as, for example,
  57 .Va krb5plugin_kuserok_ftable
  58 and a pointer to which is either registered via
  59 .Xr krb5_plugin_register 3
  60 or found in a shared object via a symbol lookup for the symbol name
  61 defined in the associated header file (e.g., "kuserok" for the
  62 plugin for
  63 .Xr krb5_kuserok 3
  64 ).
  65 .Pp
  66 The plugin structs for all plugin types always begin with the same three
  67 common fields:
  68 .Bl -enum -compact
  69 .It
  70 .Va minor_version
  71 , an int.  Plugin minor versions are defined in each plugin type's
  72 associated header file.
  73 .It
  74 .Va init
  75 , a pointer to a function with two arguments, a krb5_context and a
  76 void **, returning a krb5_error_code.  This function will be called to
  77 initialize a plugin-specific context in the form of a void * that will
  78 be output through the init function's second argument.
  79 .It
  80 .Va fini
  81 , a pointer to a function of one argument, a void *, consisting of the
  82 plugin's context to be destroyed, and returning void.
  83 .El
  84 .Pp
  85 Each plugin type must add zero or more fields to this struct following
  86 the above three.  Plugins are typically invoked in no particular order
  87 until one succeeds or fails, or all return a special return value such
  88 as KRB5_PLUGIN_NO_HANDLE to indicate that the plugin was not applicable.
  89 Most plugin types obtain deterministic plugin behavior in spite of the
  90 non-deterministic invocation order by, for example, invoking all plugins
  91 for each "rule" and passing the rule to each plugin with the expectation
  92 that just one plugin will match any given rule.
  93 .Pp
  94 There is a database plugin system intended for many of the uses of
  95 databases in Heimdal.  The plugin is expected to call
  96 .Xr heim_db_register 3
  97 from its
  98 .Va init
  99 entry point to register a DB type.  The DB plugin's
 100 .Va fini
 101 function must do nothing, and the plugin must not provide any other
 102 entry points.
 103 .Pp
 104 The krb5_kuserok plugin adds a single field to its struct: a pointer to
 105 a function that implements kuserok functionality with the following
 106 form:
 107 .Bd -literal -offset indent
 108 static krb5_error_code
 109 kuserok(void *plug_ctx, krb5_context context, const char *rule,
 110         unsigned int flags, const char *k5login_dir,
 111         const char *luser, krb5_const_principal principal,
 112         krb5_boolean *result)
 113 .Ed
 114 .Pp
 115 The
 116 .Va luser
 117 ,
 118 .Va principal
 119 and
 120 .Va result
 121 arguments are self-explanatory (see
 122 .Xr krb5_kuserok 3
 123 ).  The
 124 .Va plug_ctx
 125 argument is the context output by the plugin's init function.  The
 126 .Va rule
 127 argument is a kuserok rule from the krb5.conf file; each plugin is invoked once
 128 for each rule until all plugins fail or one succeeds.  The
 129 .Va k5login_dir
 130 argument provides an alternative k5login file location, if not NULL.
 131 The
 132 .Va flags
 133 argument indicates whether the plugin may call
 134 .Xr krb5_aname_to_localname 3
 135 (KUSEROK_ANAME_TO_LNAME_OK), and whether k5login databases are expected to be
 136 authoritative (KUSEROK_K5LOGIN_IS_AUTHORITATIVE).
 137 .Pp
 138 The plugin for
 139 .Xr krb5_aname_to_localname 3
 140 is named "an2ln" and has a single extra field for the plugin struct:
 141 .Bd -literal -offset indent
 142 typedef krb5_error_code (*set_result_f)(void *, const char *);
 143
 144 static krb5_error_code
 145 an2ln(void *plug_ctx, krb5_context context, const char *rule,
 146       krb5_const_principal aname, set_result_f set_res_f, void *set_res_ctx)
 147 .Ed
 148 .Pp
 149 The arguments for the
 150 .Va an2ln
 151 plugin are similar to those of the kuserok plugin, but the result, being
 152 a string, is set by calling the
 153 .Va set_res_f
 154 function argument with the
 155 .Va set_res_ctx
 156 and result string as arguments.  The
 157 .Va set_res_f
 158 function will make a copy of the string.
 159 .Sh FILES
 160 .Bl -tag -compact
 161 .It Pa libdir/plugin/krb5/*
 162 Shared objects containing plugins for Heimdal.
 163 .El
 164 .Sh EXAMPLES
 165 .Pp
 166 An example an2ln plugin that maps principals to a constant "nouser"
 167 follows:
 168 .Pp
 169 .Bd -literal -offset indent
 170 #include <krb5/an2ln_plugin.h>
 171
 172 static krb5_error_code
 173 nouser_plug_init(krb5_context context, void **ctx)
 174 {
 175     *ctx = NULL;
 176     return 0;
 177 }
 178
 179 static void nouser_plug_fini(void *ctx) { }
 180
 181 static krb5_error_code
 182 nouser_plug_an2ln(void *plug_ctx, krb5_context context,
 183                   const char *rule,
 184                   krb5_const_principal aname,
 185                   set_result_f set_res_f, void *set_res_ctx)
 186 {
 187     krb5_error_code ret;
 188
 189     if (strcmp(rule, "NOUSER") != 0)
 190         return KRB5_PLUGIN_NO_HANDLE;
 191
 192     ret = set_res_f(set_res_ctx, "nouser");
 193
 194     return ret;
 195 }
 196
 197 krb5plugin_an2ln_ftable an2ln = {
 198     KRB5_PLUGIN_AN2LN_VERSION_0,
 199     nouser_plug_init,
 200     nouser_plug_fini,
 201     nouser_plug_an2ln,
 202 };
 203 .Ed
 204 .Pp
 205 An example kuserok plugin that rejects all requests follows.  (Note that
 206 there exists a built-in plugin with this functionality; see
 207 .Xr krb5_kuserok 3
 208 ).
 209 .Pp
 210 .Bd -literal -offset indent
 211 #include <krb5/kuserok_plugin.h>
 212
 213 static krb5_error_code
 214 reject_plug_init(krb5_context context, void **ctx)
 215 {
 216     *ctx = NULL;
 217     return 0;
 218 }
 219
 220 static void reject_plug_fini(void *ctx) { }
 221
 222 static krb5_error_code
 223 reject_plug_kuserok(void *plug_ctx, krb5_context context, const char *rule,
 224                     unsigned int flags, const char *k5login_dir,
 225                     const char *luser, krb5_const_principal principal,
 226                     krb5_boolean *result)
 227 {
 228     if (strcmp(rule, "REJECT") != 0)
 229         return KRB5_PLUGIN_NO_HANDLE;
 230
 231     *result = FALSE;
 232     return 0;
 233 }
 234
 235 krb5plugin_kuserok_ftable kuserok = {
 236     KRB5_PLUGIN_KUSEROK_VERSION_0,
 237     reject_plug_init,
 238     reject_plug_fini,
 239     reject_plug_kuserok,
 240 };
 241 .Ed
 242 .Sh SEE ALSO
 243 .Xr krb5_plugin_register 3
 244 .Xr krb5_kuserok 3
 245 .Xr krb5_aname_to_localname 3