"Fossies" - the Fresh Open Source Software Archive

Member "krb5-1.18/doc/pdf/plugindev.tex" (12 Feb 2020, 49369 Bytes) of package /linux/misc/krb5-1.18.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 %% Generated by Sphinx.
    2 \def\sphinxdocclass{report}
    3 \documentclass[letterpaper,10pt,english]{sphinxmanual}
    4 \ifdefined\pdfpxdimen
    5    \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
    6 \fi \sphinxpxdimen=.75bp\relax
    7 
    8 \usepackage[utf8]{inputenc}
    9 \ifdefined\DeclareUnicodeCharacter
   10  \ifdefined\DeclareUnicodeCharacterAsOptional
   11   \DeclareUnicodeCharacter{"00A0}{\nobreakspace}
   12   \DeclareUnicodeCharacter{"2500}{\sphinxunichar{2500}}
   13   \DeclareUnicodeCharacter{"2502}{\sphinxunichar{2502}}
   14   \DeclareUnicodeCharacter{"2514}{\sphinxunichar{2514}}
   15   \DeclareUnicodeCharacter{"251C}{\sphinxunichar{251C}}
   16   \DeclareUnicodeCharacter{"2572}{\textbackslash}
   17  \else
   18   \DeclareUnicodeCharacter{00A0}{\nobreakspace}
   19   \DeclareUnicodeCharacter{2500}{\sphinxunichar{2500}}
   20   \DeclareUnicodeCharacter{2502}{\sphinxunichar{2502}}
   21   \DeclareUnicodeCharacter{2514}{\sphinxunichar{2514}}
   22   \DeclareUnicodeCharacter{251C}{\sphinxunichar{251C}}
   23   \DeclareUnicodeCharacter{2572}{\textbackslash}
   24  \fi
   25 \fi
   26 \usepackage{cmap}
   27 \usepackage[T1]{fontenc}
   28 \usepackage{amsmath,amssymb,amstext}
   29 \usepackage{babel}
   30 \usepackage{times}
   31 \usepackage[Bjarne]{fncychap}
   32 \usepackage[dontkeepoldnames]{sphinx}
   33 
   34 \usepackage{geometry}
   35 
   36 % Include hyperref last.
   37 \usepackage{hyperref}
   38 % Fix anchor placement for figures with captions.
   39 \usepackage{hypcap}% it must be loaded after hyperref.
   40 % Set up styles of URL: it should be placed after hyperref.
   41 \urlstyle{same}
   42 
   43 \addto\captionsenglish{\renewcommand{\figurename}{Fig.}}
   44 \addto\captionsenglish{\renewcommand{\tablename}{Table}}
   45 \addto\captionsenglish{\renewcommand{\literalblockname}{Listing}}
   46 
   47 \addto\captionsenglish{\renewcommand{\literalblockcontinuedname}{continued from previous page}}
   48 \addto\captionsenglish{\renewcommand{\literalblockcontinuesname}{continues on next page}}
   49 
   50 \addto\extrasenglish{\def\pageautorefname{page}}
   51 
   52 \setcounter{tocdepth}{1}
   53 
   54 
   55 
   56 \title{Kerberos Plugin Module Developer Guide}
   57 \date{ }
   58 \release{1.18}
   59 \author{MIT}
   60 \newcommand{\sphinxlogo}{\vbox{}}
   61 \renewcommand{\releasename}{Release}
   62 \makeindex
   63 
   64 \begin{document}
   65 
   66 \maketitle
   67 \sphinxtableofcontents
   68 \phantomsection\label{\detokenize{plugindev/index::doc}}
   69 
   70 
   71 Kerberos plugin modules allow increased control over MIT krb5 library
   72 and server behavior.  This guide describes how to create dynamic
   73 plugin modules and the currently available pluggable interfaces.
   74 
   75 See \DUrole{xref,std,std-ref}{plugin\_config} for information on how to register dynamic
   76 plugin modules and how to enable and disable modules via
   77 \DUrole{xref,std,std-ref}{krb5.conf(5)}.
   78 
   79 
   80 \chapter{Contents}
   81 \label{\detokenize{plugindev/index:for-plugin-module-developers}}\label{\detokenize{plugindev/index:contents}}
   82 
   83 \section{General plugin concepts}
   84 \label{\detokenize{plugindev/general:general-plugin-concepts}}\label{\detokenize{plugindev/general::doc}}
   85 A krb5 dynamic plugin module is a Unix shared object or Windows DLL.
   86 Typically, the source code for a dynamic plugin module should live in
   87 its own project with a build system using \sphinxhref{https://www.gnu.org/software/automake/}{automake} and \sphinxhref{https://www.gnu.org/software/libtool/}{libtool}, or
   88 tools with similar functionality.
   89 
   90 A plugin module must define a specific symbol name, which depends on
   91 the pluggable interface and module name.  For most pluggable
   92 interfaces, the exported symbol is a function named
   93 \sphinxcode{INTERFACE\_MODULE\_initvt}, where \sphinxstyleemphasis{INTERFACE} is the name of the
   94 pluggable interface and \sphinxstyleemphasis{MODULE} is the name of the module.  For these
   95 interfaces, it is possible for one shared object or DLL to implement
   96 multiple plugin modules, either for the same pluggable interface or
   97 for different ones.  For example, a shared object could implement both
   98 KDC and client preauthentication mechanisms, by exporting functions
   99 named \sphinxcode{kdcpreauth\_mymech\_initvt} and \sphinxcode{clpreauth\_mymech\_initvt}.
  100 
  101 A plugin module implementation should include the header file
  102 \sphinxcode{\textless{}krb5/INTERFACE\_plugin.h\textgreater{}}, where \sphinxstyleemphasis{INTERFACE} is the name of the
  103 pluggable interface.  For instance, a ccselect plugin module
  104 implementation should use \sphinxcode{\#include \textless{}krb5/ccselect\_plugin.h\textgreater{}}.
  105 
  106 initvt functions have the following prototype:
  107 
  108 \fvset{hllines={, ,}}%
  109 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  110 \PYG{n}{krb5\PYGZus{}error\PYGZus{}code} \PYG{n}{interface\PYGZus{}modname\PYGZus{}initvt}\PYG{p}{(}\PYG{n}{krb5\PYGZus{}context} \PYG{n}{context}\PYG{p}{,}
  111                                          \PYG{n+nb}{int} \PYG{n}{maj\PYGZus{}ver}\PYG{p}{,} \PYG{n+nb}{int} \PYG{n}{min\PYGZus{}ver}\PYG{p}{,}
  112                                          \PYG{n}{krb5\PYGZus{}plugin\PYGZus{}vtable} \PYG{n}{vtable}\PYG{p}{)}\PYG{p}{;}
  113 \end{sphinxVerbatim}
  114 
  115 and should do the following:
  116 \begin{enumerate}
  117 \item {} 
  118 Check that the supplied maj\_ver argument is supported by the
  119 module.  If it is not supported, the function should return
  120 KRB5\_PLUGIN\_VER\_NOTSUPP.
  121 
  122 \item {} 
  123 Cast the supplied vtable pointer to the structure type
  124 corresponding to the major version, as documented in the pluggable
  125 interface header file.
  126 
  127 \item {} 
  128 Fill in the structure fields with pointers to method functions and
  129 static data, stopping at the field indicated by the supplied minor
  130 version.  Fields for unimplemented optional methods can be left
  131 alone; it is not necessary to initialize them to NULL.
  132 
  133 \end{enumerate}
  134 
  135 In most cases, the context argument will not be used.  The initvt
  136 function should not allocate memory; think of it as a glorified
  137 structure initializer.  Each pluggable interface defines methods for
  138 allocating and freeing module state if doing so is necessary for the
  139 interface.
  140 
  141 Pluggable interfaces typically include a \sphinxstylestrong{name} field in the vtable
  142 structure, which should be filled in with a pointer to a string
  143 literal containing the module name.
  144 
  145 Here is an example of what an initvt function might look like for a
  146 fictional pluggable interface named fences, for a module named
  147 “wicker”:
  148 
  149 \fvset{hllines={, ,}}%
  150 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  151 \PYG{n}{krb5\PYGZus{}error\PYGZus{}code}
  152 \PYG{n}{fences\PYGZus{}wicker\PYGZus{}initvt}\PYG{p}{(}\PYG{n}{krb5\PYGZus{}context} \PYG{n}{context}\PYG{p}{,} \PYG{n+nb}{int} \PYG{n}{maj\PYGZus{}ver}\PYG{p}{,}
  153                      \PYG{n+nb}{int} \PYG{n}{min\PYGZus{}ver}\PYG{p}{,} \PYG{n}{krb5\PYGZus{}plugin\PYGZus{}vtable} \PYG{n}{vtable}\PYG{p}{)}
  154 \PYG{p}{\PYGZob{}}
  155     \PYG{n}{krb5\PYGZus{}ccselect\PYGZus{}vtable} \PYG{n}{vt}\PYG{p}{;}
  156 
  157     \PYG{k}{if} \PYG{p}{(}\PYG{n}{maj\PYGZus{}ver} \PYG{o}{==} \PYG{l+m+mi}{1}\PYG{p}{)} \PYG{p}{\PYGZob{}}
  158         \PYG{n}{krb5\PYGZus{}fences\PYGZus{}vtable} \PYG{n}{vt} \PYG{o}{=} \PYG{p}{(}\PYG{n}{krb5\PYGZus{}fences\PYGZus{}vtable}\PYG{p}{)}\PYG{n}{vtable}\PYG{p}{;}
  159         \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{name} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{wicker}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;}
  160         \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{slats} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}slats}\PYG{p}{;}
  161         \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{braces} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}braces}\PYG{p}{;}
  162     \PYG{p}{\PYGZcb{}} \PYG{k}{else} \PYG{k}{if} \PYG{p}{(}\PYG{n}{maj\PYGZus{}ver} \PYG{o}{==} \PYG{l+m+mi}{2}\PYG{p}{)} \PYG{p}{\PYGZob{}}
  163         \PYG{n}{krb5\PYGZus{}fences\PYGZus{}vtable\PYGZus{}v2} \PYG{n}{vt} \PYG{o}{=} \PYG{p}{(}\PYG{n}{krb5\PYGZus{}fences\PYGZus{}vtable\PYGZus{}v2}\PYG{p}{)}\PYG{n}{vtable}\PYG{p}{;}
  164         \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{name} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{wicker}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;}
  165         \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{material} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}material}\PYG{p}{;}
  166         \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{construction} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}construction}\PYG{p}{;}
  167         \PYG{k}{if} \PYG{p}{(}\PYG{n}{min\PYGZus{}ver} \PYG{o}{\PYGZlt{}} \PYG{l+m+mi}{2}\PYG{p}{)}
  168             \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;}
  169         \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{footing} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}footing}\PYG{p}{;}
  170         \PYG{k}{if} \PYG{p}{(}\PYG{n}{min\PYGZus{}ver} \PYG{o}{\PYGZlt{}} \PYG{l+m+mi}{3}\PYG{p}{)}
  171             \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;}
  172         \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{appearance} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}appearance}\PYG{p}{;}
  173     \PYG{p}{\PYGZcb{}} \PYG{k}{else} \PYG{p}{\PYGZob{}}
  174         \PYG{k}{return} \PYG{n}{KRB5\PYGZus{}PLUGIN\PYGZus{}VER\PYGZus{}NOTSUPP}\PYG{p}{;}
  175     \PYG{p}{\PYGZcb{}}
  176     \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;}
  177 \PYG{p}{\PYGZcb{}}
  178 \end{sphinxVerbatim}
  179 
  180 
  181 \subsection{Logging from KDC and kadmind plugin modules}
  182 \label{\detokenize{plugindev/general:logging-from-kdc-and-kadmind-plugin-modules}}
  183 Plugin modules for the KDC or kadmind daemons can write to the
  184 configured logging outputs (see \DUrole{xref,std,std-ref}{logging}) by calling the
  185 \sphinxstylestrong{com\_err} function.  The first argument (\sphinxstyleemphasis{whoami}) is ignored.  If
  186 the second argument (\sphinxstyleemphasis{code}) is zero, the formatted message is logged
  187 at informational severity; otherwise, the formatted message is logged
  188 at error severity and includes the error message for the supplied
  189 code.  Here are examples:
  190 
  191 \fvset{hllines={, ,}}%
  192 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  193 \PYG{n}{com\PYGZus{}err}\PYG{p}{(}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{Client message contains }\PYG{l+s+si}{\PYGZpc{}d}\PYG{l+s+s2}{ items}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{nitems}\PYG{p}{)}\PYG{p}{;}
  194 \PYG{n}{com\PYGZus{}err}\PYG{p}{(}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{retval}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{while decoding client message}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
  195 \end{sphinxVerbatim}
  196 
  197 (The behavior described above is new in release 1.17.  In prior
  198 releases, the \sphinxstyleemphasis{whoami} argument is included for some logging output
  199 types, the logged message does not include the usual header for some
  200 output types, and the severity for syslog outputs is configured as
  201 part of the logging specification, defaulting to error severity.)
  202 
  203 
  204 \section{Client preauthentication interface (clpreauth)}
  205 \label{\detokenize{plugindev/clpreauth:client-preauthentication-interface-clpreauth}}\label{\detokenize{plugindev/clpreauth::doc}}
  206 During an initial ticket request, a KDC may ask a client to prove its
  207 knowledge of the password before issuing an encrypted ticket, or to
  208 use credentials other than a password.  This process is called
  209 preauthentication, and is described in \index{RFC!RFC 4120}\sphinxhref{https://tools.ietf.org/html/rfc4120.html}{\sphinxstylestrong{RFC 4120}} and \index{RFC!RFC 6113}\sphinxhref{https://tools.ietf.org/html/rfc6113.html}{\sphinxstylestrong{RFC 6113}}.
  210 The clpreauth interface allows the addition of client support for
  211 preauthentication mechanisms beyond those included in the core MIT
  212 krb5 code base.  For a detailed description of the clpreauth
  213 interface, see the header file \sphinxcode{\textless{}krb5/clpreauth\_plugin.h\textgreater{}} (or
  214 \sphinxcode{\textless{}krb5/preauth\_plugin.h\textgreater{}} before release 1.12).
  215 
  216 A clpreauth module is generally responsible for:
  217 \begin{itemize}
  218 \item {} 
  219 Supplying a list of preauth type numbers used by the module in the
  220 \sphinxstylestrong{pa\_type\_list} field of the vtable structure.
  221 
  222 \item {} 
  223 Indicating what kind of preauthentication mechanism it implements,
  224 with the \sphinxstylestrong{flags} method.  In the most common case, this method
  225 just returns \sphinxcode{PA\_REAL}, indicating that it implements a normal
  226 preauthentication type.
  227 
  228 \item {} 
  229 Examining the padata information included in a PREAUTH\_REQUIRED or
  230 MORE\_PREAUTH\_DATA\_REQUIRED error and producing padata values for the
  231 next AS request.  This is done with the \sphinxstylestrong{process} method.
  232 
  233 \item {} 
  234 Examining the padata information included in a successful ticket
  235 reply, possibly verifying the KDC identity and computing a reply
  236 key.  This is also done with the \sphinxstylestrong{process} method.
  237 
  238 \item {} 
  239 For preauthentication types which support it, recovering from errors
  240 by examining the error data from the KDC and producing a padata
  241 value for another AS request.  This is done with the \sphinxstylestrong{tryagain}
  242 method.
  243 
  244 \item {} 
  245 Receiving option information (supplied by \sphinxcode{kinit -X} or by an
  246 application), with the \sphinxstylestrong{gic\_opts} method.
  247 
  248 \end{itemize}
  249 
  250 A clpreauth module can create and destroy per-library-context and
  251 per-request state objects by implementing the \sphinxstylestrong{init}, \sphinxstylestrong{fini},
  252 \sphinxstylestrong{request\_init}, and \sphinxstylestrong{request\_fini} methods.  Per-context state
  253 objects have the type krb5\_clpreauth\_moddata, and per-request state
  254 objects have the type krb5\_clpreauth\_modreq.  These are abstract
  255 pointer types; a module should typically cast these to internal
  256 types for the state objects.
  257 
  258 The \sphinxstylestrong{process} and \sphinxstylestrong{tryagain} methods have access to a callback
  259 function and handle (called a “rock”) which can be used to get
  260 additional information about the current request, including the
  261 expected enctype of the AS reply, the FAST armor key, and the client
  262 long-term key (prompting for the user password if necessary).  A
  263 callback can also be used to replace the AS reply key if the
  264 preauthentication mechanism computes one.
  265 
  266 
  267 \section{KDC preauthentication interface (kdcpreauth)}
  268 \label{\detokenize{plugindev/kdcpreauth:kdc-preauthentication-interface-kdcpreauth}}\label{\detokenize{plugindev/kdcpreauth::doc}}
  269 The kdcpreauth interface allows the addition of KDC support for
  270 preauthentication mechanisms beyond those included in the core MIT
  271 krb5 code base.  For a detailed description of the kdcpreauth
  272 interface, see the header file \sphinxcode{\textless{}krb5/kdcpreauth\_plugin.h\textgreater{}} (or
  273 \sphinxcode{\textless{}krb5/preauth\_plugin.h\textgreater{}} before release 1.12).
  274 
  275 A kdcpreauth module is generally responsible for:
  276 \begin{itemize}
  277 \item {} 
  278 Supplying a list of preauth type numbers used by the module in the
  279 \sphinxstylestrong{pa\_type\_list} field of the vtable structure.
  280 
  281 \item {} 
  282 Indicating what kind of preauthentication mechanism it implements,
  283 with the \sphinxstylestrong{flags} method.  If the mechanism computes a new reply
  284 key, it must specify the \sphinxcode{PA\_REPLACES\_KEY} flag.  If the mechanism
  285 is generally only used with hardware tokens, the \sphinxcode{PA\_HARDWARE}
  286 flag allows the mechanism to work with principals which have the
  287 \sphinxstylestrong{requires\_hwauth} flag set.
  288 
  289 \item {} 
  290 Producing a padata value to be sent with a preauth\_required error,
  291 with the \sphinxstylestrong{edata} method.
  292 
  293 \item {} 
  294 Examining a padata value sent by a client and verifying that it
  295 proves knowledge of the appropriate client credential information.
  296 This is done with the \sphinxstylestrong{verify} method.
  297 
  298 \item {} 
  299 Producing a padata response value for the client, and possibly
  300 computing a reply key.  This is done with the \sphinxstylestrong{return\_padata}
  301 method.
  302 
  303 \end{itemize}
  304 
  305 A module can create and destroy per-KDC state objects by implementing
  306 the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  Per-KDC state objects have the
  307 type krb5\_kdcpreauth\_moddata, which is an abstract pointer types.  A
  308 module should typically cast this to an internal type for the state
  309 object.
  310 
  311 A module can create a per-request state object by returning one in the
  312 \sphinxstylestrong{verify} method, receiving it in the \sphinxstylestrong{return\_padata} method, and
  313 destroying it in the \sphinxstylestrong{free\_modreq} method.  Note that these state
  314 objects only apply to the processing of a single AS request packet,
  315 not to an entire authentication exchange (since an authentication
  316 exchange may remain unfinished by the client or may involve multiple
  317 different KDC hosts).  Per-request state objects have the type
  318 krb5\_kdcpreauth\_modreq, which is an abstract pointer type.
  319 
  320 The \sphinxstylestrong{edata}, \sphinxstylestrong{verify}, and \sphinxstylestrong{return\_padata} methods have access
  321 to a callback function and handle (called a “rock”) which can be used
  322 to get additional information about the current request, including the
  323 maximum allowable clock skew, the client’s long-term keys, the
  324 DER-encoded request body, the FAST armor key, string attributes on the
  325 client’s database entry, and the client’s database entry itself.  The
  326 \sphinxstylestrong{verify} method can assert one or more authentication indicators to
  327 be included in the issued ticket using the \sphinxcode{add\_auth\_indicator}
  328 callback (new in release 1.14).
  329 
  330 A module can generate state information to be included with the next
  331 client request using the \sphinxcode{set\_cookie} callback (new in release
  332 1.14).  On the next request, the module can read this state
  333 information using the \sphinxcode{get\_cookie} callback.  Cookie information is
  334 encrypted, timestamped, and transmitted to the client in a
  335 \sphinxcode{PA-FX-COOKIE} pa-data item.  Older clients may not support cookies
  336 and therefore may not transmit the cookie in the next request; in this
  337 case, \sphinxcode{get\_cookie} will not yield the saved information.
  338 
  339 If a module implements a mechanism which requires multiple round
  340 trips, its \sphinxstylestrong{verify} method can respond with the code
  341 \sphinxcode{KRB5KDC\_ERR\_MORE\_PREAUTH\_DATA\_REQUIRED} and a list of pa-data in
  342 the \sphinxstyleemphasis{e\_data} parameter to be processed by the client.
  343 
  344 The \sphinxstylestrong{edata} and \sphinxstylestrong{verify} methods can be implemented
  345 asynchronously.  Because of this, they do not return values directly
  346 to the caller, but must instead invoke responder functions with their
  347 results.  A synchronous implementation can invoke the responder
  348 function immediately.  An asynchronous implementation can use the
  349 callback to get an event context for use with the \sphinxhref{https://fedorahosted.org/libverto/}{libverto} API.
  350 
  351 
  352 \section{Credential cache selection interface (ccselect)}
  353 \label{\detokenize{plugindev/ccselect:credential-cache-selection-interface-ccselect}}\label{\detokenize{plugindev/ccselect::doc}}\label{\detokenize{plugindev/ccselect:ccselect-plugin}}
  354 The ccselect interface allows modules to control how credential caches
  355 are chosen when a GSSAPI client contacts a service.  For a detailed
  356 description of the ccselect interface, see the header file
  357 \sphinxcode{\textless{}krb5/ccselect\_plugin.h\textgreater{}}.
  358 
  359 The primary ccselect method is \sphinxstylestrong{choose}, which accepts a server
  360 principal as input and returns a ccache and/or principal name as
  361 output.  A module can use the krb5\_cccol APIs to iterate over the
  362 cache collection in order to find an appropriate ccache to use.
  363 
  364 A module can create and destroy per-library-context state objects by
  365 implementing the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  State objects have
  366 the type krb5\_ccselect\_moddata, which is an abstract pointer type.  A
  367 module should typically cast this to an internal type for the state
  368 object.
  369 
  370 A module can have one of two priorities, “authoritative” or
  371 “heuristic”.  Results from authoritative modules, if any are
  372 available, will take priority over results from heuristic modules.  A
  373 module communicates its priority as a result of the \sphinxstylestrong{init} method.
  374 
  375 
  376 \section{Password quality interface (pwqual)}
  377 \label{\detokenize{plugindev/pwqual::doc}}\label{\detokenize{plugindev/pwqual:password-quality-interface-pwqual}}\label{\detokenize{plugindev/pwqual:pwqual-plugin}}
  378 The pwqual interface allows modules to control what passwords are
  379 allowed when a user changes passwords.  For a detailed description of
  380 the pwqual interface, see the header file \sphinxcode{\textless{}krb5/pwqual\_plugin.h\textgreater{}}.
  381 
  382 The primary pwqual method is \sphinxstylestrong{check}, which receives a password as
  383 input and returns success (0) or a \sphinxcode{KADM5\_PASS\_Q\_} failure code
  384 depending on whether the password is allowed.  The \sphinxstylestrong{check} method
  385 also receives the principal name and the name of the principal’s
  386 password policy as input; although there is no stable interface for
  387 the module to obtain the fields of the password policy, it can define
  388 its own configuration or data store based on the policy name.
  389 
  390 A module can create and destroy per-process state objects by
  391 implementing the \sphinxstylestrong{open} and \sphinxstylestrong{close} methods.  State objects have
  392 the type krb5\_pwqual\_moddata, which is an abstract pointer type.  A
  393 module should typically cast this to an internal type for the state
  394 object.  The \sphinxstylestrong{open} method also receives the name of the realm’s
  395 dictionary file (as configured by the \sphinxstylestrong{dict\_file} variable in the
  396 \DUrole{xref,std,std-ref}{kdc\_realms} section of \DUrole{xref,std,std-ref}{kdc.conf(5)}) if it wishes to use
  397 it.
  398 
  399 
  400 \section{KADM5 hook interface (kadm5\_hook)}
  401 \label{\detokenize{plugindev/kadm5_hook:kadm5-hook-interface-kadm5-hook}}\label{\detokenize{plugindev/kadm5_hook::doc}}\label{\detokenize{plugindev/kadm5_hook:kadm5-hook-plugin}}
  402 The kadm5\_hook interface allows modules to perform actions when
  403 changes are made to the Kerberos database through \DUrole{xref,std,std-ref}{kadmin(1)}.
  404 For a detailed description of the kadm5\_hook interface, see the header
  405 file \sphinxcode{\textless{}krb5/kadm5\_hook\_plugin.h\textgreater{}}.
  406 
  407 The kadm5\_hook interface has five primary methods: \sphinxstylestrong{chpass},
  408 \sphinxstylestrong{create}, \sphinxstylestrong{modify}, \sphinxstylestrong{remove}, and \sphinxstylestrong{rename}.  (The \sphinxstylestrong{rename}
  409 method was introduced in release 1.14.)  Each of these methods is
  410 called twice when the corresponding administrative action takes place,
  411 once before the action is committed and once afterwards.  A module can
  412 prevent the action from taking place by returning an error code during
  413 the pre-commit stage.
  414 
  415 A module can create and destroy per-process state objects by
  416 implementing the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  State objects have
  417 the type kadm5\_hook\_modinfo, which is an abstract pointer type.  A
  418 module should typically cast this to an internal type for the state
  419 object.
  420 
  421 Because the kadm5\_hook interface is tied closely to the kadmin
  422 interface (which is explicitly unstable), it may not remain as stable
  423 across versions as other public pluggable interfaces.
  424 
  425 
  426 \section{kadmin authorization interface (kadm5\_auth)}
  427 \label{\detokenize{plugindev/kadm5_auth:kadm5-auth-plugin}}\label{\detokenize{plugindev/kadm5_auth:kadmin-authorization-interface-kadm5-auth}}\label{\detokenize{plugindev/kadm5_auth::doc}}
  428 The kadm5\_auth interface (new in release 1.16) allows modules to
  429 determine whether a client principal is authorized to perform an
  430 operation in the kadmin protocol, and to apply restrictions to
  431 principal operations.  For a detailed description of the kadm5\_auth
  432 interface, see the header file \sphinxcode{\textless{}krb5/kadm5\_auth\_plugin.h\textgreater{}}.
  433 
  434 A module can create and destroy per-process state objects by
  435 implementing the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  State objects have
  436 the type kadm5\_auth\_modinfo, which is an abstract pointer type.  A
  437 module should typically cast this to an internal type for the state
  438 object.
  439 
  440 The kadm5\_auth interface has one method for each kadmin operation,
  441 with parameters specific to the operation.  Each method can return
  442 either 0 to authorize access, KRB5\_PLUGIN\_NO\_HANDLE to defer the
  443 decision to other modules, or another error (canonically EPERM) to
  444 authoritatively deny access.  Access is granted if at least one module
  445 grants access and no module authoritatively denies access.
  446 
  447 The \sphinxstylestrong{addprinc} and \sphinxstylestrong{modprinc} methods can also impose restrictions
  448 on the principal operation by returning a \sphinxcode{struct
  449 kadm5\_auth\_restrictions} object.  The module should also implement
  450 the \sphinxstylestrong{free\_restrictions} method if it dynamically allocates
  451 restrictions objects for principal operations.
  452 
  453 kadm5\_auth modules can optionally inspect principal or policy objects.
  454 To do this, the module must also include \sphinxcode{\textless{}kadm5/admin.h\textgreater{}} to gain
  455 access to the structure definitions for those objects.  As the kadmin
  456 interface is explicitly not as stable as other public interfaces,
  457 modules which do this may not retain compatibility across releases.
  458 
  459 
  460 \section{Host-to-realm interface (hostrealm)}
  461 \label{\detokenize{plugindev/hostrealm:hostrealm-plugin}}\label{\detokenize{plugindev/hostrealm::doc}}\label{\detokenize{plugindev/hostrealm:host-to-realm-interface-hostrealm}}
  462 The host-to-realm interface was first introduced in release 1.12.  It
  463 allows modules to control the local mapping of hostnames to realm
  464 names as well as the default realm.  For a detailed description of the
  465 hostrealm interface, see the header file
  466 \sphinxcode{\textless{}krb5/hostrealm\_plugin.h\textgreater{}}.
  467 
  468 Although the mapping methods in the hostrealm interface return a list
  469 of one or more realms, only the first realm in the list is currently
  470 used by callers.  Callers may begin using later responses in the
  471 future.
  472 
  473 Any mapping method may return KRB5\_PLUGIN\_NO\_HANDLE to defer
  474 processing to a later module.
  475 
  476 A module can create and destroy per-library-context state objects
  477 using the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  If the module does not need
  478 any state, it does not need to implement these methods.
  479 
  480 The optional \sphinxstylestrong{host\_realm} method allows a module to determine
  481 authoritative realm mappings for a hostname.  The first authoritative
  482 mapping is used in preference to KDC referrals when getting service
  483 credentials.
  484 
  485 The optional \sphinxstylestrong{fallback\_realm} method allows a module to determine
  486 fallback mappings for a hostname.  The first fallback mapping is tried
  487 if there is no authoritative mapping for a realm, and KDC referrals
  488 failed to produce a successful result.
  489 
  490 The optional \sphinxstylestrong{default\_realm} method allows a module to determine the
  491 local default realm.
  492 
  493 If a module implements any of the above methods, it must also
  494 implement \sphinxstylestrong{free\_list} to ensure that memory is allocated and
  495 deallocated consistently.
  496 
  497 
  498 \section{Local authorization interface (localauth)}
  499 \label{\detokenize{plugindev/localauth:local-authorization-interface-localauth}}\label{\detokenize{plugindev/localauth:localauth-plugin}}\label{\detokenize{plugindev/localauth::doc}}
  500 The localauth interface was first introduced in release 1.12.  It
  501 allows modules to control the relationship between Kerberos principals
  502 and local system accounts.  When an application calls
  503 \sphinxcode{krb5\_kuserok()} or \sphinxcode{krb5\_aname\_to\_localname()}, localauth
  504 modules are consulted to determine the result.  For a detailed
  505 description of the localauth interface, see the header file
  506 \sphinxcode{\textless{}krb5/localauth\_plugin.h\textgreater{}}.
  507 
  508 A module can create and destroy per-library-context state objects
  509 using the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  If the module does not need
  510 any state, it does not need to implement these methods.
  511 
  512 The optional \sphinxstylestrong{userok} method allows a module to control the behavior
  513 of \sphinxcode{krb5\_kuserok()}.  The module receives the authenticated name
  514 and the local account name as inputs, and can return either 0 to
  515 authorize access, KRB5\_PLUGIN\_NO\_HANDLE to defer the decision to other
  516 modules, or another error (canonically EPERM) to authoritatively deny
  517 access.  Access is granted if at least one module grants access and no
  518 module authoritatively denies access.
  519 
  520 The optional \sphinxstylestrong{an2ln} method can work in two different ways.  If the
  521 module sets an array of uppercase type names in \sphinxstylestrong{an2ln\_types}, then
  522 the module’s \sphinxstylestrong{an2ln} method will only be invoked by
  523 \sphinxcode{krb5\_aname\_to\_localname()} if an \sphinxstylestrong{auth\_to\_local} value in
  524 \DUrole{xref,std,std-ref}{krb5.conf(5)} refers to one of the module’s types.  In this
  525 case, the \sphinxstyleemphasis{type} and \sphinxstyleemphasis{residual} arguments will give the type name and
  526 residual string of the \sphinxstylestrong{auth\_to\_local} value.
  527 
  528 If the module does not set \sphinxstylestrong{an2ln\_types} but does implement
  529 \sphinxstylestrong{an2ln}, the module’s \sphinxstylestrong{an2ln} method will be invoked for all
  530 \sphinxcode{krb5\_aname\_to\_localname()} operations unless an earlier module
  531 determines a mapping, with \sphinxstyleemphasis{type} and \sphinxstyleemphasis{residual} set to NULL.  The
  532 module can return KRB5\_LNAME\_NO\_TRANS to defer mapping to later
  533 modules.
  534 
  535 If a module implements \sphinxstylestrong{an2ln}, it must also implement
  536 \sphinxstylestrong{free\_string} to ensure that memory is allocated and deallocated
  537 consistently.
  538 
  539 
  540 \section{Server location interface (locate)}
  541 \label{\detokenize{plugindev/locate:server-location-interface-locate}}\label{\detokenize{plugindev/locate::doc}}
  542 The locate interface allows modules to control how KDCs and similar
  543 services are located by clients.  For a detailed description of the
  544 ccselect interface, see the header file \sphinxcode{\textless{}krb5/locate\_plugin.h\textgreater{}}.
  545 
  546 A locate module exports a structure object of type
  547 krb5plugin\_service\_locate\_ftable, with the name \sphinxcode{service\_locator}.
  548 The structure contains a minor version and pointers to the module’s
  549 methods.
  550 
  551 The primary locate method is \sphinxstylestrong{lookup}, which accepts a service type,
  552 realm name, desired socket type, and desired address family (which
  553 will be AF\_UNSPEC if no specific address family is desired).  The
  554 method should invoke the callback function once for each server
  555 address it wants to return, passing a socket type (SOCK\_STREAM for TCP
  556 or SOCK\_DGRAM for UDP) and socket address.  The \sphinxstylestrong{lookup} method
  557 should return 0 if it has authoritatively determined the server
  558 addresses for the realm, KRB5\_PLUGIN\_NO\_HANDLE if it wants to let
  559 other location mechanisms determine the server addresses, or another
  560 code if it experienced a failure which should abort the location
  561 process.
  562 
  563 A module can create and destroy per-library-context state objects by
  564 implementing the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  State objects have
  565 the type void *, and should be cast to an internal type for the state
  566 object.
  567 
  568 
  569 \section{Configuration interface (profile)}
  570 \label{\detokenize{plugindev/profile:configuration-interface-profile}}\label{\detokenize{plugindev/profile::doc}}\label{\detokenize{plugindev/profile:profile-plugin}}
  571 The profile interface allows a module to control how krb5
  572 configuration information is obtained by the Kerberos library and
  573 applications.  For a detailed description of the profile interface,
  574 see the header file \sphinxcode{\textless{}profile.h\textgreater{}}.
  575 
  576 \begin{sphinxadmonition}{note}{Note:}
  577 The profile interface does not follow the normal conventions
  578 for MIT krb5 pluggable interfaces, because it is part of a
  579 lower-level component of the krb5 library.
  580 \end{sphinxadmonition}
  581 
  582 As with other types of plugin modules, a profile module is a Unix
  583 shared object or Windows DLL, built separately from the krb5 tree.
  584 The krb5 library will dynamically load and use a profile plugin module
  585 if it reads a \sphinxcode{module} directive at the beginning of krb5.conf, as
  586 described in \DUrole{xref,std,std-ref}{profile\_plugin\_config}.
  587 
  588 A profile module exports a function named \sphinxcode{profile\_module\_init}
  589 matching the signature of the profile\_module\_init\_fn type.  This
  590 function accepts a residual string, which may be used to help locate
  591 the configuration source.  The function fills in a vtable and may also
  592 create a per-profile state object.  If the module uses state objects,
  593 it should implement the \sphinxstylestrong{copy} and \sphinxstylestrong{cleanup} methods to manage
  594 them.
  595 
  596 A basic read-only profile module need only implement the
  597 \sphinxstylestrong{get\_values} and \sphinxstylestrong{free\_values} methods.  The \sphinxstylestrong{get\_values} method
  598 accepts a null-terminated list of C string names (e.g., an array
  599 containing “libdefaults”, “clockskew”, and NULL for the \sphinxstylestrong{clockskew}
  600 variable in the \DUrole{xref,std,std-ref}{libdefaults} section) and returns a
  601 null-terminated list of values, which will be cleaned up with the
  602 \sphinxstylestrong{free\_values} method when the caller is done with them.
  603 
  604 Iterable profile modules must also define the \sphinxstylestrong{iterator\_create},
  605 \sphinxstylestrong{iterator}, \sphinxstylestrong{iterator\_free}, and \sphinxstylestrong{free\_string} methods.  The
  606 core krb5 code does not require profiles to be iterable, but some
  607 applications may iterate over the krb5 profile object in order to
  608 present configuration interfaces.
  609 
  610 Writable profile modules must also define the \sphinxstylestrong{writable},
  611 \sphinxstylestrong{modified}, \sphinxstylestrong{update\_relation}, \sphinxstylestrong{rename\_section},
  612 \sphinxstylestrong{add\_relation}, and \sphinxstylestrong{flush} methods.  The core krb5 code does not
  613 require profiles to be writable, but some applications may write to
  614 the krb5 profile in order to present configuration interfaces.
  615 
  616 The following is an example of a very basic read-only profile module
  617 which returns a hardcoded value for the \sphinxstylestrong{default\_realm} variable in
  618 \DUrole{xref,std,std-ref}{libdefaults}, and provides no other configuration information.
  619 (For conciseness, the example omits code for checking the return
  620 values of malloc and strdup.)
  621 
  622 \fvset{hllines={, ,}}%
  623 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  624 \PYG{c+c1}{\PYGZsh{}include \PYGZlt{}stdlib.h\PYGZgt{}}
  625 \PYG{c+c1}{\PYGZsh{}include \PYGZlt{}string.h\PYGZgt{}}
  626 \PYG{c+c1}{\PYGZsh{}include \PYGZlt{}profile.h\PYGZgt{}}
  627 
  628 \PYG{n}{static} \PYG{n}{long}
  629 \PYG{n}{get\PYGZus{}values}\PYG{p}{(}\PYG{n}{void} \PYG{o}{*}\PYG{n}{cbdata}\PYG{p}{,} \PYG{n}{const} \PYG{n}{char} \PYG{o}{*}\PYG{n}{const} \PYG{o}{*}\PYG{n}{names}\PYG{p}{,} \PYG{n}{char} \PYG{o}{*}\PYG{o}{*}\PYG{o}{*}\PYG{n}{values}\PYG{p}{)}
  630 \PYG{p}{\PYGZob{}}
  631     \PYG{k}{if} \PYG{p}{(}\PYG{n}{names}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]} \PYG{o}{!=} \PYG{n}{NULL} \PYG{o}{\PYGZam{}}\PYG{o}{\PYGZam{}} \PYG{n}{strcmp}\PYG{p}{(}\PYG{n}{names}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{libdefaults}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)} \PYG{o}{==} \PYG{l+m+mi}{0} \PYG{o}{\PYGZam{}}\PYG{o}{\PYGZam{}}
  632         \PYG{n}{names}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]} \PYG{o}{!=} \PYG{n}{NULL} \PYG{o}{\PYGZam{}}\PYG{o}{\PYGZam{}} \PYG{n}{strcmp}\PYG{p}{(}\PYG{n}{names}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{default\PYGZus{}realm}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{)} \PYG{p}{\PYGZob{}}
  633         \PYG{o}{*}\PYG{n}{values} \PYG{o}{=} \PYG{n}{malloc}\PYG{p}{(}\PYG{l+m+mi}{2} \PYG{o}{*} \PYG{n}{sizeof}\PYG{p}{(}\PYG{n}{char} \PYG{o}{*}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
  634         \PYG{p}{(}\PYG{o}{*}\PYG{n}{values}\PYG{p}{)}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]} \PYG{o}{=} \PYG{n}{strdup}\PYG{p}{(}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ATHENA.MIT.EDU}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
  635         \PYG{p}{(}\PYG{o}{*}\PYG{n}{values}\PYG{p}{)}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]} \PYG{o}{=} \PYG{n}{NULL}\PYG{p}{;}
  636         \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;}
  637     \PYG{p}{\PYGZcb{}}
  638     \PYG{k}{return} \PYG{n}{PROF\PYGZus{}NO\PYGZus{}RELATION}\PYG{p}{;}
  639 \PYG{p}{\PYGZcb{}}
  640 
  641 \PYG{n}{static} \PYG{n}{void}
  642 \PYG{n}{free\PYGZus{}values}\PYG{p}{(}\PYG{n}{void} \PYG{o}{*}\PYG{n}{cbdata}\PYG{p}{,} \PYG{n}{char} \PYG{o}{*}\PYG{o}{*}\PYG{n}{values}\PYG{p}{)}
  643 \PYG{p}{\PYGZob{}}
  644     \PYG{n}{char} \PYG{o}{*}\PYG{o}{*}\PYG{n}{v}\PYG{p}{;}
  645 
  646     \PYG{k}{for} \PYG{p}{(}\PYG{n}{v} \PYG{o}{=} \PYG{n}{values}\PYG{p}{;} \PYG{o}{*}\PYG{n}{v}\PYG{p}{;} \PYG{n}{v}\PYG{o}{+}\PYG{o}{+}\PYG{p}{)}
  647         \PYG{n}{free}\PYG{p}{(}\PYG{o}{*}\PYG{n}{v}\PYG{p}{)}\PYG{p}{;}
  648     \PYG{n}{free}\PYG{p}{(}\PYG{n}{values}\PYG{p}{)}\PYG{p}{;}
  649 \PYG{p}{\PYGZcb{}}
  650 
  651 \PYG{n}{long}
  652 \PYG{n}{profile\PYGZus{}module\PYGZus{}init}\PYG{p}{(}\PYG{n}{const} \PYG{n}{char} \PYG{o}{*}\PYG{n}{residual}\PYG{p}{,} \PYG{n}{struct} \PYG{n}{profile\PYGZus{}vtable} \PYG{o}{*}\PYG{n}{vtable}\PYG{p}{,}
  653                     \PYG{n}{void} \PYG{o}{*}\PYG{o}{*}\PYG{n}{cb\PYGZus{}ret}\PYG{p}{)}\PYG{p}{;}
  654 
  655 \PYG{n}{long}
  656 \PYG{n}{profile\PYGZus{}module\PYGZus{}init}\PYG{p}{(}\PYG{n}{const} \PYG{n}{char} \PYG{o}{*}\PYG{n}{residual}\PYG{p}{,} \PYG{n}{struct} \PYG{n}{profile\PYGZus{}vtable} \PYG{o}{*}\PYG{n}{vtable}\PYG{p}{,}
  657                     \PYG{n}{void} \PYG{o}{*}\PYG{o}{*}\PYG{n}{cb\PYGZus{}ret}\PYG{p}{)}
  658 \PYG{p}{\PYGZob{}}
  659     \PYG{o}{*}\PYG{n}{cb\PYGZus{}ret} \PYG{o}{=} \PYG{n}{NULL}\PYG{p}{;}
  660     \PYG{n}{vtable}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{get\PYGZus{}values} \PYG{o}{=} \PYG{n}{get\PYGZus{}values}\PYG{p}{;}
  661     \PYG{n}{vtable}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{free\PYGZus{}values} \PYG{o}{=} \PYG{n}{free\PYGZus{}values}\PYG{p}{;}
  662     \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;}
  663 \PYG{p}{\PYGZcb{}}
  664 \end{sphinxVerbatim}
  665 
  666 
  667 \section{GSSAPI mechanism interface}
  668 \label{\detokenize{plugindev/gssapi::doc}}\label{\detokenize{plugindev/gssapi:gssapi-mechanism-interface}}
  669 The GSSAPI library in MIT krb5 can load mechanism modules to augment
  670 the set of built-in mechanisms.
  671 
  672 A mechanism module is a Unix shared object or Windows DLL, built
  673 separately from the krb5 tree.  Modules are loaded according to the
  674 GSS mechanism config files described in \DUrole{xref,std,std-ref}{gssapi\_plugin\_config}.
  675 
  676 For the most part, a GSSAPI mechanism module exports the same
  677 functions as would a GSSAPI implementation itself, with the same
  678 function signatures.  The mechanism selection layer within the GSSAPI
  679 library (called the “mechglue”) will dispatch calls from the
  680 application to the module if the module’s mechanism is requested.  If
  681 a module does not wish to implement a GSSAPI extension, it can simply
  682 refrain from exporting it, and the mechglue will fail gracefully if
  683 the application calls that function.
  684 
  685 The mechglue does not invoke a module’s \sphinxstylestrong{gss\_add\_cred},
  686 \sphinxstylestrong{gss\_add\_cred\_from}, \sphinxstylestrong{gss\_add\_cred\_impersonate\_name}, or
  687 \sphinxstylestrong{gss\_add\_cred\_with\_password} function.  A mechanism only needs to
  688 implement the “acquire” variants of those functions.
  689 
  690 A module does not need to coordinate its minor status codes with those
  691 of other mechanisms.  If the mechglue detects conflicts, it will map
  692 the mechanism’s status codes onto unique values, and then map them
  693 back again when \sphinxstylestrong{gss\_display\_status} is called.
  694 
  695 
  696 \subsection{NegoEx modules}
  697 \label{\detokenize{plugindev/gssapi:negoex-modules}}
  698 Some Windows GSSAPI mechanisms can only be negotiated via a Microsoft
  699 extension to SPNEGO called NegoEx.  Beginning with release 1.18,
  700 mechanism modules can support NegoEx as follows:
  701 \begin{itemize}
  702 \item {} 
  703 Implement the gssspi\_query\_meta\_data(), gssspi\_exchange\_meta\_data(),
  704 and gssspi\_query\_mechanism\_info() SPIs declared in
  705 \sphinxcode{\textless{}gssapi/gssapi\_ext.h\textgreater{}}.
  706 
  707 \item {} 
  708 Implement gss\_inquire\_sec\_context\_by\_oid() and answer the
  709 \sphinxstylestrong{GSS\_C\_INQ\_NEGOEX\_KEY} and \sphinxstylestrong{GSS\_C\_INQ\_NEGOEX\_VERIFY\_KEY} OIDs
  710 to provide the checksum keys for outgoing and incoming checksums,
  711 respectively.  The answer must be in two buffers: the first buffer
  712 contains the key contents, and the second buffer contains the key
  713 encryption type as a four-byte little-endian integer.
  714 
  715 \end{itemize}
  716 
  717 By default, NegoEx mechanisms will not be directly negotiated via
  718 SPNEGO.  If direct SPNEGO negotiation is required for
  719 interoperability, implement gss\_inquire\_attrs\_for\_mech() and assert
  720 the GSS\_C\_MA\_NEGOEX\_AND\_SPNEGO attribute (along with any applicable
  721 RFC 5587 attributes).
  722 
  723 
  724 \subsection{Interposer modules}
  725 \label{\detokenize{plugindev/gssapi:interposer-modules}}
  726 The mechglue also supports a kind of loadable module, called an
  727 interposer module, which intercepts calls to existing mechanisms
  728 rather than implementing a new mechanism.
  729 
  730 An interposer module must export the symbol \sphinxstylestrong{gss\_mech\_interposer}
  731 with the following signature:
  732 
  733 \fvset{hllines={, ,}}%
  734 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  735 \PYG{n}{gss\PYGZus{}OID\PYGZus{}set} \PYG{n}{gss\PYGZus{}mech\PYGZus{}interposer}\PYG{p}{(}\PYG{n}{gss\PYGZus{}OID} \PYG{n}{mech\PYGZus{}type}\PYG{p}{)}\PYG{p}{;}
  736 \end{sphinxVerbatim}
  737 
  738 This function is invoked with the OID of the interposer mechanism as
  739 specified in the mechanism config file, and returns a set of mechanism
  740 OIDs to be interposed.  The returned OID set must have been created
  741 using the mechglue’s gss\_create\_empty\_oid\_set and
  742 gss\_add\_oid\_set\_member functions.
  743 
  744 An interposer module must use the prefix \sphinxcode{gssi\_} for the GSSAPI
  745 functions it exports, instead of the prefix \sphinxcode{gss\_}.
  746 
  747 An interposer module can link against the GSSAPI library in order to
  748 make calls to the original mechanism.  To do so, it must specify a
  749 special mechanism OID which is the concatention of the interposer’s
  750 own OID byte string and the original mechanism’s OID byte string.
  751 
  752 Since \sphinxstylestrong{gss\_accept\_sec\_context} does not accept a mechanism argument,
  753 an interposer mechanism must, in order to invoke the original
  754 mechanism’s function, acquire a credential for the concatenated OID
  755 and pass that as the \sphinxstyleemphasis{verifier\_cred\_handle} parameter.
  756 
  757 Since \sphinxstylestrong{gss\_import\_name}, \sphinxstylestrong{gss\_import\_cred}, and
  758 \sphinxstylestrong{gss\_import\_sec\_context} do not accept mechanism parameters, the SPI
  759 has been extended to include variants which do.  This allows the
  760 interposer module to know which mechanism should be used to interpret
  761 the token.  These functions have the following signatures:
  762 
  763 \fvset{hllines={, ,}}%
  764 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  765 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gssi\PYGZus{}import\PYGZus{}sec\PYGZus{}context\PYGZus{}by\PYGZus{}mech}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  766     \PYG{n}{gss\PYGZus{}OID} \PYG{n}{desired\PYGZus{}mech}\PYG{p}{,} \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{interprocess\PYGZus{}token}\PYG{p}{,}
  767     \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{o}{*}\PYG{n}{context\PYGZus{}handle}\PYG{p}{)}\PYG{p}{;}
  768 
  769 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gssi\PYGZus{}import\PYGZus{}name\PYGZus{}by\PYGZus{}mech}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  770     \PYG{n}{gss\PYGZus{}OID} \PYG{n}{mech\PYGZus{}type}\PYG{p}{,} \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{input\PYGZus{}name\PYGZus{}buffer}\PYG{p}{,}
  771     \PYG{n}{gss\PYGZus{}OID} \PYG{n}{input\PYGZus{}name\PYGZus{}type}\PYG{p}{,} \PYG{n}{gss\PYGZus{}name\PYGZus{}t} \PYG{n}{output\PYGZus{}name}\PYG{p}{)}\PYG{p}{;}
  772 
  773 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gssi\PYGZus{}import\PYGZus{}cred\PYGZus{}by\PYGZus{}mech}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  774     \PYG{n}{gss\PYGZus{}OID} \PYG{n}{mech\PYGZus{}type}\PYG{p}{,} \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{token}\PYG{p}{,}
  775     \PYG{n}{gss\PYGZus{}cred\PYGZus{}id\PYGZus{}t} \PYG{o}{*}\PYG{n}{cred\PYGZus{}handle}\PYG{p}{)}\PYG{p}{;}
  776 \end{sphinxVerbatim}
  777 
  778 To re-enter the original mechanism when importing tokens for the above
  779 functions, the interposer module must wrap the mechanism token in the
  780 mechglue’s format, using the concatenated OID.  The mechglue token
  781 formats are:
  782 \begin{itemize}
  783 \item {} 
  784 For \sphinxstylestrong{gss\_import\_sec\_context}, a four-byte OID length in big-endian
  785 order, followed by the mechanism OID, followed by the mechanism
  786 token.
  787 
  788 \item {} 
  789 For \sphinxstylestrong{gss\_import\_name}, the bytes 04 01, followed by a two-byte OID
  790 length in big-endian order, followed by the mechanism OID, followed
  791 by the bytes 06, followed by the OID length as a single byte,
  792 followed by the mechanism OID, followed by the mechanism token.
  793 
  794 \item {} 
  795 For \sphinxstylestrong{gss\_import\_cred}, a four-byte OID length in big-endian order,
  796 followed by the mechanism OID, followed by a four-byte token length
  797 in big-endian order, followed by the mechanism token.  This sequence
  798 may be repeated multiple times.
  799 
  800 \end{itemize}
  801 
  802 
  803 \section{Internal pluggable interfaces}
  804 \label{\detokenize{plugindev/internal::doc}}\label{\detokenize{plugindev/internal:internal-pluggable-interfaces}}
  805 Following are brief discussions of pluggable interfaces which have not
  806 yet been made public.  These interfaces are functional, but the
  807 interfaces are likely to change in incompatible ways from release to
  808 release.  In some cases, it may be necessary to copy header files from
  809 the krb5 source tree to use an internal interface.  Use these with
  810 care, and expect to need to update your modules for each new release
  811 of MIT krb5.
  812 
  813 
  814 \subsection{Kerberos database interface (KDB)}
  815 \label{\detokenize{plugindev/internal:kerberos-database-interface-kdb}}
  816 A KDB module implements a database back end for KDC principal and
  817 policy information, and can also control many aspects of KDC behavior.
  818 For a full description of the interface, see the header file
  819 \sphinxcode{\textless{}kdb.h\textgreater{}}.
  820 
  821 The KDB pluggable interface is often referred to as the DAL (Database
  822 Access Layer).
  823 
  824 
  825 \subsection{Authorization data interface (authdata)}
  826 \label{\detokenize{plugindev/internal:authorization-data-interface-authdata}}
  827 The authdata interface allows a module to provide (from the KDC) or
  828 consume (in application servers) authorization data of types beyond
  829 those handled by the core MIT krb5 code base.  The interface is
  830 defined in the header file \sphinxcode{\textless{}krb5/authdata\_plugin.h\textgreater{}}, which is not
  831 installed by the build.
  832 
  833 
  834 \section{PKINIT certificate authorization interface (certauth)}
  835 \label{\detokenize{plugindev/certauth:certauth-plugin}}\label{\detokenize{plugindev/certauth::doc}}\label{\detokenize{plugindev/certauth:pkinit-certificate-authorization-interface-certauth}}
  836 The certauth interface was first introduced in release 1.16.  It
  837 allows customization of the X.509 certificate attribute requirements
  838 placed on certificates used by PKINIT enabled clients.  For a detailed
  839 description of the certauth interface, see the header file
  840 \sphinxcode{\textless{}krb5/certauth\_plugin.h\textgreater{}}
  841 
  842 A certauth module implements the \sphinxstylestrong{authorize} method to determine
  843 whether a client’s certificate is authorized to authenticate a client
  844 principal.  \sphinxstylestrong{authorize} receives the DER-encoded certificate, the
  845 requested client principal, and a pointer to the client’s
  846 krb5\_db\_entry (for modules that link against libkdb5).  It returns the
  847 authorization status and optionally outputs a list of authentication
  848 indicator strings to be added to the ticket.  A module must use its
  849 own internal or library-provided ASN.1 certificate decoder.
  850 
  851 A module can optionally create and destroy module data with the
  852 \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  Module data objects last for the
  853 lifetime of the KDC process.
  854 
  855 If a module allocates and returns a list of authentication indicators
  856 from \sphinxstylestrong{authorize}, it must also implement the \sphinxstylestrong{free\_ind} method
  857 to free the list.
  858 
  859 
  860 \section{KDC policy interface (kdcpolicy)}
  861 \label{\detokenize{plugindev/kdcpolicy:kdcpolicy-plugin}}\label{\detokenize{plugindev/kdcpolicy::doc}}\label{\detokenize{plugindev/kdcpolicy:kdc-policy-interface-kdcpolicy}}
  862 The kdcpolicy interface was first introduced in release 1.16.  It
  863 allows modules to veto otherwise valid AS and TGS requests or restrict
  864 the lifetime and renew time of the resulting ticket.  For a detailed
  865 description of the kdcpolicy interface, see the header file
  866 \sphinxcode{\textless{}krb5/kdcpolicy\_plugin.h\textgreater{}}.
  867 
  868 The optional \sphinxstylestrong{check\_as} and \sphinxstylestrong{check\_tgs} functions allow the module
  869 to perform access control.  Additionally, a module can create and
  870 destroy module data with the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods.  Module
  871 data objects last for the lifetime of the KDC process, and are
  872 provided to all other methods.  The data has the type
  873 krb5\_kdcpolicy\_moddata, which should be cast to the appropriate
  874 internal type.
  875 
  876 kdcpolicy modules can optionally inspect principal entries.  To do
  877 this, the module must also include \sphinxcode{\textless{}kdb.h\textgreater{}} to gain access to the
  878 principal entry structure definition.  As the KDB interface is
  879 explicitly not as stable as other public interfaces, modules which do
  880 this may not retain compatibility across releases.
  881 
  882 
  883 
  884 \renewcommand{\indexname}{Index}
  885 \printindex
  886 \end{document}