diff options
Diffstat (limited to 'crypto/krb5/doc/pdf/plugindev.tex')
| -rw-r--r-- | crypto/krb5/doc/pdf/plugindev.tex | 1020 |
1 files changed, 0 insertions, 1020 deletions
diff --git a/crypto/krb5/doc/pdf/plugindev.tex b/crypto/krb5/doc/pdf/plugindev.tex deleted file mode 100644 index 0bb2bc520e83..000000000000 --- a/crypto/krb5/doc/pdf/plugindev.tex +++ /dev/null @@ -1,1020 +0,0 @@ -%% Generated by Sphinx. -\def\sphinxdocclass{report} -\documentclass[letterpaper,10pt,english]{sphinxmanual} -\ifdefined\pdfpxdimen - \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen -\fi \sphinxpxdimen=.75bp\relax -\ifdefined\pdfimageresolution - \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax -\fi -%% let collapsible pdf bookmarks panel have high depth per default -\PassOptionsToPackage{bookmarksdepth=5}{hyperref} - -\PassOptionsToPackage{warn}{textcomp} -\usepackage[utf8]{inputenc} -\ifdefined\DeclareUnicodeCharacter -% support both utf8 and utf8x syntaxes - \ifdefined\DeclareUnicodeCharacterAsOptional - \def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}} - \else - \let\sphinxDUC\DeclareUnicodeCharacter - \fi - \sphinxDUC{00A0}{\nobreakspace} - \sphinxDUC{2500}{\sphinxunichar{2500}} - \sphinxDUC{2502}{\sphinxunichar{2502}} - \sphinxDUC{2514}{\sphinxunichar{2514}} - \sphinxDUC{251C}{\sphinxunichar{251C}} - \sphinxDUC{2572}{\textbackslash} -\fi -\usepackage{cmap} -\usepackage[T1]{fontenc} -\usepackage{amsmath,amssymb,amstext} -\usepackage{babel} - - - -\usepackage{tgtermes} -\usepackage{tgheros} -\renewcommand{\ttdefault}{txtt} - - - -\usepackage[Bjarne]{fncychap} -\usepackage{sphinx} - -\fvset{fontsize=auto} -\usepackage{geometry} - - -% Include hyperref last. -\usepackage{hyperref} -% Fix anchor placement for figures with captions. -\usepackage{hypcap}% it must be loaded after hyperref. -% Set up styles of URL: it should be placed after hyperref. -\urlstyle{same} - - -\usepackage{sphinxmessages} -\setcounter{tocdepth}{1} - - - -\title{Kerberos Plugin Module Developer Guide} -\date{ } -\release{1.21.3} -\author{MIT} -\newcommand{\sphinxlogo}{\vbox{}} -\renewcommand{\releasename}{Release} -\makeindex -\begin{document} - -\pagestyle{empty} -\sphinxmaketitle -\pagestyle{plain} -\sphinxtableofcontents -\pagestyle{normal} -\phantomsection\label{\detokenize{plugindev/index::doc}} - - -\sphinxAtStartPar -Kerberos plugin modules allow increased control over MIT krb5 library -and server behavior. This guide describes how to create dynamic -plugin modules and the currently available pluggable interfaces. - -\sphinxAtStartPar -See \DUrole{xref,std,std-ref}{plugin\_config} for information on how to register dynamic -plugin modules and how to enable and disable modules via -\DUrole{xref,std,std-ref}{krb5.conf(5)}. - - -\chapter{Contents} -\label{\detokenize{plugindev/index:contents}} - -\section{General plugin concepts} -\label{\detokenize{plugindev/general:general-plugin-concepts}}\label{\detokenize{plugindev/general::doc}} -\sphinxAtStartPar -A krb5 dynamic plugin module is a Unix shared object or Windows DLL. -Typically, the source code for a dynamic plugin module should live in -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 -tools with similar functionality. - -\sphinxAtStartPar -A plugin module must define a specific symbol name, which depends on -the pluggable interface and module name. For most pluggable -interfaces, the exported symbol is a function named -\sphinxcode{\sphinxupquote{INTERFACE\_MODULE\_initvt}}, where \sphinxstyleemphasis{INTERFACE} is the name of the -pluggable interface and \sphinxstyleemphasis{MODULE} is the name of the module. For these -interfaces, it is possible for one shared object or DLL to implement -multiple plugin modules, either for the same pluggable interface or -for different ones. For example, a shared object could implement both -KDC and client preauthentication mechanisms, by exporting functions -named \sphinxcode{\sphinxupquote{kdcpreauth\_mymech\_initvt}} and \sphinxcode{\sphinxupquote{clpreauth\_mymech\_initvt}}. - -\sphinxAtStartPar -A plugin module implementation should include the header file -\sphinxcode{\sphinxupquote{\textless{}krb5/INTERFACE\_plugin.h\textgreater{}}}, where \sphinxstyleemphasis{INTERFACE} is the name of the -pluggable interface. For instance, a ccselect plugin module -implementation should use \sphinxcode{\sphinxupquote{\#include \textless{}krb5/ccselect\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -initvt functions have the following prototype: - -\begin{sphinxVerbatim}[commandchars=\\\{\}] -\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}{,} - \PYG{n+nb}{int} \PYG{n}{maj\PYGZus{}ver}\PYG{p}{,} \PYG{n+nb}{int} \PYG{n}{min\PYGZus{}ver}\PYG{p}{,} - \PYG{n}{krb5\PYGZus{}plugin\PYGZus{}vtable} \PYG{n}{vtable}\PYG{p}{)}\PYG{p}{;} -\end{sphinxVerbatim} - -\sphinxAtStartPar -and should do the following: -\begin{enumerate} -\sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}% -\item {} -\sphinxAtStartPar -Check that the supplied maj\_ver argument is supported by the -module. If it is not supported, the function should return -KRB5\_PLUGIN\_VER\_NOTSUPP. - -\item {} -\sphinxAtStartPar -Cast the supplied vtable pointer to the structure type -corresponding to the major version, as documented in the pluggable -interface header file. - -\item {} -\sphinxAtStartPar -Fill in the structure fields with pointers to method functions and -static data, stopping at the field indicated by the supplied minor -version. Fields for unimplemented optional methods can be left -alone; it is not necessary to initialize them to NULL. - -\end{enumerate} - -\sphinxAtStartPar -In most cases, the context argument will not be used. The initvt -function should not allocate memory; think of it as a glorified -structure initializer. Each pluggable interface defines methods for -allocating and freeing module state if doing so is necessary for the -interface. - -\sphinxAtStartPar -Pluggable interfaces typically include a \sphinxstylestrong{name} field in the vtable -structure, which should be filled in with a pointer to a string -literal containing the module name. - -\sphinxAtStartPar -Here is an example of what an initvt function might look like for a -fictional pluggable interface named fences, for a module named -“wicker”: - -\begin{sphinxVerbatim}[commandchars=\\\{\}] -\PYG{n}{krb5\PYGZus{}error\PYGZus{}code} -\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}{,} - \PYG{n+nb}{int} \PYG{n}{min\PYGZus{}ver}\PYG{p}{,} \PYG{n}{krb5\PYGZus{}plugin\PYGZus{}vtable} \PYG{n}{vtable}\PYG{p}{)} -\PYG{p}{\PYGZob{}} - \PYG{n}{krb5\PYGZus{}ccselect\PYGZus{}vtable} \PYG{n}{vt}\PYG{p}{;} - - \PYG{k}{if} \PYG{p}{(}\PYG{n}{maj\PYGZus{}ver} \PYG{o}{==} \PYG{l+m+mi}{1}\PYG{p}{)} \PYG{p}{\PYGZob{}} - \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}{;} - \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}{;} - \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{slats} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}slats}\PYG{p}{;} - \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{braces} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}braces}\PYG{p}{;} - \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{}} - \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}{;} - \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}{;} - \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{material} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}material}\PYG{p}{;} - \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{construction} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}construction}\PYG{p}{;} - \PYG{k}{if} \PYG{p}{(}\PYG{n}{min\PYGZus{}ver} \PYG{o}{\PYGZlt{}} \PYG{l+m+mi}{2}\PYG{p}{)} - \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;} - \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{footing} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}footing}\PYG{p}{;} - \PYG{k}{if} \PYG{p}{(}\PYG{n}{min\PYGZus{}ver} \PYG{o}{\PYGZlt{}} \PYG{l+m+mi}{3}\PYG{p}{)} - \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;} - \PYG{n}{vt}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{appearance} \PYG{o}{=} \PYG{n}{wicker\PYGZus{}appearance}\PYG{p}{;} - \PYG{p}{\PYGZcb{}} \PYG{k}{else} \PYG{p}{\PYGZob{}} - \PYG{k}{return} \PYG{n}{KRB5\PYGZus{}PLUGIN\PYGZus{}VER\PYGZus{}NOTSUPP}\PYG{p}{;} - \PYG{p}{\PYGZcb{}} - \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;} -\PYG{p}{\PYGZcb{}} -\end{sphinxVerbatim} - - -\subsection{Logging from KDC and kadmind plugin modules} -\label{\detokenize{plugindev/general:logging-from-kdc-and-kadmind-plugin-modules}} -\sphinxAtStartPar -Plugin modules for the KDC or kadmind daemons can write to the -configured logging outputs (see \DUrole{xref,std,std-ref}{logging}) by calling the -\sphinxstylestrong{com\_err} function. The first argument (\sphinxstyleemphasis{whoami}) is ignored. If -the second argument (\sphinxstyleemphasis{code}) is zero, the formatted message is logged -at informational severity; otherwise, the formatted message is logged -at error severity and includes the error message for the supplied -code. Here are examples: - -\begin{sphinxVerbatim}[commandchars=\\\{\}] -\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}{;} -\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}{;} -\end{sphinxVerbatim} - -\sphinxAtStartPar -(The behavior described above is new in release 1.17. In prior -releases, the \sphinxstyleemphasis{whoami} argument is included for some logging output -types, the logged message does not include the usual header for some -output types, and the severity for syslog outputs is configured as -part of the logging specification, defaulting to error severity.) - - -\section{Client preauthentication interface (clpreauth)} -\label{\detokenize{plugindev/clpreauth:client-preauthentication-interface-clpreauth}}\label{\detokenize{plugindev/clpreauth::doc}} -\sphinxAtStartPar -During an initial ticket request, a KDC may ask a client to prove its -knowledge of the password before issuing an encrypted ticket, or to -use credentials other than a password. This process is called -preauthentication, and is described in \index{RFC@\spxentry{RFC}!RFC 4120@\spxentry{RFC 4120}}\sphinxhref{https://tools.ietf.org/html/rfc4120.html}{\sphinxstylestrong{RFC 4120}} and \index{RFC@\spxentry{RFC}!RFC 6113@\spxentry{RFC 6113}}\sphinxhref{https://tools.ietf.org/html/rfc6113.html}{\sphinxstylestrong{RFC 6113}}. -The clpreauth interface allows the addition of client support for -preauthentication mechanisms beyond those included in the core MIT -krb5 code base. For a detailed description of the clpreauth -interface, see the header file \sphinxcode{\sphinxupquote{\textless{}krb5/clpreauth\_plugin.h\textgreater{}}} (or -\sphinxcode{\sphinxupquote{\textless{}krb5/preauth\_plugin.h\textgreater{}}} before release 1.12). - -\sphinxAtStartPar -A clpreauth module is generally responsible for: -\begin{itemize} -\item {} -\sphinxAtStartPar -Supplying a list of preauth type numbers used by the module in the -\sphinxstylestrong{pa\_type\_list} field of the vtable structure. - -\item {} -\sphinxAtStartPar -Indicating what kind of preauthentication mechanism it implements, -with the \sphinxstylestrong{flags} method. In the most common case, this method -just returns \sphinxcode{\sphinxupquote{PA\_REAL}}, indicating that it implements a normal -preauthentication type. - -\item {} -\sphinxAtStartPar -Examining the padata information included in a PREAUTH\_REQUIRED or -MORE\_PREAUTH\_DATA\_REQUIRED error and producing padata values for the -next AS request. This is done with the \sphinxstylestrong{process} method. - -\item {} -\sphinxAtStartPar -Examining the padata information included in a successful ticket -reply, possibly verifying the KDC identity and computing a reply -key. This is also done with the \sphinxstylestrong{process} method. - -\item {} -\sphinxAtStartPar -For preauthentication types which support it, recovering from errors -by examining the error data from the KDC and producing a padata -value for another AS request. This is done with the \sphinxstylestrong{tryagain} -method. - -\item {} -\sphinxAtStartPar -Receiving option information (supplied by \sphinxcode{\sphinxupquote{kinit \sphinxhyphen{}X}} or by an -application), with the \sphinxstylestrong{gic\_opts} method. - -\end{itemize} - -\sphinxAtStartPar -A clpreauth module can create and destroy per\sphinxhyphen{}library\sphinxhyphen{}context and -per\sphinxhyphen{}request state objects by implementing the \sphinxstylestrong{init}, \sphinxstylestrong{fini}, -\sphinxstylestrong{request\_init}, and \sphinxstylestrong{request\_fini} methods. Per\sphinxhyphen{}context state -objects have the type krb5\_clpreauth\_moddata, and per\sphinxhyphen{}request state -objects have the type krb5\_clpreauth\_modreq. These are abstract -pointer types; a module should typically cast these to internal -types for the state objects. - -\sphinxAtStartPar -The \sphinxstylestrong{process} and \sphinxstylestrong{tryagain} methods have access to a callback -function and handle (called a “rock”) which can be used to get -additional information about the current request, including the -expected enctype of the AS reply, the FAST armor key, and the client -long\sphinxhyphen{}term key (prompting for the user password if necessary). A -callback can also be used to replace the AS reply key if the -preauthentication mechanism computes one. - - -\section{KDC preauthentication interface (kdcpreauth)} -\label{\detokenize{plugindev/kdcpreauth:kdc-preauthentication-interface-kdcpreauth}}\label{\detokenize{plugindev/kdcpreauth::doc}} -\sphinxAtStartPar -The kdcpreauth interface allows the addition of KDC support for -preauthentication mechanisms beyond those included in the core MIT -krb5 code base. For a detailed description of the kdcpreauth -interface, see the header file \sphinxcode{\sphinxupquote{\textless{}krb5/kdcpreauth\_plugin.h\textgreater{}}} (or -\sphinxcode{\sphinxupquote{\textless{}krb5/preauth\_plugin.h\textgreater{}}} before release 1.12). - -\sphinxAtStartPar -A kdcpreauth module is generally responsible for: -\begin{itemize} -\item {} -\sphinxAtStartPar -Supplying a list of preauth type numbers used by the module in the -\sphinxstylestrong{pa\_type\_list} field of the vtable structure. - -\item {} -\sphinxAtStartPar -Indicating what kind of preauthentication mechanism it implements, -with the \sphinxstylestrong{flags} method. If the mechanism computes a new reply -key, it must specify the \sphinxcode{\sphinxupquote{PA\_REPLACES\_KEY}} flag. If the mechanism -is generally only used with hardware tokens, the \sphinxcode{\sphinxupquote{PA\_HARDWARE}} -flag allows the mechanism to work with principals which have the -\sphinxstylestrong{requires\_hwauth} flag set. - -\item {} -\sphinxAtStartPar -Producing a padata value to be sent with a preauth\_required error, -with the \sphinxstylestrong{edata} method. - -\item {} -\sphinxAtStartPar -Examining a padata value sent by a client and verifying that it -proves knowledge of the appropriate client credential information. -This is done with the \sphinxstylestrong{verify} method. - -\item {} -\sphinxAtStartPar -Producing a padata response value for the client, and possibly -computing a reply key. This is done with the \sphinxstylestrong{return\_padata} -method. - -\end{itemize} - -\sphinxAtStartPar -A module can create and destroy per\sphinxhyphen{}KDC state objects by implementing -the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. Per\sphinxhyphen{}KDC state objects have the -type krb5\_kdcpreauth\_moddata, which is an abstract pointer types. A -module should typically cast this to an internal type for the state -object. - -\sphinxAtStartPar -A module can create a per\sphinxhyphen{}request state object by returning one in the -\sphinxstylestrong{verify} method, receiving it in the \sphinxstylestrong{return\_padata} method, and -destroying it in the \sphinxstylestrong{free\_modreq} method. Note that these state -objects only apply to the processing of a single AS request packet, -not to an entire authentication exchange (since an authentication -exchange may remain unfinished by the client or may involve multiple -different KDC hosts). Per\sphinxhyphen{}request state objects have the type -krb5\_kdcpreauth\_modreq, which is an abstract pointer type. - -\sphinxAtStartPar -The \sphinxstylestrong{edata}, \sphinxstylestrong{verify}, and \sphinxstylestrong{return\_padata} methods have access -to a callback function and handle (called a “rock”) which can be used -to get additional information about the current request, including the -maximum allowable clock skew, the client’s long\sphinxhyphen{}term keys, the -DER\sphinxhyphen{}encoded request body, the FAST armor key, string attributes on the -client’s database entry, and the client’s database entry itself. The -\sphinxstylestrong{verify} method can assert one or more authentication indicators to -be included in the issued ticket using the \sphinxcode{\sphinxupquote{add\_auth\_indicator}} -callback (new in release 1.14). - -\sphinxAtStartPar -A module can generate state information to be included with the next -client request using the \sphinxcode{\sphinxupquote{set\_cookie}} callback (new in release -1.14). On the next request, the module can read this state -information using the \sphinxcode{\sphinxupquote{get\_cookie}} callback. Cookie information is -encrypted, timestamped, and transmitted to the client in a -\sphinxcode{\sphinxupquote{PA\sphinxhyphen{}FX\sphinxhyphen{}COOKIE}} pa\sphinxhyphen{}data item. Older clients may not support cookies -and therefore may not transmit the cookie in the next request; in this -case, \sphinxcode{\sphinxupquote{get\_cookie}} will not yield the saved information. - -\sphinxAtStartPar -If a module implements a mechanism which requires multiple round -trips, its \sphinxstylestrong{verify} method can respond with the code -\sphinxcode{\sphinxupquote{KRB5KDC\_ERR\_MORE\_PREAUTH\_DATA\_REQUIRED}} and a list of pa\sphinxhyphen{}data in -the \sphinxstyleemphasis{e\_data} parameter to be processed by the client. - -\sphinxAtStartPar -The \sphinxstylestrong{edata} and \sphinxstylestrong{verify} methods can be implemented -asynchronously. Because of this, they do not return values directly -to the caller, but must instead invoke responder functions with their -results. A synchronous implementation can invoke the responder -function immediately. An asynchronous implementation can use the -callback to get an event context for use with the \sphinxhref{https://fedorahosted.org/libverto/}{libverto} API. - - -\section{Credential cache selection interface (ccselect)} -\label{\detokenize{plugindev/ccselect:credential-cache-selection-interface-ccselect}}\label{\detokenize{plugindev/ccselect:ccselect-plugin}}\label{\detokenize{plugindev/ccselect::doc}} -\sphinxAtStartPar -The ccselect interface allows modules to control how credential caches -are chosen when a GSSAPI client contacts a service. For a detailed -description of the ccselect interface, see the header file -\sphinxcode{\sphinxupquote{\textless{}krb5/ccselect\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -The primary ccselect method is \sphinxstylestrong{choose}, which accepts a server -principal as input and returns a ccache and/or principal name as -output. A module can use the krb5\_cccol APIs to iterate over the -cache collection in order to find an appropriate ccache to use. - -\sphinxAtStartPar -A module can create and destroy per\sphinxhyphen{}library\sphinxhyphen{}context state objects by -implementing the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. State objects have -the type krb5\_ccselect\_moddata, which is an abstract pointer type. A -module should typically cast this to an internal type for the state -object. - -\sphinxAtStartPar -A module can have one of two priorities, “authoritative” or -“heuristic”. Results from authoritative modules, if any are -available, will take priority over results from heuristic modules. A -module communicates its priority as a result of the \sphinxstylestrong{init} method. - - -\section{Password quality interface (pwqual)} -\label{\detokenize{plugindev/pwqual:password-quality-interface-pwqual}}\label{\detokenize{plugindev/pwqual:pwqual-plugin}}\label{\detokenize{plugindev/pwqual::doc}} -\sphinxAtStartPar -The pwqual interface allows modules to control what passwords are -allowed when a user changes passwords. For a detailed description of -the pwqual interface, see the header file \sphinxcode{\sphinxupquote{\textless{}krb5/pwqual\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -The primary pwqual method is \sphinxstylestrong{check}, which receives a password as -input and returns success (0) or a \sphinxcode{\sphinxupquote{KADM5\_PASS\_Q\_}} failure code -depending on whether the password is allowed. The \sphinxstylestrong{check} method -also receives the principal name and the name of the principal’s -password policy as input; although there is no stable interface for -the module to obtain the fields of the password policy, it can define -its own configuration or data store based on the policy name. - -\sphinxAtStartPar -A module can create and destroy per\sphinxhyphen{}process state objects by -implementing the \sphinxstylestrong{open} and \sphinxstylestrong{close} methods. State objects have -the type krb5\_pwqual\_moddata, which is an abstract pointer type. A -module should typically cast this to an internal type for the state -object. The \sphinxstylestrong{open} method also receives the name of the realm’s -dictionary file (as configured by the \sphinxstylestrong{dict\_file} variable in the -\DUrole{xref,std,std-ref}{kdc\_realms} section of \DUrole{xref,std,std-ref}{kdc.conf(5)}) if it wishes to use -it. - - -\section{KADM5 hook interface (kadm5\_hook)} -\label{\detokenize{plugindev/kadm5_hook:kadm5-hook-interface-kadm5-hook}}\label{\detokenize{plugindev/kadm5_hook:kadm5-hook-plugin}}\label{\detokenize{plugindev/kadm5_hook::doc}} -\sphinxAtStartPar -The kadm5\_hook interface allows modules to perform actions when -changes are made to the Kerberos database through \DUrole{xref,std,std-ref}{kadmin(1)}. -For a detailed description of the kadm5\_hook interface, see the header -file \sphinxcode{\sphinxupquote{\textless{}krb5/kadm5\_hook\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -The kadm5\_hook interface has five primary methods: \sphinxstylestrong{chpass}, -\sphinxstylestrong{create}, \sphinxstylestrong{modify}, \sphinxstylestrong{remove}, and \sphinxstylestrong{rename}. (The \sphinxstylestrong{rename} -method was introduced in release 1.14.) Each of these methods is -called twice when the corresponding administrative action takes place, -once before the action is committed and once afterwards. A module can -prevent the action from taking place by returning an error code during -the pre\sphinxhyphen{}commit stage. - -\sphinxAtStartPar -A module can create and destroy per\sphinxhyphen{}process state objects by -implementing the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. State objects have -the type kadm5\_hook\_modinfo, which is an abstract pointer type. A -module should typically cast this to an internal type for the state -object. - -\sphinxAtStartPar -Because the kadm5\_hook interface is tied closely to the kadmin -interface (which is explicitly unstable), it may not remain as stable -across versions as other public pluggable interfaces. - - -\section{kadmin authorization interface (kadm5\_auth)} -\label{\detokenize{plugindev/kadm5_auth:kadmin-authorization-interface-kadm5-auth}}\label{\detokenize{plugindev/kadm5_auth:kadm5-auth-plugin}}\label{\detokenize{plugindev/kadm5_auth::doc}} -\sphinxAtStartPar -The kadm5\_auth interface (new in release 1.16) allows modules to -determine whether a client principal is authorized to perform an -operation in the kadmin protocol, and to apply restrictions to -principal operations. For a detailed description of the kadm5\_auth -interface, see the header file \sphinxcode{\sphinxupquote{\textless{}krb5/kadm5\_auth\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -A module can create and destroy per\sphinxhyphen{}process state objects by -implementing the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. State objects have -the type kadm5\_auth\_modinfo, which is an abstract pointer type. A -module should typically cast this to an internal type for the state -object. - -\sphinxAtStartPar -The kadm5\_auth interface has one method for each kadmin operation, -with parameters specific to the operation. Each method can return -either 0 to authorize access, KRB5\_PLUGIN\_NO\_HANDLE to defer the -decision to other modules, or another error (canonically EPERM) to -authoritatively deny access. Access is granted if at least one module -grants access and no module authoritatively denies access. - -\sphinxAtStartPar -The \sphinxstylestrong{addprinc} and \sphinxstylestrong{modprinc} methods can also impose restrictions -on the principal operation by returning a \sphinxcode{\sphinxupquote{struct -kadm5\_auth\_restrictions}} object. The module should also implement -the \sphinxstylestrong{free\_restrictions} method if it dynamically allocates -restrictions objects for principal operations. - -\sphinxAtStartPar -kadm5\_auth modules can optionally inspect principal or policy objects. -To do this, the module must also include \sphinxcode{\sphinxupquote{\textless{}kadm5/admin.h\textgreater{}}} to gain -access to the structure definitions for those objects. As the kadmin -interface is explicitly not as stable as other public interfaces, -modules which do this may not retain compatibility across releases. - - -\section{Host\sphinxhyphen{}to\sphinxhyphen{}realm interface (hostrealm)} -\label{\detokenize{plugindev/hostrealm:host-to-realm-interface-hostrealm}}\label{\detokenize{plugindev/hostrealm:hostrealm-plugin}}\label{\detokenize{plugindev/hostrealm::doc}} -\sphinxAtStartPar -The host\sphinxhyphen{}to\sphinxhyphen{}realm interface was first introduced in release 1.12. It -allows modules to control the local mapping of hostnames to realm -names as well as the default realm. For a detailed description of the -hostrealm interface, see the header file -\sphinxcode{\sphinxupquote{\textless{}krb5/hostrealm\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -Although the mapping methods in the hostrealm interface return a list -of one or more realms, only the first realm in the list is currently -used by callers. Callers may begin using later responses in the -future. - -\sphinxAtStartPar -Any mapping method may return KRB5\_PLUGIN\_NO\_HANDLE to defer -processing to a later module. - -\sphinxAtStartPar -A module can create and destroy per\sphinxhyphen{}library\sphinxhyphen{}context state objects -using the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. If the module does not need -any state, it does not need to implement these methods. - -\sphinxAtStartPar -The optional \sphinxstylestrong{host\_realm} method allows a module to determine -authoritative realm mappings for a hostname. The first authoritative -mapping is used in preference to KDC referrals when getting service -credentials. - -\sphinxAtStartPar -The optional \sphinxstylestrong{fallback\_realm} method allows a module to determine -fallback mappings for a hostname. The first fallback mapping is tried -if there is no authoritative mapping for a realm, and KDC referrals -failed to produce a successful result. - -\sphinxAtStartPar -The optional \sphinxstylestrong{default\_realm} method allows a module to determine the -local default realm. - -\sphinxAtStartPar -If a module implements any of the above methods, it must also -implement \sphinxstylestrong{free\_list} to ensure that memory is allocated and -deallocated consistently. - - -\section{Local authorization interface (localauth)} -\label{\detokenize{plugindev/localauth:local-authorization-interface-localauth}}\label{\detokenize{plugindev/localauth:localauth-plugin}}\label{\detokenize{plugindev/localauth::doc}} -\sphinxAtStartPar -The localauth interface was first introduced in release 1.12. It -allows modules to control the relationship between Kerberos principals -and local system accounts. When an application calls -\sphinxcode{\sphinxupquote{krb5\_kuserok()}} or \sphinxcode{\sphinxupquote{krb5\_aname\_to\_localname()}}, localauth -modules are consulted to determine the result. For a detailed -description of the localauth interface, see the header file -\sphinxcode{\sphinxupquote{\textless{}krb5/localauth\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -A module can create and destroy per\sphinxhyphen{}library\sphinxhyphen{}context state objects -using the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. If the module does not need -any state, it does not need to implement these methods. - -\sphinxAtStartPar -The optional \sphinxstylestrong{userok} method allows a module to control the behavior -of \sphinxcode{\sphinxupquote{krb5\_kuserok()}}. The module receives the authenticated name -and the local account name as inputs, and can return either 0 to -authorize access, KRB5\_PLUGIN\_NO\_HANDLE to defer the decision to other -modules, or another error (canonically EPERM) to authoritatively deny -access. Access is granted if at least one module grants access and no -module authoritatively denies access. - -\sphinxAtStartPar -The optional \sphinxstylestrong{an2ln} method can work in two different ways. If the -module sets an array of uppercase type names in \sphinxstylestrong{an2ln\_types}, then -the module’s \sphinxstylestrong{an2ln} method will only be invoked by -\sphinxcode{\sphinxupquote{krb5\_aname\_to\_localname()}} if an \sphinxstylestrong{auth\_to\_local} value in -\DUrole{xref,std,std-ref}{krb5.conf(5)} refers to one of the module’s types. In this -case, the \sphinxstyleemphasis{type} and \sphinxstyleemphasis{residual} arguments will give the type name and -residual string of the \sphinxstylestrong{auth\_to\_local} value. - -\sphinxAtStartPar -If the module does not set \sphinxstylestrong{an2ln\_types} but does implement -\sphinxstylestrong{an2ln}, the module’s \sphinxstylestrong{an2ln} method will be invoked for all -\sphinxcode{\sphinxupquote{krb5\_aname\_to\_localname()}} operations unless an earlier module -determines a mapping, with \sphinxstyleemphasis{type} and \sphinxstyleemphasis{residual} set to NULL. The -module can return KRB5\_LNAME\_NO\_TRANS to defer mapping to later -modules. - -\sphinxAtStartPar -If a module implements \sphinxstylestrong{an2ln}, it must also implement -\sphinxstylestrong{free\_string} to ensure that memory is allocated and deallocated -consistently. - - -\section{Server location interface (locate)} -\label{\detokenize{plugindev/locate:server-location-interface-locate}}\label{\detokenize{plugindev/locate::doc}} -\sphinxAtStartPar -The locate interface allows modules to control how KDCs and similar -services are located by clients. For a detailed description of the -ccselect interface, see the header file \sphinxcode{\sphinxupquote{\textless{}krb5/locate\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -A locate module exports a structure object of type -krb5plugin\_service\_locate\_ftable, with the name \sphinxcode{\sphinxupquote{service\_locator}}. -The structure contains a minor version and pointers to the module’s -methods. - -\sphinxAtStartPar -The primary locate method is \sphinxstylestrong{lookup}, which accepts a service type, -realm name, desired socket type, and desired address family (which -will be AF\_UNSPEC if no specific address family is desired). The -method should invoke the callback function once for each server -address it wants to return, passing a socket type (SOCK\_STREAM for TCP -or SOCK\_DGRAM for UDP) and socket address. The \sphinxstylestrong{lookup} method -should return 0 if it has authoritatively determined the server -addresses for the realm, KRB5\_PLUGIN\_NO\_HANDLE if it wants to let -other location mechanisms determine the server addresses, or another -code if it experienced a failure which should abort the location -process. - -\sphinxAtStartPar -A module can create and destroy per\sphinxhyphen{}library\sphinxhyphen{}context state objects by -implementing the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. State objects have -the type void *, and should be cast to an internal type for the state -object. - - -\section{Configuration interface (profile)} -\label{\detokenize{plugindev/profile:configuration-interface-profile}}\label{\detokenize{plugindev/profile:profile-plugin}}\label{\detokenize{plugindev/profile::doc}} -\sphinxAtStartPar -The profile interface allows a module to control how krb5 -configuration information is obtained by the Kerberos library and -applications. For a detailed description of the profile interface, -see the header file \sphinxcode{\sphinxupquote{\textless{}profile.h\textgreater{}}}. - -\begin{sphinxadmonition}{note}{Note:} -\sphinxAtStartPar -The profile interface does not follow the normal conventions -for MIT krb5 pluggable interfaces, because it is part of a -lower\sphinxhyphen{}level component of the krb5 library. -\end{sphinxadmonition} - -\sphinxAtStartPar -As with other types of plugin modules, a profile module is a Unix -shared object or Windows DLL, built separately from the krb5 tree. -The krb5 library will dynamically load and use a profile plugin module -if it reads a \sphinxcode{\sphinxupquote{module}} directive at the beginning of krb5.conf, as -described in \DUrole{xref,std,std-ref}{profile\_plugin\_config}. - -\sphinxAtStartPar -A profile module exports a function named \sphinxcode{\sphinxupquote{profile\_module\_init}} -matching the signature of the profile\_module\_init\_fn type. This -function accepts a residual string, which may be used to help locate -the configuration source. The function fills in a vtable and may also -create a per\sphinxhyphen{}profile state object. If the module uses state objects, -it should implement the \sphinxstylestrong{copy} and \sphinxstylestrong{cleanup} methods to manage -them. - -\sphinxAtStartPar -A basic read\sphinxhyphen{}only profile module need only implement the -\sphinxstylestrong{get\_values} and \sphinxstylestrong{free\_values} methods. The \sphinxstylestrong{get\_values} method -accepts a null\sphinxhyphen{}terminated list of C string names (e.g., an array -containing “libdefaults”, “clockskew”, and NULL for the \sphinxstylestrong{clockskew} -variable in the \DUrole{xref,std,std-ref}{libdefaults} section) and returns a -null\sphinxhyphen{}terminated list of values, which will be cleaned up with the -\sphinxstylestrong{free\_values} method when the caller is done with them. - -\sphinxAtStartPar -Iterable profile modules must also define the \sphinxstylestrong{iterator\_create}, -\sphinxstylestrong{iterator}, \sphinxstylestrong{iterator\_free}, and \sphinxstylestrong{free\_string} methods. The -core krb5 code does not require profiles to be iterable, but some -applications may iterate over the krb5 profile object in order to -present configuration interfaces. - -\sphinxAtStartPar -Writable profile modules must also define the \sphinxstylestrong{writable}, -\sphinxstylestrong{modified}, \sphinxstylestrong{update\_relation}, \sphinxstylestrong{rename\_section}, -\sphinxstylestrong{add\_relation}, and \sphinxstylestrong{flush} methods. The core krb5 code does not -require profiles to be writable, but some applications may write to -the krb5 profile in order to present configuration interfaces. - -\sphinxAtStartPar -The following is an example of a very basic read\sphinxhyphen{}only profile module -which returns a hardcoded value for the \sphinxstylestrong{default\_realm} variable in -\DUrole{xref,std,std-ref}{libdefaults}, and provides no other configuration information. -(For conciseness, the example omits code for checking the return -values of malloc and strdup.) - -\begin{sphinxVerbatim}[commandchars=\\\{\}] -\PYG{c+c1}{\PYGZsh{}include \PYGZlt{}stdlib.h\PYGZgt{}} -\PYG{c+c1}{\PYGZsh{}include \PYGZlt{}string.h\PYGZgt{}} -\PYG{c+c1}{\PYGZsh{}include \PYGZlt{}profile.h\PYGZgt{}} - -\PYG{n}{static} \PYG{n}{long} -\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}{)} -\PYG{p}{\PYGZob{}} - \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{}} - \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{}} - \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}{;} - \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}{;} - \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}{;} - \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;} - \PYG{p}{\PYGZcb{}} - \PYG{k}{return} \PYG{n}{PROF\PYGZus{}NO\PYGZus{}RELATION}\PYG{p}{;} -\PYG{p}{\PYGZcb{}} - -\PYG{n}{static} \PYG{n}{void} -\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}{)} -\PYG{p}{\PYGZob{}} - \PYG{n}{char} \PYG{o}{*}\PYG{o}{*}\PYG{n}{v}\PYG{p}{;} - - \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}{)} - \PYG{n}{free}\PYG{p}{(}\PYG{o}{*}\PYG{n}{v}\PYG{p}{)}\PYG{p}{;} - \PYG{n}{free}\PYG{p}{(}\PYG{n}{values}\PYG{p}{)}\PYG{p}{;} -\PYG{p}{\PYGZcb{}} - -\PYG{n}{long} -\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}{,} - \PYG{n}{void} \PYG{o}{*}\PYG{o}{*}\PYG{n}{cb\PYGZus{}ret}\PYG{p}{)}\PYG{p}{;} - -\PYG{n}{long} -\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}{,} - \PYG{n}{void} \PYG{o}{*}\PYG{o}{*}\PYG{n}{cb\PYGZus{}ret}\PYG{p}{)} -\PYG{p}{\PYGZob{}} - \PYG{o}{*}\PYG{n}{cb\PYGZus{}ret} \PYG{o}{=} \PYG{n}{NULL}\PYG{p}{;} - \PYG{n}{vtable}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{get\PYGZus{}values} \PYG{o}{=} \PYG{n}{get\PYGZus{}values}\PYG{p}{;} - \PYG{n}{vtable}\PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZgt{}}\PYG{n}{free\PYGZus{}values} \PYG{o}{=} \PYG{n}{free\PYGZus{}values}\PYG{p}{;} - \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;} -\PYG{p}{\PYGZcb{}} -\end{sphinxVerbatim} - - -\section{GSSAPI mechanism interface} -\label{\detokenize{plugindev/gssapi:gssapi-mechanism-interface}}\label{\detokenize{plugindev/gssapi::doc}} -\sphinxAtStartPar -The GSSAPI library in MIT krb5 can load mechanism modules to augment -the set of built\sphinxhyphen{}in mechanisms. - -\sphinxAtStartPar -A mechanism module is a Unix shared object or Windows DLL, built -separately from the krb5 tree. Modules are loaded according to the -GSS mechanism config files described in \DUrole{xref,std,std-ref}{gssapi\_plugin\_config}. - -\sphinxAtStartPar -For the most part, a GSSAPI mechanism module exports the same -functions as would a GSSAPI implementation itself, with the same -function signatures. The mechanism selection layer within the GSSAPI -library (called the “mechglue”) will dispatch calls from the -application to the module if the module’s mechanism is requested. If -a module does not wish to implement a GSSAPI extension, it can simply -refrain from exporting it, and the mechglue will fail gracefully if -the application calls that function. - -\sphinxAtStartPar -The mechglue does not invoke a module’s \sphinxstylestrong{gss\_add\_cred}, -\sphinxstylestrong{gss\_add\_cred\_from}, \sphinxstylestrong{gss\_add\_cred\_impersonate\_name}, or -\sphinxstylestrong{gss\_add\_cred\_with\_password} function. A mechanism only needs to -implement the “acquire” variants of those functions. - -\sphinxAtStartPar -A module does not need to coordinate its minor status codes with those -of other mechanisms. If the mechglue detects conflicts, it will map -the mechanism’s status codes onto unique values, and then map them -back again when \sphinxstylestrong{gss\_display\_status} is called. - - -\subsection{NegoEx modules} -\label{\detokenize{plugindev/gssapi:negoex-modules}} -\sphinxAtStartPar -Some Windows GSSAPI mechanisms can only be negotiated via a Microsoft -extension to SPNEGO called NegoEx. Beginning with release 1.18, -mechanism modules can support NegoEx as follows: -\begin{itemize} -\item {} -\sphinxAtStartPar -Implement the gssspi\_query\_meta\_data(), gssspi\_exchange\_meta\_data(), -and gssspi\_query\_mechanism\_info() SPIs declared in -\sphinxcode{\sphinxupquote{\textless{}gssapi/gssapi\_ext.h\textgreater{}}}. - -\item {} -\sphinxAtStartPar -Implement gss\_inquire\_sec\_context\_by\_oid() and answer the -\sphinxstylestrong{GSS\_C\_INQ\_NEGOEX\_KEY} and \sphinxstylestrong{GSS\_C\_INQ\_NEGOEX\_VERIFY\_KEY} OIDs -to provide the checksum keys for outgoing and incoming checksums, -respectively. The answer must be in two buffers: the first buffer -contains the key contents, and the second buffer contains the key -encryption type as a four\sphinxhyphen{}byte little\sphinxhyphen{}endian integer. - -\end{itemize} - -\sphinxAtStartPar -By default, NegoEx mechanisms will not be directly negotiated via -SPNEGO. If direct SPNEGO negotiation is required for -interoperability, implement gss\_inquire\_attrs\_for\_mech() and assert -the GSS\_C\_MA\_NEGOEX\_AND\_SPNEGO attribute (along with any applicable -RFC 5587 attributes). - - -\subsection{Interposer modules} -\label{\detokenize{plugindev/gssapi:interposer-modules}} -\sphinxAtStartPar -The mechglue also supports a kind of loadable module, called an -interposer module, which intercepts calls to existing mechanisms -rather than implementing a new mechanism. - -\sphinxAtStartPar -An interposer module must export the symbol \sphinxstylestrong{gss\_mech\_interposer} -with the following signature: - -\begin{sphinxVerbatim}[commandchars=\\\{\}] -\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}{;} -\end{sphinxVerbatim} - -\sphinxAtStartPar -This function is invoked with the OID of the interposer mechanism as -specified in the mechanism config file, and returns a set of mechanism -OIDs to be interposed. The returned OID set must have been created -using the mechglue’s gss\_create\_empty\_oid\_set and -gss\_add\_oid\_set\_member functions. - -\sphinxAtStartPar -An interposer module must use the prefix \sphinxcode{\sphinxupquote{gssi\_}} for the GSSAPI -functions it exports, instead of the prefix \sphinxcode{\sphinxupquote{gss\_}}. In most cases, -unexported \sphinxcode{\sphinxupquote{gssi\_}} functions will result in failure from their -corresponding \sphinxcode{\sphinxupquote{gss\_}} calls. - -\sphinxAtStartPar -An interposer module can link against the GSSAPI library in order to -make calls to the original mechanism. To do so, it must specify a -special mechanism OID which is the concatention of the interposer’s -own OID byte string and the original mechanism’s OID byte string. - -\sphinxAtStartPar -Functions that do not accept a mechanism argument directly require no -special handling, with the following exceptions: - -\sphinxAtStartPar -Since \sphinxstylestrong{gss\_accept\_sec\_context} does not accept a mechanism argument, -an interposer mechanism must, in order to invoke the original -mechanism’s function, acquire a credential for the concatenated OID -and pass that as the \sphinxstyleemphasis{verifier\_cred\_handle} parameter. - -\sphinxAtStartPar -Since \sphinxstylestrong{gss\_import\_name}, \sphinxstylestrong{gss\_import\_cred}, and -\sphinxstylestrong{gss\_import\_sec\_context} do not accept mechanism parameters, the SPI -has been extended to include variants which do. This allows the -interposer module to know which mechanism should be used to interpret -the token. These functions have the following signatures: - -\begin{sphinxVerbatim}[commandchars=\\\{\}] -\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}{,} - \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}{,} - \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{o}{*}\PYG{n}{context\PYGZus{}handle}\PYG{p}{)}\PYG{p}{;} - -\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}{,} - \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}{,} - \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}{;} - -\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}{,} - \PYG{n}{gss\PYGZus{}OID} \PYG{n}{mech\PYGZus{}type}\PYG{p}{,} \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{token}\PYG{p}{,} - \PYG{n}{gss\PYGZus{}cred\PYGZus{}id\PYGZus{}t} \PYG{o}{*}\PYG{n}{cred\PYGZus{}handle}\PYG{p}{)}\PYG{p}{;} -\end{sphinxVerbatim} - -\sphinxAtStartPar -To re\sphinxhyphen{}enter the original mechanism when importing tokens for the above -functions, the interposer module must wrap the mechanism token in the -mechglue’s format, using the concatenated OID (except in -\sphinxstylestrong{gss\_import\_name}). The mechglue token formats are: -\begin{itemize} -\item {} -\sphinxAtStartPar -For \sphinxstylestrong{gss\_import\_sec\_context}, a four\sphinxhyphen{}byte OID length in big\sphinxhyphen{}endian -order, followed by the concatenated OID, followed by the mechanism -token. - -\item {} -\sphinxAtStartPar -For \sphinxstylestrong{gss\_import\_name}, the bytes 04 01, followed by a two\sphinxhyphen{}byte OID -length in big\sphinxhyphen{}endian order, followed by the mechanism OID, followed -by a four\sphinxhyphen{}byte token length in big\sphinxhyphen{}endian order, followed by the -mechanism token. Unlike most uses of OIDs in the API, the mechanism -OID encoding must include the DER tag and length for an object -identifier (06 followed by the DER length of the OID byte string), -and this prefix must be included in the two\sphinxhyphen{}byte OID length. -input\_name\_type must also be set to GSS\_C\_NT\_EXPORT\_NAME. - -\item {} -\sphinxAtStartPar -For \sphinxstylestrong{gss\_import\_cred}, a four\sphinxhyphen{}byte OID length in big\sphinxhyphen{}endian order, -followed by the concatenated OID, followed by a four\sphinxhyphen{}byte token -length in big\sphinxhyphen{}endian order, followed by the mechanism token. This -sequence may be repeated multiple times. - -\end{itemize} - - -\section{Internal pluggable interfaces} -\label{\detokenize{plugindev/internal:internal-pluggable-interfaces}}\label{\detokenize{plugindev/internal::doc}} -\sphinxAtStartPar -Following are brief discussions of pluggable interfaces which have not -yet been made public. These interfaces are functional, but the -interfaces are likely to change in incompatible ways from release to -release. In some cases, it may be necessary to copy header files from -the krb5 source tree to use an internal interface. Use these with -care, and expect to need to update your modules for each new release -of MIT krb5. - - -\subsection{Kerberos database interface (KDB)} -\label{\detokenize{plugindev/internal:kerberos-database-interface-kdb}} -\sphinxAtStartPar -A KDB module implements a database back end for KDC principal and -policy information, and can also control many aspects of KDC behavior. -For a full description of the interface, see the header file -\sphinxcode{\sphinxupquote{\textless{}kdb.h\textgreater{}}}. - -\sphinxAtStartPar -The KDB pluggable interface is often referred to as the DAL (Database -Access Layer). - - -\subsection{Authorization data interface (authdata)} -\label{\detokenize{plugindev/internal:authorization-data-interface-authdata}} -\sphinxAtStartPar -The authdata interface allows a module to provide (from the KDC) or -consume (in application servers) authorization data of types beyond -those handled by the core MIT krb5 code base. The interface is -defined in the header file \sphinxcode{\sphinxupquote{\textless{}krb5/authdata\_plugin.h\textgreater{}}}, which is not -installed by the build. - - -\section{PKINIT certificate authorization interface (certauth)} -\label{\detokenize{plugindev/certauth:pkinit-certificate-authorization-interface-certauth}}\label{\detokenize{plugindev/certauth:certauth-plugin}}\label{\detokenize{plugindev/certauth::doc}} -\sphinxAtStartPar -The certauth interface was first introduced in release 1.16. It -allows customization of the X.509 certificate attribute requirements -placed on certificates used by PKINIT enabled clients. For a detailed -description of the certauth interface, see the header file -\sphinxcode{\sphinxupquote{\textless{}krb5/certauth\_plugin.h\textgreater{}}} - -\sphinxAtStartPar -A certauth module implements the \sphinxstylestrong{authorize} method to determine -whether a client’s certificate is authorized to authenticate a client -principal. \sphinxstylestrong{authorize} receives the DER\sphinxhyphen{}encoded certificate, the -requested client principal, and a pointer to the client’s -krb5\_db\_entry (for modules that link against libkdb5). The method -must decode the certificate and inspect its attributes to determine if -it should authorize PKINIT authentication. It returns the -authorization status and optionally outputs a list of authentication -indicator strings to be added to the ticket. - -\sphinxAtStartPar -Beginning in release 1.19, the authorize method can request that the -hardware authentication bit be set in the ticket by returning -\sphinxstylestrong{KRB5\_CERTAUTH\_HWAUTH}. Beginning in release 1.20, the authorize -method can return \sphinxstylestrong{KRB5\_CERTAUTH\_HWAUTH\_PASS} to request that the -hardware authentication bit be set in the ticket but otherwise defer -authorization to another certauth module. A module must use its own -internal or library\sphinxhyphen{}provided ASN.1 certificate decoder. - -\sphinxAtStartPar -A module can optionally create and destroy module data with the -\sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. Module data objects last for the -lifetime of the KDC process. - -\sphinxAtStartPar -If a module allocates and returns a list of authentication indicators -from \sphinxstylestrong{authorize}, it must also implement the \sphinxstylestrong{free\_ind} method -to free the list. - - -\section{KDC policy interface (kdcpolicy)} -\label{\detokenize{plugindev/kdcpolicy:kdc-policy-interface-kdcpolicy}}\label{\detokenize{plugindev/kdcpolicy:kdcpolicy-plugin}}\label{\detokenize{plugindev/kdcpolicy::doc}} -\sphinxAtStartPar -The kdcpolicy interface was first introduced in release 1.16. It -allows modules to veto otherwise valid AS and TGS requests or restrict -the lifetime and renew time of the resulting ticket. For a detailed -description of the kdcpolicy interface, see the header file -\sphinxcode{\sphinxupquote{\textless{}krb5/kdcpolicy\_plugin.h\textgreater{}}}. - -\sphinxAtStartPar -The optional \sphinxstylestrong{check\_as} and \sphinxstylestrong{check\_tgs} functions allow the module -to perform access control. Additionally, a module can create and -destroy module data with the \sphinxstylestrong{init} and \sphinxstylestrong{fini} methods. Module -data objects last for the lifetime of the KDC process, and are -provided to all other methods. The data has the type -krb5\_kdcpolicy\_moddata, which should be cast to the appropriate -internal type. - -\sphinxAtStartPar -kdcpolicy modules can optionally inspect principal entries. To do -this, the module must also include \sphinxcode{\sphinxupquote{\textless{}kdb.h\textgreater{}}} to gain access to the -principal entry structure definition. As the KDB interface is -explicitly not as stable as other public interfaces, modules which do -this may not retain compatibility across releases. - - - -\renewcommand{\indexname}{Index} -\printindex -\end{document}
\ No newline at end of file |