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