Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
KRB5-PLUGIN(7)		Miscellaneous Information Manual	KRB5-PLUGIN(7)

NAME
       krb5-plugin -- plugin interface for Heimdal

SYNOPSIS
       #include	<krb5.h>
       #include	<krb5/an2ln_plugin.h>
       #include	<krb5/ccache_plugin.h>
       #include	<krb5/db_plugin.h>
       #include	<krb5/kuserok_plugin.h>
       #include	<krb5/locate_plugin.h>
       #include	<krb5/send_to_kdc_plugin.h>

DESCRIPTION
       Heimdal	has a plugin interface.	 Plugins may be	statically linked into
       Heimdal and registered via  the	krb5_plugin_register(3)	 function,  or
       they may	be dynamically loaded from shared objects present in the Heim-
       dal plugins directories.

       Plugins consist of a C struct whose struct name is given	in the associ-
       ated header file, such as, for example, krb5plugin_kuserok_ftable and a
       pointer	to  which  is either registered	via krb5_plugin_register(3) or
       found in	a shared object	via a symbol lookup for	the  symbol  name  de-
       fined in	the associated header file (e.g., "kuserok" for	the plugin for
       krb5_kuserok(3) ).

       The  plugin  structs  for  all  plugin types always begin with the same
       three common fields:
       1.   minor_version , an int.  Plugin minor versions are defined in each
	    plugin type's associated header file.
       2.   init , a pointer to	a function with	two arguments, a  krb5_context
	    and	a void **, returning a krb5_error_code.	 This function will be
	    called  to	initialize  a plugin-specific context in the form of a
	    void * that	will be	output through the init	function's second  ar-
	    gument.
       3.   fini , a pointer to	a function of one argument, a void *, consist-
	    ing	of the plugin's	context	to be destroyed, and returning void.

       Each  plugin type must add zero or more 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 such
       as KRB5_PLUGIN_NO_HANDLE	to indicate that the plugin was	 not  applica-
       ble.   Most  plugin types obtain	deterministic plugin behavior in spite
       of the non-deterministic	invocation order by, for example, invoking all
       plugins for each	"rule" and passing the rule to each  plugin  with  the
       expectation that	just one plugin	will match any given rule.

       There  is  a  database  plugin  system intended for many	of the uses of
       databases   in	Heimdal.    The	  plugin   is	expected    to	  call
       heim_db_register(3)  from  its  init entry point	to register a DB type.
       The DB plugin's fini function must do nothing, and the plugin must  not
       provide any other entry points.

       The krb5_kuserok	plugin adds a single field to its struct: a pointer to
       a  function  that  implements  kuserok functionality with the following
       form:

	     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)

       The luser , principal and result	arguments  are	self-explanatory  (see
       krb5_kuserok(3)	).  The	plug_ctx argument is the context output	by the
       plugin's	init function.	The 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 k5login_dir argument provides	an al-
       ternative k5login file location,	if not NULL.  The flags	argument indi-
       cates  whether	the   plugin   may   call   krb5_aname_to_localname(3)
       (KUSEROK_ANAME_TO_LNAME_OK), and	whether	k5login	databases are expected
       to be authoritative (KUSEROK_K5LOGIN_IS_AUTHORITATIVE).

       The  plugin  for	 krb5_aname_to_localname(3) is named "an2ln" and has a
       single extra field for the plugin struct:

	     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)

       The arguments for the an2ln plugin are similar to those of the  kuserok
       plugin, but the result, being a string, is set by calling the set_res_f
       function	 argument with the set_res_ctx and result string as arguments.
       The set_res_f function will make	a copy of the string.

FILES
       libdir/plugin/krb5/*
	       Shared objects containing plugins for Heimdal.

EXAMPLES
       An example an2ln	plugin that maps principals  to	 a  constant  "nouser"
       follows:

	     #include <krb5/an2ln_plugin.h>

	     static krb5_error_code KRB5_CALLCONV
	     nouser_plug_init(krb5_context 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,
	     };

       An  example  kuserok  plugin  that rejects all requests follows.	 (Note
       that there exists  a  built-in  plugin  with  this  functionality;  see
       krb5_kuserok(3) ).

	     #include <krb5/kuserok_plugin.h>

	     static krb5_error_code KRB5_CALLCONV
	     reject_plug_init(krb5_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;
	     }

	     krb5plugin_kuserok_ftable kuserok = {
		 KRB5_PLUGIN_KUSEROK_VERSION_0,
		 reject_plug_init,
		 reject_plug_fini,
		 reject_plug_kuserok,
	     };

SEE ALSO
       krb5_plugin_register(3) krb5_kuserok(3) krb5_aname_to_localname(3)

HEIMDAL			       December	21, 2011		KRB5-PLUGIN(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=krb5-plugin&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>

home | help