Adding upstream version 2:4.17.12+dfsg.upstream/2%4.17.12+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 359 insertions, 0 deletions

diff --git a/third_party/heimdal/lib/krb5/krb5-plugin.7 b/third_party/heimdal/lib/krb5/krb5-plugin.7
new file mode 100644
index 0000000..0b1e729
--- /dev/null
+++ b/third_party/heimdal/lib/krb5/krb5-plugin.7
@@ -0,0 +1,359 @@
+.\" Copyright (c) 1999 - 2005 Kungliga Tekniska Högskolan
+.\" (Royal Institute of Technology, Stockholm, Sweden).
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. 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.
+.\"
+.\" 3. Neither the name of the Institute nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE 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 INSTITUTE 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.
+.\"
+.\" $Id$
+.\"
+.Dd December  21, 2011
+.Dt KRB5-PLUGIN 7
+.Os HEIMDAL
+.Sh NAME
+.Nm krb5-plugin
+.Nd plugin interface for Heimdal
+.Sh SYNOPSIS
+.In krb5.h
+.In krb5/an2ln_plugin.h
+.In krb5/ccache_plugin.h
+.In krb5/db_plugin.h
+.In krb5/kuserok_plugin.h
+.In krb5/locate_plugin.h
+.In krb5/send_to_kdc_plugin.h
+.Sh DESCRIPTION
+Heimdal has a plugin interface.  Plugins may be statically linked into
+Heimdal and registered via the
+.Xr krb5_plugin_register 3
+function, or they may be dynamically loaded from shared objects present
+in the Heimdal plugins directories.
+.Pp
+Plugins consist of a C struct whose struct name is given in the
+associated header file, such as, for example,
+.Va krb5plugin_kuserok_ftable
+and a pointer to which is either registered via
+.Xr krb5_plugin_register 3
+or via a plugin load function exported by a shared object.
+Plugin load functions should be named by concatenating the name defined in the
+associated header file with the string "plugin_load" (e.g.
+"krb5_plugin_kuserok_plugin_load" for the plugin for
+.Xr krb5_kuserok 3
+).
+The plugin load function must be of type
+.Va heim_plugin_load_ft
+which is:
+.Bd -literal -offset indent
+krb5_error_code HEIM_CALLCONV
+my_plugin_load(heim_pcontext context,
+               krb5_get_instance_func_t *get_instance,
+               size_t *num_plugins,
+               heim_plugin_common_ftable_cp **plugins);
+
+.Ed
+where
+.Va HEIM_CALLCONV
+is
+.Va __stdcall
+on Windows.
+.Pp
+The plugin should set the get_instance output parameter to the a
+function that will return the instances of its library
+dependencies.  For example:
+.Bd -literal -offset indent
+static uintptr_t HEIM_LIB_CALL
+my_plugin_get_instance(const char *name)
+{
+    if (strcmp(name, "krb5") == 0)
+        return krb5_get_instance(name);
+    return 0;
+}
+.Ed
+.Pp
+The
+.Va get_instance
+function is used to check that dynamically-linked plugins are
+linked with the same Heimdal shared objects as the one loading
+and running the plugin.
+.Pp
+The output parameters
+.Va plugins
+and
+.Va n_plugins
+output an array of pointers to function tabls, and the number of
+those, respectively.
+.Pp
+The plugin structs for all plugin types always begin with the same three
+common fields:
+.Bl -enum -compact
+.It
+.Va minor_version
+, an int.  Plugin minor versions are defined in each plugin type's
+associated header file.
+.It
+.Va init
+, a pointer to a function with two arguments, a
+.Va heim_pcontext
+(which for krb5 plugins is actually a krb5_context),
+and a
+.Va void **
+, returning a heim_error_code.  This function will be called to
+initialize a plugin-specific context in the form of a
+.Va void *
+that will be output through the init function's second argument.
+.It
+.Va fini
+, a pointer to a function of one argument, a
+.Va void *
+, consisting of the plugin's context to be destroyed, and
+returning
+.Va void.
+.El
+.Pp
+Each plugin type may add fields to this struct following the above
+three.  Plugins are typically invoked in no particular order until one
+succeeds or fails, or all return a special return value that indicates
+that the plugin was not applicable.  For krb5 plugins,
+.Va KRB5_PLUGIN_NO_HANDLE
+indicates that the plugin was not applicable.
+.Pp
+Heimdal plugin callers either invoke all plugins until one returns an
+error or all return
+.Va KRB5_PLUGIN_NO_HANDLE
+, or invoke all plugins until one returns a value other than
+.Va KRB5_PLUGIN_NO_HANDLE
+with the expectation that only one plugin would return success and all
+oters would return
+.Va KRB5_PLUGIN_NO_HANDLE.
+Thus Heimdal plugin invokation can be deterministic in spite of
+non-deterministic invocation order.
+.Pp
+There is a database plugin system intended for many of the uses of
+databases in Heimdal.  The plugin is expected to call
+.Xr heim_db_register 3
+from its
+.Va init
+entry point to register a DB type.  The DB plugin's
+.Va fini
+function must do nothing, and the plugin must not provide any other
+entry points.
+.Pp
+The krb5_kuserok plugin adds a single field to its struct: a pointer to
+a function that implements kuserok functionality with the following
+form:
+.Bd -literal -offset indent
+static krb5_error_code
+kuserok(void *plug_ctx, krb5_context context, const char *rule,
+        unsigned int flags, const char *k5login_dir,
+        const char *luser, krb5_const_principal principal,
+        krb5_boolean *result)
+.Ed
+.Pp
+The
+.Va luser
+,
+.Va principal
+and
+.Va result
+arguments are self-explanatory (see
+.Xr krb5_kuserok 3
+).  The
+.Va plug_ctx
+argument is the context output by the plugin's init function.  The
+.Va rule
+argument is a kuserok rule from the krb5.conf file; each plugin is invoked once
+for each rule until all plugins fail or one succeeds.  The
+.Va k5login_dir
+argument provides an alternative k5login file location, if not NULL.
+The
+.Va flags
+argument indicates whether the plugin may call
+.Xr krb5_aname_to_localname 3
+(KUSEROK_ANAME_TO_LNAME_OK), and whether k5login databases are expected to be
+authoritative (KUSEROK_K5LOGIN_IS_AUTHORITATIVE).
+.Pp
+The plugin for
+.Xr krb5_aname_to_localname 3
+is named "an2ln" and has a single extra field for the plugin struct:
+.Bd -literal -offset indent
+typedef krb5_error_code (*set_result_f)(void *, const char *);
+
+static krb5_error_code
+an2ln(void *plug_ctx, krb5_context context, const char *rule,
+      krb5_const_principal aname, set_result_f set_res_f, void *set_res_ctx)
+.Ed
+.Pp
+The arguments for the
+.Va an2ln
+plugin are similar to those of the kuserok plugin, but the result, being
+a string, is set by calling the
+.Va set_res_f
+function argument with the
+.Va set_res_ctx
+and result string as arguments.  The
+.Va set_res_f
+function will make a copy of the string.
+.Sh FILES
+.Bl -tag -compact
+.It Pa libdir/plugin/krb5/*
+Shared objects containing plugins for Heimdal.
+.El
+.Sh EXAMPLES
+.Pp
+An example an2ln plugin that maps principals to a constant "nouser"
+follows:
+.Pp
+.Bd -literal -offset indent
+#include <krb5/an2ln_plugin.h>
+
+/* Note that `context' here is actually a krb5_context value */
+static krb5_error_code KRB5_CALLCONV
+nouser_plug_init(heim_pcontext context, void **ctx)
+{
+    *ctx = NULL;
+    return 0;
+}
+
+static void KRB5_CALLCONV nouser_plug_fini(void *ctx) { }
+
+static krb5_error_code KRB5_CALLCONV
+nouser_plug_an2ln(void *plug_ctx, krb5_context context,
+                  const char *rule,
+                  krb5_const_principal aname,
+                  set_result_f set_res_f, void *set_res_ctx)
+{   
+    krb5_error_code ret;
+
+    if (strcmp(rule, "NOUSER") != 0)
+	return KRB5_PLUGIN_NO_HANDLE;
+
+    ret = set_res_f(set_res_ctx, "nouser");
+
+    return ret;
+}
+
+krb5plugin_an2ln_ftable an2ln = {
+    KRB5_PLUGIN_AN2LN_VERSION_0,
+    nouser_plug_init,
+    nouser_plug_fini,
+    nouser_plug_an2ln,
+};
+
+static const krb5plugin_an2ln_ftable *const plugins[] = {
+    &an2ln
+};
+
+static uintptr_t
+an2ln_get_instance(const char *libname)
+{
+    if (strcmp(libname, "krb5") == 0)
+	return krb5_get_instance(libname);
+
+    return 0;
+}
+
+/* Note that `context' here is actually a krb5_context value */
+krb5_error_code
+an2ln_plugin_load(heim_pcontext context,
+                 krb5_get_instance_func_t *get_instance,
+                 size_t *num_plugins,
+                 const krb5plugin_an2ln_ftable * const **pplugins)
+{
+    *get_instance = an2ln_get_instance;
+    *num_plugins = sizeof(plugins) / sizeof(plugins[0]);
+    *pplugins = plugins;
+    return 0;
+}
+.Ed
+.Pp
+An example kuserok plugin that rejects all requests follows.  (Note that
+there exists a built-in plugin with this functionality; see
+.Xr krb5_kuserok 3
+).
+.Pp
+.Bd -literal -offset indent
+#include <krb5/kuserok_plugin.h>
+
+static krb5_error_code KRB5_CALLCONV
+reject_plug_init(heim_context context, void **ctx)
+{
+    *ctx = NULL;
+    return 0;
+}
+
+static void KRB5_CALLCONV reject_plug_fini(void *ctx) { }
+
+static krb5_error_code KRB5_CALLCONV
+reject_plug_kuserok(void *plug_ctx, krb5_context context, const char *rule,
+                    unsigned int flags, const char *k5login_dir,
+                    const char *luser, krb5_const_principal principal,
+                    krb5_boolean *result)
+{
+    if (strcmp(rule, "REJECT") != 0)
+        return KRB5_PLUGIN_NO_HANDLE;
+
+    *result = FALSE;
+    return 0;
+}
+
+static krb5plugin_kuserok_ftable kuserok = {
+    KRB5_PLUGIN_KUSEROK_VERSION_0,
+    reject_plug_init,
+    reject_plug_fini,
+    reject_plug_kuserok,
+};
+
+static const krb5plugin_kuserok_ftable *const plugins[] = {
+    &kuserok
+};
+
+static uintptr_t
+kuserok_get_instance(const char *libname)
+{
+    if (strcmp(libname, "krb5") == 0)
+	return krb5_get_instance(libname);
+
+    return 0;
+}
+
+krb5_error_code
+krb5_plugin_kuserok_plugin_load(
+    heim_context context,
+    krb5_get_instance_func_t *get_instance,
+    size_t *num_plugins,
+    const krb5plugin_kuserok_ftable * const **pplugins)
+{
+    *krb5_instance = kuserok_get_instance;
+    *num_plugins = sizeof(plugins) / sizeof(plugins[0]);
+    *pplugins = plugins;
+    return 0;
+}
+
+.Ed
+.Sh SEE ALSO
+.Xr krb5_plugin_register 3
+.Xr krb5_kuserok 3
+.Xr krb5_aname_to_localname 3