"Fossies" - the Fresh Open Source Software Archive

Member "krb5-1.18/doc/pdf/appdev.tex" (12 Feb 2020, 1249182 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}{0}
   53 
   54 
   55 
   56 \title{Kerberos Application 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{appdev/index::doc}}
   69 
   70 
   71 
   72 \chapter{Developing with GSSAPI}
   73 \label{\detokenize{appdev/gssapi:for-application-developers}}\label{\detokenize{appdev/gssapi::doc}}\label{\detokenize{appdev/gssapi:developing-with-gssapi}}
   74 The GSSAPI (Generic Security Services API) allows applications to
   75 communicate securely using Kerberos 5 or other security mechanisms.
   76 We recommend using the GSSAPI (or a higher-level framework which
   77 encompasses GSSAPI, such as SASL) for secure network communication
   78 over using the libkrb5 API directly.
   79 
   80 GSSAPIv2 is specified in \index{RFC!RFC 2743}\sphinxhref{https://tools.ietf.org/html/rfc2743.html}{\sphinxstylestrong{RFC 2743}} and \index{RFC!RFC 2744}\sphinxhref{https://tools.ietf.org/html/rfc2744.html}{\sphinxstylestrong{RFC 2744}}.  Also see
   81 \index{RFC!RFC 7546}\sphinxhref{https://tools.ietf.org/html/rfc7546.html}{\sphinxstylestrong{RFC 7546}} for a description of how to use the GSSAPI in a client or
   82 server program.
   83 
   84 This documentation will describe how various ways of using the
   85 GSSAPI will behave with the krb5 mechanism as implemented in MIT krb5,
   86 as well as krb5-specific extensions to the GSSAPI.
   87 
   88 
   89 \section{Name types}
   90 \label{\detokenize{appdev/gssapi:name-types}}
   91 A GSSAPI application can name a local or remote entity by calling
   92 \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.16}{gss\_import\_name}, specifying a name type and a value.  The following
   93 name types are supported by the krb5 mechanism:
   94 \begin{itemize}
   95 \item {} 
   96 \sphinxstylestrong{GSS\_C\_NT\_HOSTBASED\_SERVICE}: The value should be a string of the
   97 form \sphinxcode{service} or \sphinxcode{service@hostname}.  This is the most common
   98 way to name target services when initiating a security context, and
   99 is the most likely name type to work across multiple mechanisms.
  100 
  101 \item {} 
  102 \sphinxstylestrong{GSS\_KRB5\_NT\_PRINCIPAL\_NAME}: The value should be a principal name
  103 string.  This name type only works with the krb5 mechanism, and is
  104 defined in the \sphinxcode{\textless{}gssapi/gssapi\_krb5.h\textgreater{}} header.
  105 
  106 \item {} 
  107 \sphinxstylestrong{GSS\_C\_NT\_USER\_NAME} or \sphinxstylestrong{GSS\_C\_NULL\_OID}: The value is treated
  108 as an unparsed principal name string, as above.  These name types
  109 may work with mechanisms other than krb5, but will have different
  110 interpretations in those mechanisms.  \sphinxstylestrong{GSS\_C\_NT\_USER\_NAME} is
  111 intended to be used with a local username, which will parse into a
  112 single-component principal in the default realm.
  113 
  114 \item {} 
  115 \sphinxstylestrong{GSS\_C\_NT\_ANONYMOUS}: The value is ignored.  The anonymous
  116 principal is used, allowing a client to authenticate to a server
  117 without asserting a particular identity (which may or may not be
  118 allowed by a particular server or Kerberos realm).
  119 
  120 \item {} 
  121 \sphinxstylestrong{GSS\_C\_NT\_MACHINE\_UID\_NAME}: The value is uid\_t object.  On
  122 Unix-like systems, the username of the uid is looked up in the
  123 system user database and the resulting username is parsed as a
  124 principal name.
  125 
  126 \item {} 
  127 \sphinxstylestrong{GSS\_C\_NT\_STRING\_UID\_NAME}: As above, but the value is a decimal
  128 string representation of the uid.
  129 
  130 \item {} 
  131 \sphinxstylestrong{GSS\_C\_NT\_EXPORT\_NAME}: The value must be the result of a
  132 \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.13}{gss\_export\_name} call.
  133 
  134 \item {} 
  135 \sphinxstylestrong{GSS\_KRB5\_NT\_ENTERPRISE\_NAME}: The value should be a krb5
  136 enterprise name string (see \index{RFC!RFC 6806}\sphinxhref{https://tools.ietf.org/html/rfc6806.html}{\sphinxstylestrong{RFC 6806}} section 5), in the form
  137 \sphinxcode{user@suffix}.  This name type is used to convey alias names, and
  138 is defined in the \sphinxcode{\textless{}gssapi/gssapi\_krb5.h\textgreater{}} header.  (New in
  139 release 1.17.)
  140 
  141 \end{itemize}
  142 
  143 
  144 \section{Initiator credentials}
  145 \label{\detokenize{appdev/gssapi:initiator-credentials}}
  146 A GSSAPI client application uses \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.19}{gss\_init\_sec\_context} to establish a
  147 security context.  The \sphinxstyleemphasis{initiator\_cred\_handle} parameter determines
  148 what tickets are used to establish the connection.  An application can
  149 either pass \sphinxstylestrong{GSS\_C\_NO\_CREDENTIAL} to use the default client
  150 credential, or it can use \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.2}{gss\_acquire\_cred} beforehand to acquire an
  151 initiator credential.  The call to \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.2}{gss\_acquire\_cred} may include a
  152 \sphinxstyleemphasis{desired\_name} parameter, or it may pass \sphinxstylestrong{GSS\_C\_NO\_NAME} if it does
  153 not have a specific name preference.
  154 
  155 If the desired name for a krb5 initiator credential is a host-based
  156 name, it is converted to a principal name of the form
  157 \sphinxcode{service/hostname} in the local realm, where \sphinxstyleemphasis{hostname} is the local
  158 hostname if not specified.  The hostname will be canonicalized using
  159 forward name resolution, and possibly also using reverse name
  160 resolution depending on the value of the \sphinxstylestrong{rdns} variable in
  161 \DUrole{xref,std,std-ref}{libdefaults}.
  162 
  163 If a desired name is specified in the call to \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.2}{gss\_acquire\_cred}, the
  164 krb5 mechanism will attempt to find existing tickets for that client
  165 principal name in the default credential cache or collection.  If the
  166 default cache type does not support a collection, and the default
  167 cache contains credentials for a different principal than the desired
  168 name, a \sphinxstylestrong{GSS\_S\_CRED\_UNAVAIL} error will be returned with a minor
  169 code indicating a mismatch.
  170 
  171 If no existing tickets are available for the desired name, but the
  172 name has an entry in the default client \DUrole{xref,std,std-ref}{keytab\_definition}, the
  173 krb5 mechanism will acquire initial tickets for the name using the
  174 default client keytab.
  175 
  176 If no desired name is specified, credential acquisition will be
  177 deferred until the credential is used in a call to
  178 \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.19}{gss\_init\_sec\_context} or \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.21}{gss\_inquire\_cred}.  If the call is to
  179 \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.19}{gss\_init\_sec\_context}, the target name will be used to choose a client
  180 principal name using the credential cache selection facility.  (This
  181 facility might, for instance, try to choose existing tickets for a
  182 client principal in the same realm as the target service).  If there
  183 are no existing tickets for the chosen principal, but it is present in
  184 the default client keytab, the krb5 mechanism will acquire initial
  185 tickets using the keytab.
  186 
  187 If the target name cannot be used to select a client principal
  188 (because the credentials are used in a call to \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.21}{gss\_inquire\_cred}), or
  189 if the credential cache selection facility cannot choose a principal
  190 for it, the default credential cache will be selected if it exists and
  191 contains tickets.
  192 
  193 If the default credential cache does not exist, but the default client
  194 keytab does, the krb5 mechanism will try to acquire initial tickets
  195 for the first principal in the default client keytab.
  196 
  197 If the krb5 mechanism acquires initial tickets using the default
  198 client keytab, the resulting tickets will be stored in the default
  199 cache or collection, and will be refreshed by future calls to
  200 \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.2}{gss\_acquire\_cred} as they approach their expire time.
  201 
  202 
  203 \section{Acceptor names}
  204 \label{\detokenize{appdev/gssapi:acceptor-names}}
  205 A GSSAPI server application uses \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.1}{gss\_accept\_sec\_context} to establish
  206 a security context based on tokens provided by the client.  The
  207 \sphinxstyleemphasis{acceptor\_cred\_handle} parameter determines what
  208 \DUrole{xref,std,std-ref}{keytab\_definition} entries may be authenticated to by the
  209 client, if the krb5 mechanism is used.
  210 
  211 The simplest choice is to pass \sphinxstylestrong{GSS\_C\_NO\_CREDENTIAL} as the acceptor
  212 credential.  In this case, clients may authenticate to any service
  213 principal in the default keytab (typically \DUrole{xref,std,std-ref}{DEFKTNAME}, or the value of
  214 the \sphinxstylestrong{KRB5\_KTNAME} environment variable).  This is the recommended
  215 approach if the server application has no specific requirements to the
  216 contrary.
  217 
  218 A server may acquire an acceptor credential with \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.2}{gss\_acquire\_cred} and
  219 a \sphinxstyleemphasis{cred\_usage} of \sphinxstylestrong{GSS\_C\_ACCEPT} or \sphinxstylestrong{GSS\_C\_BOTH}.  If the
  220 \sphinxstyleemphasis{desired\_name} parameter is \sphinxstylestrong{GSS\_C\_NO\_NAME}, then clients will be
  221 allowed to authenticate to any service principal in the default
  222 keytab, just as if no acceptor credential was supplied.
  223 
  224 If a server wishes to specify a \sphinxstyleemphasis{desired\_name} to \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.2}{gss\_acquire\_cred},
  225 the most common choice is a host-based name.  If the host-based
  226 \sphinxstyleemphasis{desired\_name} contains just a \sphinxstyleemphasis{service}, then clients will be allowed
  227 to authenticate to any host-based service principal (that is, a
  228 principal of the form \sphinxcode{service/hostname@REALM}) for the named
  229 service, regardless of hostname or realm, as long as it is present in
  230 the default keytab.  If the input name contains both a \sphinxstyleemphasis{service} and a
  231 \sphinxstyleemphasis{hostname}, clients will be allowed to authenticate to any host-based
  232 principal for the named service and hostname, regardless of realm.
  233 
  234 \begin{sphinxadmonition}{note}{Note:}
  235 If a \sphinxstyleemphasis{hostname} is specified, it will be canonicalized
  236 using forward name resolution, and possibly also using
  237 reverse name resolution depending on the value of the
  238 \sphinxstylestrong{rdns} variable in \DUrole{xref,std,std-ref}{libdefaults}.
  239 \end{sphinxadmonition}
  240 
  241 \begin{sphinxadmonition}{note}{Note:}
  242 If the \sphinxstylestrong{ignore\_acceptor\_hostname} variable in
  243 \DUrole{xref,std,std-ref}{libdefaults} is enabled, then \sphinxstyleemphasis{hostname} will be
  244 ignored even if one is specified in the input name.
  245 \end{sphinxadmonition}
  246 
  247 \begin{sphinxadmonition}{note}{Note:}
  248 In MIT krb5 versions prior to 1.10, and in Heimdal’s
  249 implementation of the krb5 mechanism, an input name with
  250 just a \sphinxstyleemphasis{service} is treated like an input name of
  251 \sphinxcode{service@localhostname}, where \sphinxstyleemphasis{localhostname} is the
  252 string returned by gethostname().
  253 \end{sphinxadmonition}
  254 
  255 If the \sphinxstyleemphasis{desired\_name} is a krb5 principal name or a local system name
  256 type which is mapped to a krb5 principal name, clients will only be
  257 allowed to authenticate to that principal in the default keytab.
  258 
  259 
  260 \section{Name Attributes}
  261 \label{\detokenize{appdev/gssapi:name-attributes}}
  262 In release 1.8 or later, the \sphinxhref{https://tools.ietf.org/html/rfc6680.txt\#section-7.4}{gss\_inquire\_name} and
  263 \sphinxhref{https://tools.ietf.org/html/6680.html\#section-7.5}{gss\_get\_name\_attribute} functions, specified in \index{RFC!RFC 6680}\sphinxhref{https://tools.ietf.org/html/rfc6680.html}{\sphinxstylestrong{RFC 6680}}, can be
  264 used to retrieve name attributes from the \sphinxstyleemphasis{src\_name} returned by
  265 \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.1}{gss\_accept\_sec\_context}.  The following attributes are defined when
  266 the krb5 mechanism is used:
  267 
  268 \phantomsection\label{\detokenize{appdev/gssapi:gssapi-authind-attr}}\begin{itemize}
  269 \item {} 
  270 “auth-indicators” attribute:
  271 
  272 \end{itemize}
  273 
  274 This attribute will be included in the \sphinxhref{https://tools.ietf.org/html/rfc6680.txt\#section-7.4}{gss\_inquire\_name} output if the
  275 ticket contains \DUrole{xref,std,std-ref}{authentication indicators}.
  276 One indicator is returned per invocation of \sphinxhref{https://tools.ietf.org/html/6680.html\#section-7.5}{gss\_get\_name\_attribute},
  277 so multiple invocations may be necessary to retrieve all of the
  278 indicators from the ticket.  (New in release 1.15.)
  279 
  280 
  281 \section{Importing and exporting credentials}
  282 \label{\detokenize{appdev/gssapi:importing-and-exporting-credentials}}
  283 The following GSSAPI extensions can be used to import and export
  284 credentials (declared in \sphinxcode{\textless{}gssapi/gssapi\_ext.h\textgreater{}}):
  285 
  286 \fvset{hllines={, ,}}%
  287 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  288 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}export\PYGZus{}cred}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  289                           \PYG{n}{gss\PYGZus{}cred\PYGZus{}id\PYGZus{}t} \PYG{n}{cred\PYGZus{}handle}\PYG{p}{,}
  290                           \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{token}\PYG{p}{)}\PYG{p}{;}
  291 
  292 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}import\PYGZus{}cred}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  293                           \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{token}\PYG{p}{,}
  294                           \PYG{n}{gss\PYGZus{}cred\PYGZus{}id\PYGZus{}t} \PYG{o}{*}\PYG{n}{cred\PYGZus{}handle}\PYG{p}{)}\PYG{p}{;}
  295 \end{sphinxVerbatim}
  296 
  297 The first function serializes a GSSAPI credential handle into a
  298 buffer; the second unseralizes a buffer into a GSSAPI credential
  299 handle.  Serializing a credential does not destroy it.  If any of the
  300 mechanisms used in \sphinxstyleemphasis{cred\_handle} do not support serialization,
  301 gss\_export\_cred will return \sphinxstylestrong{GSS\_S\_UNAVAILABLE}.  As with other
  302 GSSAPI serialization functions, these extensions are only intended to
  303 work with a matching implementation on the other side; they do not
  304 serialize credentials in a standardized format.
  305 
  306 A serialized credential may contain secret information such as ticket
  307 session keys.  The serialization format does not protect this
  308 information from eavesdropping or tampering.  The calling application
  309 must take care to protect the serialized credential when communicating
  310 it over an insecure channel or to an untrusted party.
  311 
  312 A krb5 GSSAPI credential may contain references to a credential cache,
  313 a client keytab, an acceptor keytab, and a replay cache.  These
  314 resources are normally serialized as references to their external
  315 locations (such as the filename of the credential cache).  Because of
  316 this, a serialized krb5 credential can only be imported by a process
  317 with similar privileges to the exporter.  A serialized credential
  318 should not be trusted if it originates from a source with lower
  319 privileges than the importer, as it may contain references to external
  320 credential cache, keytab, or replay cache resources not accessible to
  321 the originator.
  322 
  323 An exception to the above rule applies when a krb5 GSSAPI credential
  324 refers to a memory credential cache, as is normally the case for
  325 delegated credentials received by \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.1}{gss\_accept\_sec\_context}.  In this
  326 case, the contents of the credential cache are serialized, so that the
  327 resulting token may be imported even if the original memory credential
  328 cache no longer exists.
  329 
  330 
  331 \section{Constrained delegation (S4U)}
  332 \label{\detokenize{appdev/gssapi:constrained-delegation-s4u}}
  333 The Microsoft S4U2Self and S4U2Proxy Kerberos protocol extensions
  334 allow an intermediate service to acquire credentials from a client to
  335 a target service without requiring the client to delegate a
  336 ticket-granting ticket, if the KDC is configured to allow it.
  337 
  338 To perform a constrained delegation operation, the intermediate
  339 service must submit to the KDC an “evidence ticket” from the client to
  340 the intermediate service.  An evidence ticket can be acquired when the
  341 client authenticates to the intermediate service with Kerberos, or
  342 with an S4U2Self request if the KDC allows it.  The MIT krb5 GSSAPI
  343 library represents an evidence ticket using a “proxy credential”,
  344 which is a special kind of gss\_cred\_id\_t object whose underlying
  345 credential cache contains the evidence ticket and a krbtgt ticket for
  346 the intermediate service.
  347 
  348 To acquire a proxy credential during client authentication, the
  349 service should first create an acceptor credential using the
  350 \sphinxstylestrong{GSS\_C\_BOTH} usage.  The application should then pass this
  351 credential as the \sphinxstyleemphasis{acceptor\_cred\_handle} to \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.1}{gss\_accept\_sec\_context},
  352 and also pass a \sphinxstyleemphasis{delegated\_cred\_handle} output parameter to receive a
  353 proxy credential containing the evidence ticket.  The output value of
  354 \sphinxstyleemphasis{delegated\_cred\_handle} may be a delegated ticket-granting ticket if
  355 the client sent one, or a proxy credential if not.  If the library can
  356 determine that the client’s ticket is not a valid evidence ticket, it
  357 will place \sphinxstylestrong{GSS\_C\_NO\_CREDENTIAL} in \sphinxstyleemphasis{delegated\_cred\_handle}.
  358 
  359 To acquire a proxy credential using an S4U2Self request, the service
  360 can use the following GSSAPI extension:
  361 
  362 \fvset{hllines={, ,}}%
  363 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  364 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}acquire\PYGZus{}cred\PYGZus{}impersonate\PYGZus{}name}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  365                                             \PYG{n}{gss\PYGZus{}cred\PYGZus{}id\PYGZus{}t} \PYG{n}{icred}\PYG{p}{,}
  366                                             \PYG{n}{gss\PYGZus{}name\PYGZus{}t} \PYG{n}{desired\PYGZus{}name}\PYG{p}{,}
  367                                             \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{time\PYGZus{}req}\PYG{p}{,}
  368                                             \PYG{n}{gss\PYGZus{}OID\PYGZus{}set} \PYG{n}{desired\PYGZus{}mechs}\PYG{p}{,}
  369                                             \PYG{n}{gss\PYGZus{}cred\PYGZus{}usage\PYGZus{}t} \PYG{n}{cred\PYGZus{}usage}\PYG{p}{,}
  370                                             \PYG{n}{gss\PYGZus{}cred\PYGZus{}id\PYGZus{}t} \PYG{o}{*}\PYG{n}{output\PYGZus{}cred}\PYG{p}{,}
  371                                             \PYG{n}{gss\PYGZus{}OID\PYGZus{}set} \PYG{o}{*}\PYG{n}{actual\PYGZus{}mechs}\PYG{p}{,}
  372                                             \PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{time\PYGZus{}rec}\PYG{p}{)}\PYG{p}{;}
  373 \end{sphinxVerbatim}
  374 
  375 The parameters to this function are similar to those of
  376 \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.2}{gss\_acquire\_cred}, except that \sphinxstyleemphasis{icred} is used to make an S4U2Self
  377 request to the KDC for a ticket from \sphinxstyleemphasis{desired\_name} to the
  378 intermediate service.  Both \sphinxstyleemphasis{icred} and \sphinxstyleemphasis{desired\_name} are required
  379 for this function; passing \sphinxstylestrong{GSS\_C\_NO\_CREDENTIAL} or
  380 \sphinxstylestrong{GSS\_C\_NO\_NAME} will cause the call to fail.  \sphinxstyleemphasis{icred} must contain a
  381 krbtgt ticket for the intermediate service.  The result of this
  382 operation is a proxy credential.  (Prior to release 1.18, the result
  383 of this operation may be a regular credential for \sphinxstyleemphasis{desired\_name}, if
  384 the KDC issues a non-forwardable ticket.)
  385 
  386 Once the intermediate service has a proxy credential, it can simply
  387 pass it to \sphinxhref{https://tools.ietf.org/html/rfc2744.html\#section-5.19}{gss\_init\_sec\_context} as the \sphinxstyleemphasis{initiator\_cred\_handle}
  388 parameter, and the desired service as the \sphinxstyleemphasis{target\_name} parameter.
  389 The GSSAPI library will present the krbtgt ticket and evidence ticket
  390 in the proxy credential to the KDC in an S4U2Proxy request; if the
  391 intermediate service has the appropriate permissions, the KDC will
  392 issue a ticket from the client to the target service.  The GSSAPI
  393 library will then use this ticket to authenticate to the target
  394 service.
  395 
  396 If an application needs to find out whether a credential it holds is a
  397 proxy credential and the name of the intermediate service, it can
  398 query the credential with the \sphinxstylestrong{GSS\_KRB5\_GET\_CRED\_IMPERSONATOR} OID
  399 (new in release 1.16, declared in \sphinxcode{\textless{}gssapi/gssapi\_krb5.h\textgreater{}}) using
  400 the gss\_inquire\_cred\_by\_oid extension (declared in
  401 \sphinxcode{\textless{}gssapi/gssapi\_ext.h\textgreater{}}):
  402 
  403 \fvset{hllines={, ,}}%
  404 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  405 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}inquire\PYGZus{}cred\PYGZus{}by\PYGZus{}oid}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  406                                   \PYG{n}{const} \PYG{n}{gss\PYGZus{}cred\PYGZus{}id\PYGZus{}t} \PYG{n}{cred\PYGZus{}handle}\PYG{p}{,}
  407                                   \PYG{n}{gss\PYGZus{}OID} \PYG{n}{desired\PYGZus{}object}\PYG{p}{,}
  408                                   \PYG{n}{gss\PYGZus{}buffer\PYGZus{}set\PYGZus{}t} \PYG{o}{*}\PYG{n}{data\PYGZus{}set}\PYG{p}{)}\PYG{p}{;}
  409 \end{sphinxVerbatim}
  410 
  411 If the call succeeds and \sphinxstyleemphasis{cred\_handle} is a proxy credential,
  412 \sphinxstyleemphasis{data\_set} will be set to a single-element buffer set containing the
  413 unparsed principal name of the intermediate service.  If \sphinxstyleemphasis{cred\_handle}
  414 is not a proxy credential, \sphinxstyleemphasis{data\_set} will be set to an empty buffer
  415 set.  If the library does not support the query,
  416 gss\_inquire\_cred\_by\_oid will return \sphinxstylestrong{GSS\_S\_UNAVAILABLE}.
  417 
  418 
  419 \section{AEAD message wrapping}
  420 \label{\detokenize{appdev/gssapi:aead-message-wrapping}}
  421 The following GSSAPI extensions (declared in
  422 \sphinxcode{\textless{}gssapi/gssapi\_ext.h\textgreater{}}) can be used to wrap and unwrap messages
  423 with additional “associated data” which is integrity-checked but is
  424 not included in the output buffer:
  425 
  426 \fvset{hllines={, ,}}%
  427 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  428 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}wrap\PYGZus{}aead}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  429                         \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{n}{context\PYGZus{}handle}\PYG{p}{,}
  430                         \PYG{n+nb}{int} \PYG{n}{conf\PYGZus{}req\PYGZus{}flag}\PYG{p}{,} \PYG{n}{gss\PYGZus{}qop\PYGZus{}t} \PYG{n}{qop\PYGZus{}req}\PYG{p}{,}
  431                         \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{input\PYGZus{}assoc\PYGZus{}buffer}\PYG{p}{,}
  432                         \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{input\PYGZus{}payload\PYGZus{}buffer}\PYG{p}{,}
  433                         \PYG{n+nb}{int} \PYG{o}{*}\PYG{n}{conf\PYGZus{}state}\PYG{p}{,}
  434                         \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{output\PYGZus{}message\PYGZus{}buffer}\PYG{p}{)}\PYG{p}{;}
  435 
  436 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}unwrap\PYGZus{}aead}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  437                           \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{n}{context\PYGZus{}handle}\PYG{p}{,}
  438                           \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{input\PYGZus{}message\PYGZus{}buffer}\PYG{p}{,}
  439                           \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{input\PYGZus{}assoc\PYGZus{}buffer}\PYG{p}{,}
  440                           \PYG{n}{gss\PYGZus{}buffer\PYGZus{}t} \PYG{n}{output\PYGZus{}payload\PYGZus{}buffer}\PYG{p}{,}
  441                           \PYG{n+nb}{int} \PYG{o}{*}\PYG{n}{conf\PYGZus{}state}\PYG{p}{,}
  442                           \PYG{n}{gss\PYGZus{}qop\PYGZus{}t} \PYG{o}{*}\PYG{n}{qop\PYGZus{}state}\PYG{p}{)}\PYG{p}{;}
  443 \end{sphinxVerbatim}
  444 
  445 Wrap tokens created with gss\_wrap\_aead will successfully unwrap only
  446 if the same \sphinxstyleemphasis{input\_assoc\_buffer} contents are presented to
  447 gss\_unwrap\_aead.
  448 
  449 
  450 \section{IOV message wrapping}
  451 \label{\detokenize{appdev/gssapi:iov-message-wrapping}}
  452 The following extensions (declared in \sphinxcode{\textless{}gssapi/gssapi\_ext.h\textgreater{}}) can
  453 be used for in-place encryption, fine-grained control over wrap token
  454 layout, and for constructing wrap tokens compatible with Microsoft DCE
  455 RPC:
  456 
  457 \fvset{hllines={, ,}}%
  458 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  459 \PYG{n}{typedef} \PYG{n}{struct} \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc\PYGZus{}struct} \PYG{p}{\PYGZob{}}
  460     \PYG{n}{OM\PYGZus{}uint32} \PYG{n+nb}{type}\PYG{p}{;}
  461     \PYG{n}{gss\PYGZus{}buffer\PYGZus{}desc} \PYG{n}{buffer}\PYG{p}{;}
  462 \PYG{p}{\PYGZcb{}} \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc}\PYG{p}{,} \PYG{o}{*}\PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}t}\PYG{p}{;}
  463 
  464 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}wrap\PYGZus{}iov}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  465                        \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{n}{context\PYGZus{}handle}\PYG{p}{,}
  466                        \PYG{n+nb}{int} \PYG{n}{conf\PYGZus{}req\PYGZus{}flag}\PYG{p}{,} \PYG{n}{gss\PYGZus{}qop\PYGZus{}t} \PYG{n}{qop\PYGZus{}req}\PYG{p}{,}
  467                        \PYG{n+nb}{int} \PYG{o}{*}\PYG{n}{conf\PYGZus{}state}\PYG{p}{,}
  468                        \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{o}{*}\PYG{n}{iov}\PYG{p}{,} \PYG{n+nb}{int} \PYG{n}{iov\PYGZus{}count}\PYG{p}{)}\PYG{p}{;}
  469 
  470 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}unwrap\PYGZus{}iov}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  471                          \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{n}{context\PYGZus{}handle}\PYG{p}{,}
  472                          \PYG{n+nb}{int} \PYG{o}{*}\PYG{n}{conf\PYGZus{}state}\PYG{p}{,} \PYG{n}{gss\PYGZus{}qop\PYGZus{}t} \PYG{o}{*}\PYG{n}{qop\PYGZus{}state}\PYG{p}{,}
  473                          \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{o}{*}\PYG{n}{iov}\PYG{p}{,} \PYG{n+nb}{int} \PYG{n}{iov\PYGZus{}count}\PYG{p}{)}\PYG{p}{;}
  474 
  475 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}wrap\PYGZus{}iov\PYGZus{}length}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  476                               \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{n}{context\PYGZus{}handle}\PYG{p}{,}
  477                               \PYG{n+nb}{int} \PYG{n}{conf\PYGZus{}req\PYGZus{}flag}\PYG{p}{,}
  478                               \PYG{n}{gss\PYGZus{}qop\PYGZus{}t} \PYG{n}{qop\PYGZus{}req}\PYG{p}{,} \PYG{n+nb}{int} \PYG{o}{*}\PYG{n}{conf\PYGZus{}state}\PYG{p}{,}
  479                               \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{o}{*}\PYG{n}{iov}\PYG{p}{,}
  480                               \PYG{n+nb}{int} \PYG{n}{iov\PYGZus{}count}\PYG{p}{)}\PYG{p}{;}
  481 
  482 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}release\PYGZus{}iov\PYGZus{}buffer}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  483                                  \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{o}{*}\PYG{n}{iov}\PYG{p}{,}
  484                                  \PYG{n+nb}{int} \PYG{n}{iov\PYGZus{}count}\PYG{p}{)}\PYG{p}{;}
  485 \end{sphinxVerbatim}
  486 
  487 The caller of gss\_wrap\_iov provides an array of gss\_iov\_buffer\_desc
  488 structures, each containing a type and a gss\_buffer\_desc structure.
  489 Valid types include:
  490 \begin{itemize}
  491 \item {} 
  492 \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_DATA}: A data buffer to be included in the
  493 token, and to be encrypted or decrypted in-place if the token is
  494 confidentiality-protected.
  495 
  496 \item {} 
  497 \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_HEADER}: The GSSAPI wrap token header and
  498 underlying cryptographic header.
  499 
  500 \item {} 
  501 \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_TRAILER}: The cryptographic trailer, if one is
  502 required.
  503 
  504 \item {} 
  505 \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_PADDING}: Padding to be combined with the data
  506 during encryption and decryption.  (The implementation may choose to
  507 place padding in the trailer buffer, in which case it will set the
  508 padding buffer length to 0.)
  509 
  510 \item {} 
  511 \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_STREAM}: For unwrapping only, a buffer
  512 containing a complete wrap token in standard format to be unwrapped.
  513 
  514 \item {} 
  515 \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_SIGN\_ONLY}: A buffer to be included in the
  516 token’s integrity protection checksum, but not to be encrypted or
  517 included in the token itself.
  518 
  519 \end{itemize}
  520 
  521 For gss\_wrap\_iov, the IOV list should contain one HEADER buffer,
  522 followed by zero or more SIGN\_ONLY buffers, followed by one or more
  523 DATA buffers, followed by a TRAILER buffer.  The memory pointed to by
  524 the buffers is not required to be contiguous or in any particular
  525 order.  If \sphinxstyleemphasis{conf\_req\_flag} is true, DATA buffers will be encrypted
  526 in-place, while SIGN\_ONLY buffers will not be modified.
  527 
  528 The type of an output buffer may be combined with
  529 \sphinxstylestrong{GSS\_C\_BUFFER\_FLAG\_ALLOCATE} to request that gss\_wrap\_iov allocate
  530 the buffer contents.  If gss\_wrap\_iov allocates a buffer, it sets the
  531 \sphinxstylestrong{GSS\_C\_BUFFER\_FLAG\_ALLOCATED} flag on the buffer type.
  532 gss\_release\_iov\_buffer can be used to release all allocated buffers
  533 within an iov list and unset their allocated flags.  Here is an
  534 example of how gss\_wrap\_iov can be used with allocation requested
  535 (\sphinxstyleemphasis{ctx} is assumed to be a previously established gss\_ctx\_id\_t):
  536 
  537 \fvset{hllines={, ,}}%
  538 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  539 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{;}
  540 \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{4}\PYG{p}{]}\PYG{p}{;}
  541 \PYG{n}{char} \PYG{n+nb}{str}\PYG{p}{[}\PYG{p}{]} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{message}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;}
  542 
  543 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}HEADER} \PYG{o}{\textbar{}} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}FLAG\PYGZus{}ALLOCATE}\PYG{p}{;}
  544 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}DATA}\PYG{p}{;}
  545 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{n+nb}{str}\PYG{p}{;}
  546 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{=} \PYG{n}{strlen}\PYG{p}{(}\PYG{n+nb}{str}\PYG{p}{)}\PYG{p}{;}
  547 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}PADDING} \PYG{o}{\textbar{}} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}FLAG\PYGZus{}ALLOCATE}\PYG{p}{;}
  548 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}TRAILER} \PYG{o}{\textbar{}} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}FLAG\PYGZus{}ALLOCATE}\PYG{p}{;}
  549 
  550 \PYG{n}{major} \PYG{o}{=} \PYG{n}{gss\PYGZus{}wrap\PYGZus{}iov}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{ctx}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{n}{GSS\PYGZus{}C\PYGZus{}QOP\PYGZus{}DEFAULT}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,}
  551                      \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{;}
  552 \PYG{k}{if} \PYG{p}{(}\PYG{n}{GSS\PYGZus{}ERROR}\PYG{p}{(}\PYG{n}{major}\PYG{p}{)}\PYG{p}{)}
  553     \PYG{n}{handle\PYGZus{}error}\PYG{p}{(}\PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{)}\PYG{p}{;}
  554 
  555 \PYG{o}{/}\PYG{o}{*} \PYG{n}{Transmit} \PYG{o+ow}{or} \PYG{n}{otherwise} \PYG{n}{use} \PYG{n}{resulting} \PYG{n}{buffers}\PYG{o}{.} \PYG{o}{*}\PYG{o}{/}
  556 
  557 \PYG{p}{(}\PYG{n}{void}\PYG{p}{)}\PYG{n}{gss\PYGZus{}release\PYGZus{}iov\PYGZus{}buffer}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{;}
  558 \end{sphinxVerbatim}
  559 
  560 If the caller does not choose to request buffer allocation by
  561 gss\_wrap\_iov, it should first call gss\_wrap\_iov\_length to query the
  562 lengths of the HEADER, PADDING, and TRAILER buffers.  DATA buffers
  563 must be provided in the iov list so that padding length can be
  564 computed correctly, but the output buffers need not be initialized.
  565 Here is an example of using gss\_wrap\_iov\_length and gss\_wrap\_iov:
  566 
  567 \fvset{hllines={, ,}}%
  568 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  569 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{;}
  570 \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{4}\PYG{p}{]}\PYG{p}{;}
  571 \PYG{n}{char} \PYG{n+nb}{str}\PYG{p}{[}\PYG{l+m+mi}{1024}\PYG{p}{]} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{message}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{o}{*}\PYG{n}{ptr}\PYG{p}{;}
  572 
  573 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}HEADER}\PYG{p}{;}
  574 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}DATA}\PYG{p}{;}
  575 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{n+nb}{str}\PYG{p}{;}
  576 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{=} \PYG{n}{strlen}\PYG{p}{(}\PYG{n+nb}{str}\PYG{p}{)}\PYG{p}{;}
  577 
  578 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}PADDING}\PYG{p}{;}
  579 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}TRAILER}\PYG{p}{;}
  580 
  581 \PYG{n}{major} \PYG{o}{=} \PYG{n}{gss\PYGZus{}wrap\PYGZus{}iov\PYGZus{}length}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{ctx}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{n}{GSS\PYGZus{}C\PYGZus{}QOP\PYGZus{}DEFAULT}\PYG{p}{,}
  582                             \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{;}
  583 \PYG{k}{if} \PYG{p}{(}\PYG{n}{GSS\PYGZus{}ERROR}\PYG{p}{(}\PYG{n}{major}\PYG{p}{)}\PYG{p}{)}
  584     \PYG{n}{handle\PYGZus{}error}\PYG{p}{(}\PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{)}\PYG{p}{;}
  585 \PYG{k}{if} \PYG{p}{(}\PYG{n}{strlen}\PYG{p}{(}\PYG{n+nb}{str}\PYG{p}{)} \PYG{o}{+} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{+} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{+}
  586     \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{\PYGZgt{}} \PYG{n}{sizeof}\PYG{p}{(}\PYG{n+nb}{str}\PYG{p}{)}\PYG{p}{)}
  587     \PYG{n}{handle\PYGZus{}out\PYGZus{}of\PYGZus{}space\PYGZus{}error}\PYG{p}{(}\PYG{p}{)}\PYG{p}{;}
  588 \PYG{n}{ptr} \PYG{o}{=} \PYG{n+nb}{str} \PYG{o}{+} \PYG{n}{strlen}\PYG{p}{(}\PYG{n+nb}{str}\PYG{p}{)}\PYG{p}{;}
  589 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{n}{ptr}\PYG{p}{;}
  590 \PYG{n}{ptr} \PYG{o}{+}\PYG{o}{=} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length}\PYG{p}{;}
  591 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{n}{ptr}\PYG{p}{;}
  592 \PYG{n}{ptr} \PYG{o}{+}\PYG{o}{=} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length}\PYG{p}{;}
  593 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{n}{ptr}\PYG{p}{;}
  594 
  595 \PYG{n}{major} \PYG{o}{=} \PYG{n}{gss\PYGZus{}wrap\PYGZus{}iov}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{ctx}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{n}{GSS\PYGZus{}C\PYGZus{}QOP\PYGZus{}DEFAULT}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,}
  596                      \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{;}
  597 \PYG{k}{if} \PYG{p}{(}\PYG{n}{GSS\PYGZus{}ERROR}\PYG{p}{(}\PYG{n}{major}\PYG{p}{)}\PYG{p}{)}
  598     \PYG{n}{handle\PYGZus{}error}\PYG{p}{(}\PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{)}\PYG{p}{;}
  599 \end{sphinxVerbatim}
  600 
  601 If the context was established using the \sphinxstylestrong{GSS\_C\_DCE\_STYLE} flag
  602 (described in \index{RFC!RFC 4757}\sphinxhref{https://tools.ietf.org/html/rfc4757.html}{\sphinxstylestrong{RFC 4757}}), wrap tokens compatible with Microsoft DCE
  603 RPC can be constructed.  In this case, the IOV list must include a
  604 SIGN\_ONLY buffer, a DATA buffer, a second SIGN\_ONLY buffer, and a
  605 HEADER buffer in that order (the order of the buffer contents remains
  606 arbitrary).  The application must pad the DATA buffer to a multiple of
  607 16 bytes as no padding or trailer buffer is used.
  608 
  609 gss\_unwrap\_iov may be called with an IOV list just like one which
  610 would be provided to gss\_wrap\_iov.  DATA buffers will be decrypted
  611 in-place if they were encrypted, and SIGN\_ONLY buffers will not be
  612 modified.
  613 
  614 Alternatively, gss\_unwrap\_iov may be called with a single STREAM
  615 buffer, zero or more SIGN\_ONLY buffers, and a single DATA buffer.  The
  616 STREAM buffer is interpreted as a complete wrap token.  The STREAM
  617 buffer will be modified in-place to decrypt its contents.  The DATA
  618 buffer will be initialized to point to the decrypted data within the
  619 STREAM buffer, unless it has the \sphinxstylestrong{GSS\_C\_BUFFER\_FLAG\_ALLOCATE} flag
  620 set, in which case it will be initialized with a copy of the decrypted
  621 data.  Here is an example (\sphinxstyleemphasis{token} and \sphinxstyleemphasis{token\_len} are assumed to be a
  622 pre-existing pointer and length for a modifiable region of data):
  623 
  624 \fvset{hllines={, ,}}%
  625 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  626 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{;}
  627 \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{;}
  628 
  629 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}STREAM}\PYG{p}{;}
  630 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{n}{token}\PYG{p}{;}
  631 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{=} \PYG{n}{token\PYGZus{}len}\PYG{p}{;}
  632 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}DATA}\PYG{p}{;}
  633 \PYG{n}{major} \PYG{o}{=} \PYG{n}{gss\PYGZus{}unwrap\PYGZus{}iov}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{ctx}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{)}\PYG{p}{;}
  634 \PYG{k}{if} \PYG{p}{(}\PYG{n}{GSS\PYGZus{}ERROR}\PYG{p}{(}\PYG{n}{major}\PYG{p}{)}\PYG{p}{)}
  635     \PYG{n}{handle\PYGZus{}error}\PYG{p}{(}\PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{)}\PYG{p}{;}
  636 
  637 \PYG{o}{/}\PYG{o}{*} \PYG{n}{Decrypted} \PYG{n}{data} \PYG{o+ow}{is} \PYG{o+ow}{in} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{p}{,} \PYG{n}{pointing} \PYG{n}{to} \PYG{n}{a} \PYG{n}{subregion} \PYG{n}{of}
  638  \PYG{o}{*} \PYG{n}{token}\PYG{o}{.} \PYG{o}{*}\PYG{o}{/}
  639 \end{sphinxVerbatim}
  640 
  641 
  642 \section{IOV MIC tokens}
  643 \label{\detokenize{appdev/gssapi:gssapi-mic-token}}\label{\detokenize{appdev/gssapi:iov-mic-tokens}}
  644 The following extensions (declared in \sphinxcode{\textless{}gssapi/gssapi\_ext.h\textgreater{}}) can
  645 be used in release 1.12 or later to construct and verify MIC tokens
  646 using an IOV list:
  647 
  648 \fvset{hllines={, ,}}%
  649 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  650 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}get\PYGZus{}mic\PYGZus{}iov}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  651                           \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{n}{context\PYGZus{}handle}\PYG{p}{,}
  652                           \PYG{n}{gss\PYGZus{}qop\PYGZus{}t} \PYG{n}{qop\PYGZus{}req}\PYG{p}{,}
  653                           \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{o}{*}\PYG{n}{iov}\PYG{p}{,}
  654                           \PYG{n+nb}{int} \PYG{n}{iov\PYGZus{}count}\PYG{p}{)}\PYG{p}{;}
  655 
  656 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}get\PYGZus{}mic\PYGZus{}iov\PYGZus{}length}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  657                                  \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{n}{context\PYGZus{}handle}\PYG{p}{,}
  658                                  \PYG{n}{gss\PYGZus{}qop\PYGZus{}t} \PYG{n}{qop\PYGZus{}req}\PYG{p}{,}
  659                                  \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{o}{*}\PYG{n}{iov}\PYG{p}{,}
  660                                  \PYG{n}{iov\PYGZus{}count}\PYG{p}{)}\PYG{p}{;}
  661 
  662 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{gss\PYGZus{}verify\PYGZus{}mic\PYGZus{}iov}\PYG{p}{(}\PYG{n}{OM\PYGZus{}uint32} \PYG{o}{*}\PYG{n}{minor\PYGZus{}status}\PYG{p}{,}
  663                              \PYG{n}{gss\PYGZus{}ctx\PYGZus{}id\PYGZus{}t} \PYG{n}{context\PYGZus{}handle}\PYG{p}{,}
  664                              \PYG{n}{gss\PYGZus{}qop\PYGZus{}t} \PYG{o}{*}\PYG{n}{qop\PYGZus{}state}\PYG{p}{,}
  665                              \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{o}{*}\PYG{n}{iov}\PYG{p}{,}
  666                              \PYG{n+nb}{int} \PYG{n}{iov\PYGZus{}count}\PYG{p}{)}\PYG{p}{;}
  667 \end{sphinxVerbatim}
  668 
  669 The caller of gss\_get\_mic\_iov provides an array of gss\_iov\_buffer\_desc
  670 structures, each containing a type and a gss\_buffer\_desc structure.
  671 Valid types include:
  672 \begin{itemize}
  673 \item {} 
  674 \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_DATA} and \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_SIGN\_ONLY}: The
  675 corresponding buffer for each of these types will be signed for the
  676 MIC token, in the order provided.
  677 
  678 \item {} 
  679 \sphinxstylestrong{GSS\_C\_BUFFER\_TYPE\_MIC\_TOKEN}: The GSSAPI MIC token.
  680 
  681 \end{itemize}
  682 
  683 The type of the MIC\_TOKEN buffer may be combined with
  684 \sphinxstylestrong{GSS\_C\_BUFFER\_FLAG\_ALLOCATE} to request that gss\_get\_mic\_iov
  685 allocate the buffer contents.  If gss\_get\_mic\_iov allocates the
  686 buffer, it sets the \sphinxstylestrong{GSS\_C\_BUFFER\_FLAG\_ALLOCATED} flag on the buffer
  687 type.  gss\_release\_iov\_buffer can be used to release all allocated
  688 buffers within an iov list and unset their allocated flags.  Here is
  689 an example of how gss\_get\_mic\_iov can be used with allocation
  690 requested (\sphinxstyleemphasis{ctx} is assumed to be a previously established
  691 gss\_ctx\_id\_t):
  692 
  693 \fvset{hllines={, ,}}%
  694 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  695 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{;}
  696 \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{;}
  697 
  698 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}DATA}\PYG{p}{;}
  699 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{sign1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;}
  700 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{=} \PYG{l+m+mi}{5}\PYG{p}{;}
  701 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}SIGN\PYGZus{}ONLY}\PYG{p}{;}
  702 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{sign2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;}
  703 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{=} \PYG{l+m+mi}{5}\PYG{p}{;}
  704 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}MIC\PYGZus{}TOKEN} \PYG{o}{\textbar{}} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}FLAG\PYGZus{}ALLOCATE}\PYG{p}{;}
  705 
  706 \PYG{n}{major} \PYG{o}{=} \PYG{n}{gss\PYGZus{}get\PYGZus{}mic\PYGZus{}iov}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{ctx}\PYG{p}{,} \PYG{n}{GSS\PYGZus{}C\PYGZus{}QOP\PYGZus{}DEFAULT}\PYG{p}{,} \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{)}\PYG{p}{;}
  707 \PYG{k}{if} \PYG{p}{(}\PYG{n}{GSS\PYGZus{}ERROR}\PYG{p}{(}\PYG{n}{major}\PYG{p}{)}\PYG{p}{)}
  708     \PYG{n}{handle\PYGZus{}error}\PYG{p}{(}\PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{)}\PYG{p}{;}
  709 
  710 \PYG{o}{/}\PYG{o}{*} \PYG{n}{Transmit} \PYG{o+ow}{or} \PYG{n}{otherwise} \PYG{n}{use} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.} \PYG{o}{*}\PYG{o}{/}
  711 
  712 \PYG{p}{(}\PYG{n}{void}\PYG{p}{)}\PYG{n}{gss\PYGZus{}release\PYGZus{}iov\PYGZus{}buffer}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{)}\PYG{p}{;}
  713 \end{sphinxVerbatim}
  714 
  715 If the caller does not choose to request buffer allocation by
  716 gss\_get\_mic\_iov, it should first call gss\_get\_mic\_iov\_length to query
  717 the length of the MIC\_TOKEN buffer.  Here is an example of using
  718 gss\_get\_mic\_iov\_length and gss\_get\_mic\_iov:
  719 
  720 \fvset{hllines={, ,}}%
  721 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  722 \PYG{n}{OM\PYGZus{}uint32} \PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{;}
  723 \PYG{n}{gss\PYGZus{}iov\PYGZus{}buffer\PYGZus{}desc} \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{;}
  724 \PYG{n}{char} \PYG{n}{data}\PYG{p}{[}\PYG{l+m+mi}{1024}\PYG{p}{]}\PYG{p}{;}
  725 
  726 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}MIC\PYGZus{}TOKEN}\PYG{p}{;}
  727 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{type} \PYG{o}{=} \PYG{n}{GSS\PYGZus{}IOV\PYGZus{}BUFFER\PYGZus{}TYPE\PYGZus{}DATA}\PYG{p}{;}
  728 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{message}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;}
  729 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{=} \PYG{l+m+mi}{7}\PYG{p}{;}
  730 
  731 \PYG{n}{major} \PYG{o}{=} \PYG{n}{gss\PYGZus{}get\PYGZus{}mic\PYGZus{}iov\PYGZus{}length}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{ctx}\PYG{p}{,} \PYG{n}{GSS\PYGZus{}C\PYGZus{}QOP\PYGZus{}DEFAULT}\PYG{p}{,} \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{)}\PYG{p}{;}
  732 \PYG{k}{if} \PYG{p}{(}\PYG{n}{GSS\PYGZus{}ERROR}\PYG{p}{(}\PYG{n}{major}\PYG{p}{)}\PYG{p}{)}
  733     \PYG{n}{handle\PYGZus{}error}\PYG{p}{(}\PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{)}\PYG{p}{;}
  734 \PYG{k}{if} \PYG{p}{(}\PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{length} \PYG{o}{\PYGZgt{}} \PYG{n}{sizeof}\PYG{p}{(}\PYG{n}{data}\PYG{p}{)}\PYG{p}{)}
  735     \PYG{n}{handle\PYGZus{}out\PYGZus{}of\PYGZus{}space\PYGZus{}error}\PYG{p}{(}\PYG{p}{)}\PYG{p}{;}
  736 \PYG{n}{iov}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{.}\PYG{n}{buffer}\PYG{o}{.}\PYG{n}{value} \PYG{o}{=} \PYG{n}{data}\PYG{p}{;}
  737 
  738 \PYG{n}{major} \PYG{o}{=} \PYG{n}{gss\PYGZus{}get\PYGZus{}mic\PYGZus{}iov}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{minor}\PYG{p}{,} \PYG{n}{ctx}\PYG{p}{,} \PYG{n}{GSS\PYGZus{}C\PYGZus{}QOP\PYGZus{}DEFAULT}\PYG{p}{,} \PYG{n}{iov}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{)}\PYG{p}{;}
  739 \PYG{k}{if} \PYG{p}{(}\PYG{n}{GSS\PYGZus{}ERROR}\PYG{p}{(}\PYG{n}{major}\PYG{p}{)}\PYG{p}{)}
  740     \PYG{n}{handle\PYGZus{}error}\PYG{p}{(}\PYG{n}{major}\PYG{p}{,} \PYG{n}{minor}\PYG{p}{)}\PYG{p}{;}
  741 \end{sphinxVerbatim}
  742 
  743 
  744 \chapter{Year 2038 considerations for uses of krb5\_timestamp}
  745 \label{\detokenize{appdev/y2038::doc}}\label{\detokenize{appdev/y2038:year-2038-considerations-for-uses-of-krb5-timestamp}}
  746 POSIX time values, which measure the number of seconds since January 1
  747 1970, will exceed the maximum value representable in a signed 32-bit
  748 integer in January 2038.  This documentation describes considerations
  749 for consumers of the MIT krb5 libraries.
  750 
  751 Applications or libraries which use libkrb5 and consume the timestamps
  752 included in credentials or other structures make use of the
  753 {\hyperref[\detokenize{appdev/refs/types/krb5_timestamp:c.krb5_timestamp}]{\sphinxcrossref{\sphinxcode{krb5\_timestamp}}}} type.  For historical reasons, krb5\_timestamp
  754 is a signed 32-bit integer, even on platforms where a larger type is
  755 natively used to represent time values.  To behave properly for time
  756 values after January 2038, calling code should cast krb5\_timestamp
  757 values to uint32\_t, and then to time\_t:
  758 
  759 \fvset{hllines={, ,}}%
  760 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  761 \PYG{p}{(}\PYG{n}{time\PYGZus{}t}\PYG{p}{)}\PYG{p}{(}\PYG{n}{uint32\PYGZus{}t}\PYG{p}{)}\PYG{n}{timestamp}
  762 \end{sphinxVerbatim}
  763 
  764 Used in this way, krb5\_timestamp values can represent time values up
  765 until February 2106, provided that the platform uses a 64-bit or
  766 larger time\_t type.  This usage will also remain safe if a later
  767 version of MIT krb5 changes krb5\_timestamp to an unsigned 32-bit
  768 integer.
  769 
  770 The GSSAPI only uses representations of time intervals, not absolute
  771 times.  Callers of the GSSAPI should require no changes to behave
  772 correctly after January 2038, provided that they use MIT krb5 release
  773 1.16 or later.
  774 
  775 
  776 \chapter{Differences between Heimdal and MIT Kerberos API}
  777 \label{\detokenize{appdev/h5l_mit_apidiff:differences-between-heimdal-and-mit-kerberos-api}}\label{\detokenize{appdev/h5l_mit_apidiff::doc}}
  778 
  779 \begin{savenotes}\sphinxattablestart
  780 \centering
  781 \begin{tabulary}{\linewidth}[t]{|l|l|}
  782 \hline
  783 
  784 {\hyperref[\detokenize{appdev/refs/api/krb5_auth_con_getaddrs:c.krb5_auth_con_getaddrs}]{\sphinxcrossref{\sphinxcode{krb5\_auth\_con\_getaddrs()}}}}
  785 &
  786 H5l: If either of the pointers to local\_addr
  787 and remote\_addr is not NULL, it is freed
  788 first and then reallocated before being
  789 populated with the content of corresponding
  790 address from authentication context.
  791 \\
  792 \hline
  793 {\hyperref[\detokenize{appdev/refs/api/krb5_auth_con_setaddrs:c.krb5_auth_con_setaddrs}]{\sphinxcrossref{\sphinxcode{krb5\_auth\_con\_setaddrs()}}}}
  794 &
  795 H5l: If either address is NULL, the previous
  796 address remains in place
  797 \\
  798 \hline
  799 {\hyperref[\detokenize{appdev/refs/api/krb5_auth_con_setports:c.krb5_auth_con_setports}]{\sphinxcrossref{\sphinxcode{krb5\_auth\_con\_setports()}}}}
  800 &
  801 H5l: Not implemented as of version 1.3.3
  802 \\
  803 \hline
  804 {\hyperref[\detokenize{appdev/refs/api/krb5_auth_con_setrecvsubkey:c.krb5_auth_con_setrecvsubkey}]{\sphinxcrossref{\sphinxcode{krb5\_auth\_con\_setrecvsubkey()}}}}
  805 &
  806 H5l: If either port is NULL, the previous
  807 port remains in place
  808 \\
  809 \hline
  810 {\hyperref[\detokenize{appdev/refs/api/krb5_auth_con_setsendsubkey:c.krb5_auth_con_setsendsubkey}]{\sphinxcrossref{\sphinxcode{krb5\_auth\_con\_setsendsubkey()}}}}
  811 &
  812 H5l: Not implemented as of version 1.3.3
  813 \\
  814 \hline
  815 {\hyperref[\detokenize{appdev/refs/api/krb5_cc_set_config:c.krb5_cc_set_config}]{\sphinxcrossref{\sphinxcode{krb5\_cc\_set\_config()}}}}
  816 &
  817 MIT: Before version 1.10 it was assumed that
  818 the last argument \sphinxstyleemphasis{data} is ALWAYS non-zero.
  819 \\
  820 \hline
  821 \sphinxcode{krb5\_cccol\_last\_change\_time()}
  822 &
  823 MIT: not implemented
  824 \\
  825 \hline
  826 {\hyperref[\detokenize{appdev/refs/api/krb5_set_default_realm:c.krb5_set_default_realm}]{\sphinxcrossref{\sphinxcode{krb5\_set\_default\_realm()}}}}
  827 &
  828 H5l: Caches the computed default realm context
  829 field.  If the second argument is NULL,
  830 it tries to retrieve it from libdefaults or DNS.
  831 MIT: Computes the default realm each time
  832 if it wasn’t explicitly set in the context
  833 \\
  834 \hline
  835 \end{tabulary}
  836 \par
  837 \sphinxattableend\end{savenotes}
  838 
  839 
  840 \chapter{Initial credentials}
  841 \label{\detokenize{appdev/init_creds:initial-credentials}}\label{\detokenize{appdev/init_creds::doc}}
  842 Software that performs tasks such as logging users into a computer
  843 when they type their Kerberos password needs to get initial
  844 credentials (usually ticket granting tickets) from Kerberos.  Such
  845 software shares some behavior with the \DUrole{xref,std,std-ref}{kinit(1)} program.
  846 
  847 Whenever a program grants access to a resource (such as a local login
  848 session on a desktop computer) based on a user successfully getting
  849 initial Kerberos credentials, it must verify those credentials against
  850 a secure shared secret (e.g., a host keytab) to ensure that the user
  851 credentials actually originate from a legitimate KDC.  Failure to
  852 perform this verification is a critical vulnerability, because a
  853 malicious user can execute the “Zanarotti attack”: the user constructs
  854 a fake response that appears to come from the legitimate KDC, but
  855 whose contents come from an attacker-controlled KDC.
  856 
  857 Some applications read a Kerberos password over the network (ideally
  858 over a secure channel), which they then verify against the KDC.  While
  859 this technique may be the only practical way to integrate Kerberos
  860 into some existing legacy systems, its use is contrary to the original
  861 design goals of Kerberos.
  862 
  863 The function {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_password()}}}} will get initial
  864 credentials for a client using a password.  An application that needs
  865 to verify the credentials can call {\hyperref[\detokenize{appdev/refs/api/krb5_verify_init_creds:c.krb5_verify_init_creds}]{\sphinxcrossref{\sphinxcode{krb5\_verify\_init\_creds()}}}}.
  866 Here is an example of code to obtain and verify TGT credentials, given
  867 strings \sphinxstyleemphasis{princname} and \sphinxstyleemphasis{password} for the client principal name and
  868 password:
  869 
  870 \fvset{hllines={, ,}}%
  871 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  872 \PYG{n}{krb5\PYGZus{}error\PYGZus{}code} \PYG{n}{ret}\PYG{p}{;}
  873 \PYG{n}{krb5\PYGZus{}creds} \PYG{n}{creds}\PYG{p}{;}
  874 \PYG{n}{krb5\PYGZus{}principal} \PYG{n}{client\PYGZus{}princ} \PYG{o}{=} \PYG{n}{NULL}\PYG{p}{;}
  875 
  876 \PYG{n}{memset}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{sizeof}\PYG{p}{(}\PYG{n}{creds}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
  877 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}parse\PYGZus{}name}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{princname}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{client\PYGZus{}princ}\PYG{p}{)}\PYG{p}{;}
  878 \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
  879     \PYG{n}{goto} \PYG{n}{cleanup}\PYG{p}{;}
  880 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}password}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{n}{client\PYGZus{}princ}\PYG{p}{,}
  881                                    \PYG{n}{password}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{)}\PYG{p}{;}
  882 \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
  883     \PYG{n}{goto} \PYG{n}{cleanup}\PYG{p}{;}
  884 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}verify\PYGZus{}init\PYGZus{}creds}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{)}\PYG{p}{;}
  885 
  886 \PYG{n}{cleanup}\PYG{p}{:}
  887 \PYG{n}{krb5\PYGZus{}free\PYGZus{}principal}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{client\PYGZus{}princ}\PYG{p}{)}\PYG{p}{;}
  888 \PYG{n}{krb5\PYGZus{}free\PYGZus{}cred\PYGZus{}contents}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{)}\PYG{p}{;}
  889 \PYG{k}{return} \PYG{n}{ret}\PYG{p}{;}
  890 \end{sphinxVerbatim}
  891 
  892 
  893 \section{Options for get\_init\_creds}
  894 \label{\detokenize{appdev/init_creds:options-for-get-init-creds}}
  895 The function {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_password()}}}} takes an options
  896 parameter (which can be a null pointer).  Use the function
  897 {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_alloc:c.krb5_get_init_creds_opt_alloc}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_alloc()}}}} to allocate an options
  898 structure, and {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_free:c.krb5_get_init_creds_opt_free}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_free()}}}} to free it.  For
  899 example:
  900 
  901 \fvset{hllines={, ,}}%
  902 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  903 \PYG{n}{krb5\PYGZus{}error\PYGZus{}code} \PYG{n}{ret}\PYG{p}{;}
  904 \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt} \PYG{o}{*}\PYG{n}{opt} \PYG{o}{=} \PYG{n}{NULL}\PYG{p}{;}
  905 \PYG{n}{krb5\PYGZus{}creds} \PYG{n}{creds}\PYG{p}{;}
  906 
  907 \PYG{n}{memset}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{sizeof}\PYG{p}{(}\PYG{n}{creds}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
  908 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}alloc}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{opt}\PYG{p}{)}\PYG{p}{;}
  909 \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
  910     \PYG{n}{goto} \PYG{n}{cleanup}\PYG{p}{;}
  911 \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}set\PYGZus{}tkt\PYGZus{}life}\PYG{p}{(}\PYG{n}{opt}\PYG{p}{,} \PYG{l+m+mi}{24} \PYG{o}{*} \PYG{l+m+mi}{60} \PYG{o}{*} \PYG{l+m+mi}{60}\PYG{p}{)}\PYG{p}{;}
  912 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}password}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{n}{client\PYGZus{}princ}\PYG{p}{,}
  913                                    \PYG{n}{password}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{opt}\PYG{p}{)}\PYG{p}{;}
  914 \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
  915     \PYG{n}{goto} \PYG{n}{cleanup}\PYG{p}{;}
  916 
  917 \PYG{n}{cleanup}\PYG{p}{:}
  918 \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}free}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{opt}\PYG{p}{)}\PYG{p}{;}
  919 \PYG{n}{krb5\PYGZus{}free\PYGZus{}cred\PYGZus{}contents}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{)}\PYG{p}{;}
  920 \PYG{k}{return} \PYG{n}{ret}\PYG{p}{;}
  921 \end{sphinxVerbatim}
  922 
  923 
  924 \section{Getting anonymous credentials}
  925 \label{\detokenize{appdev/init_creds:getting-anonymous-credentials}}
  926 As of release 1.8, it is possible to obtain fully anonymous or
  927 partially anonymous (realm-exposed) credentials, if the KDC supports
  928 it.  The MIT KDC supports issuing fully anonymous credentials as of
  929 release 1.8 if configured appropriately (see \DUrole{xref,std,std-ref}{anonymous\_pkinit}),
  930 but does not support issuing realm-exposed anonymous credentials at
  931 this time.
  932 
  933 To obtain fully anonymous credentials, call
  934 {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_anonymous:c.krb5_get_init_creds_opt_set_anonymous}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_set\_anonymous()}}}} on the options
  935 structure to set the anonymous flag, and specify a client principal
  936 with the KDC’s realm and a single empty data component (the principal
  937 obtained by parsing \sphinxcode{@}\sphinxstyleemphasis{realmname}).  Authentication will take
  938 place using anonymous PKINIT; if successful, the client principal of
  939 the resulting tickets will be
  940 \sphinxcode{WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS}.  Here is an example:
  941 
  942 \fvset{hllines={, ,}}%
  943 \begin{sphinxVerbatim}[commandchars=\\\{\}]
  944 \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}set\PYGZus{}anonymous}\PYG{p}{(}\PYG{n}{opt}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{p}{;}
  945 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}build\PYGZus{}principal}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{client\PYGZus{}princ}\PYG{p}{,} \PYG{n}{strlen}\PYG{p}{(}\PYG{n}{myrealm}\PYG{p}{)}\PYG{p}{,}
  946                            \PYG{n}{myrealm}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{p}{(}\PYG{n}{char} \PYG{o}{*}\PYG{p}{)}\PYG{n}{NULL}\PYG{p}{)}\PYG{p}{;}
  947 \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
  948     \PYG{n}{goto} \PYG{n}{cleanup}\PYG{p}{;}
  949 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}password}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{n}{client\PYGZus{}princ}\PYG{p}{,}
  950                                    \PYG{n}{password}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{opt}\PYG{p}{)}\PYG{p}{;}
  951 \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
  952     \PYG{n}{goto} \PYG{n}{cleanup}\PYG{p}{;}
  953 \end{sphinxVerbatim}
  954 
  955 To obtain realm-exposed anonymous credentials, set the anonymous flag
  956 on the options structure as above, but specify a normal client
  957 principal in order to prove membership in the realm.  Authentication
  958 will take place as it normally does; if successful, the client
  959 principal of the resulting tickets will be \sphinxcode{WELLKNOWN/ANONYMOUS@}\sphinxstyleemphasis{realmname}.
  960 
  961 
  962 \section{User interaction}
  963 \label{\detokenize{appdev/init_creds:user-interaction}}
  964 Authenticating a user usually requires the entry of secret
  965 information, such as a password.  A password can be supplied directly
  966 to {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_password()}}}} via the \sphinxstyleemphasis{password}
  967 parameter, or the application can supply prompter and/or responder
  968 callbacks instead.  If callbacks are used, the user can also be
  969 queried for other secret information such as a PIN, informed of
  970 impending password expiration, or prompted to change a password which
  971 has expired.
  972 
  973 
  974 \subsection{Prompter callback}
  975 \label{\detokenize{appdev/init_creds:prompter-callback}}
  976 A prompter callback can be specified via the \sphinxstyleemphasis{prompter} and \sphinxstyleemphasis{data}
  977 parameters to {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_password()}}}}.  The prompter
  978 will be invoked each time the krb5 library has a question to ask or
  979 information to present.  When the prompter callback is invoked, the
  980 \sphinxstyleemphasis{banner} argument (if not null) is intended to be displayed to the
  981 user, and the questions to be answered are specified in the \sphinxstyleemphasis{prompts}
  982 array.  Each prompt contains a text question in the \sphinxstyleemphasis{prompt} field, a
  983 \sphinxstyleemphasis{hidden} bit to indicate whether the answer should be hidden from
  984 display, and a storage area for the answer in the \sphinxstyleemphasis{reply} field.  The
  985 callback should fill in each question’s \sphinxcode{reply-\textgreater{}data} with the
  986 answer, up to a maximum number of \sphinxcode{reply-\textgreater{}length} bytes, and then
  987 reset \sphinxcode{reply-\textgreater{}length} to the length of the answer.
  988 
  989 A prompter callback can call {\hyperref[\detokenize{appdev/refs/api/krb5_get_prompt_types:c.krb5_get_prompt_types}]{\sphinxcrossref{\sphinxcode{krb5\_get\_prompt\_types()}}}} to get an
  990 array of type constants corresponding to the prompts, to get
  991 programmatic information about the semantic meaning of the questions.
  992 {\hyperref[\detokenize{appdev/refs/api/krb5_get_prompt_types:c.krb5_get_prompt_types}]{\sphinxcrossref{\sphinxcode{krb5\_get\_prompt\_types()}}}} may return a null pointer if no prompt
  993 type information is available.
  994 
  995 Text-based applications can use a built-in text prompter
  996 implementation by supplying {\hyperref[\detokenize{appdev/refs/api/krb5_prompter_posix:c.krb5_prompter_posix}]{\sphinxcrossref{\sphinxcode{krb5\_prompter\_posix()}}}} as the
  997 \sphinxstyleemphasis{prompter} parameter and a null pointer as the \sphinxstyleemphasis{data} parameter.  For
  998 example:
  999 
 1000 \fvset{hllines={, ,}}%
 1001 \begin{sphinxVerbatim}[commandchars=\\\{\}]
 1002 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}password}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{n}{client\PYGZus{}princ}\PYG{p}{,}
 1003                                    \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{krb5\PYGZus{}prompter\PYGZus{}posix}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,}
 1004                                    \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{)}\PYG{p}{;}
 1005 \end{sphinxVerbatim}
 1006 
 1007 
 1008 \subsection{Responder callback}
 1009 \label{\detokenize{appdev/init_creds:responder-callback}}
 1010 A responder callback can be specified through the init\_creds options
 1011 using the {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_responder:c.krb5_get_init_creds_opt_set_responder}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_set\_responder()}}}} function.
 1012 Responder callbacks can present a more sophisticated user interface
 1013 for authentication secrets.  The responder callback is usually invoked
 1014 only once per authentication, with a list of questions produced by all
 1015 of the allowed preauthentication mechanisms.
 1016 
 1017 When the responder callback is invoked, the \sphinxstyleemphasis{rctx} argument can be
 1018 accessed to obtain the list of questions and to answer them.  The
 1019 {\hyperref[\detokenize{appdev/refs/api/krb5_responder_list_questions:c.krb5_responder_list_questions}]{\sphinxcrossref{\sphinxcode{krb5\_responder\_list\_questions()}}}} function retrieves an array of
 1020 question types.  For each question type, the
 1021 {\hyperref[\detokenize{appdev/refs/api/krb5_responder_get_challenge:c.krb5_responder_get_challenge}]{\sphinxcrossref{\sphinxcode{krb5\_responder\_get\_challenge()}}}} function retrieves additional
 1022 information about the question, if applicable, and the
 1023 {\hyperref[\detokenize{appdev/refs/api/krb5_responder_set_answer:c.krb5_responder_set_answer}]{\sphinxcrossref{\sphinxcode{krb5\_responder\_set\_answer()}}}} function sets the answer.
 1024 
 1025 Responder question types, challenges, and answers are UTF-8 strings.
 1026 The question type is a well-known string; the meaning of the challenge
 1027 and answer depend on the question type.  If an application does not
 1028 understand a question type, it cannot interpret the challenge or
 1029 provide an answer.  Failing to answer a question typically results in
 1030 the prompter callback being used as a fallback.
 1031 
 1032 
 1033 \subsubsection{Password question}
 1034 \label{\detokenize{appdev/init_creds:password-question}}
 1035 The \sphinxcode{KRB5\_RESPONDER\_QUESTION\_PASSWORD} (or \sphinxcode{"password"})
 1036 question type requests the user’s password.  This question does not
 1037 have a challenge, and the response is simply the password string.
 1038 
 1039 
 1040 \subsubsection{One-time password question}
 1041 \label{\detokenize{appdev/init_creds:one-time-password-question}}
 1042 The \sphinxcode{KRB5\_RESPONDER\_QUESTION\_OTP} (or \sphinxcode{"otp"}) question
 1043 type requests a choice among one-time password tokens and the PIN and
 1044 value for the chosen token.  The challenge and answer are JSON-encoded
 1045 strings, but an application can use convenience functions to avoid
 1046 doing any JSON processing itself.
 1047 
 1048 The {\hyperref[\detokenize{appdev/refs/api/krb5_responder_otp_get_challenge:c.krb5_responder_otp_get_challenge}]{\sphinxcrossref{\sphinxcode{krb5\_responder\_otp\_get\_challenge()}}}} function decodes the
 1049 challenge into a krb5\_responder\_otp\_challenge structure.  The
 1050 {\hyperref[\detokenize{appdev/refs/api/krb5_responder_otp_set_answer:c.krb5_responder_otp_set_answer}]{\sphinxcrossref{\sphinxcode{krb5\_responder\_otp\_set\_answer()}}}} function selects one of the
 1051 token information elements from the challenge and supplies the value
 1052 and pin for that token.
 1053 
 1054 
 1055 \subsubsection{PKINIT password or PIN question}
 1056 \label{\detokenize{appdev/init_creds:pkinit-password-or-pin-question}}
 1057 The \sphinxcode{KRB5\_RESPONDER\_QUESTION\_PKINIT} (or \sphinxcode{"pkinit"}) question
 1058 type requests PINs for hardware devices and/or passwords for encrypted
 1059 credentials which are stored on disk, potentially also supplying
 1060 information about the state of the hardware devices.  The challenge and
 1061 answer are JSON-encoded strings, but an application can use convenience
 1062 functions to avoid doing any JSON processing itself.
 1063 
 1064 The {\hyperref[\detokenize{appdev/refs/api/krb5_responder_pkinit_get_challenge:c.krb5_responder_pkinit_get_challenge}]{\sphinxcrossref{\sphinxcode{krb5\_responder\_pkinit\_get\_challenge()}}}} function decodes the
 1065 challenges into a krb5\_responder\_pkinit\_challenge structure.  The
 1066 {\hyperref[\detokenize{appdev/refs/api/krb5_responder_pkinit_set_answer:c.krb5_responder_pkinit_set_answer}]{\sphinxcrossref{\sphinxcode{krb5\_responder\_pkinit\_set\_answer()}}}} function can be used to
 1067 supply the PIN or password for a particular client credential, and can
 1068 be called multiple times.
 1069 
 1070 
 1071 \subsubsection{Example}
 1072 \label{\detokenize{appdev/init_creds:example}}
 1073 Here is an example of using a responder callback:
 1074 
 1075 \fvset{hllines={, ,}}%
 1076 \begin{sphinxVerbatim}[commandchars=\\\{\}]
 1077 \PYG{n}{static} \PYG{n}{krb5\PYGZus{}error\PYGZus{}code}
 1078 \PYG{n}{my\PYGZus{}responder}\PYG{p}{(}\PYG{n}{krb5\PYGZus{}context} \PYG{n}{context}\PYG{p}{,} \PYG{n}{void} \PYG{o}{*}\PYG{n}{data}\PYG{p}{,}
 1079              \PYG{n}{krb5\PYGZus{}responder\PYGZus{}context} \PYG{n}{rctx}\PYG{p}{)}
 1080 \PYG{p}{\PYGZob{}}
 1081     \PYG{n}{krb5\PYGZus{}error\PYGZus{}code} \PYG{n}{ret}\PYG{p}{;}
 1082     \PYG{n}{krb5\PYGZus{}responder\PYGZus{}otp\PYGZus{}challenge} \PYG{o}{*}\PYG{n}{chl}\PYG{p}{;}
 1083 
 1084     \PYG{k}{if} \PYG{p}{(}\PYG{n}{krb5\PYGZus{}responder\PYGZus{}get\PYGZus{}challenge}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{rctx}\PYG{p}{,}
 1085                                      \PYG{n}{KRB5\PYGZus{}RESPONDER\PYGZus{}QUESTION\PYGZus{}PASSWORD}\PYG{p}{)}\PYG{p}{)} \PYG{p}{\PYGZob{}}
 1086         \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}responder\PYGZus{}set\PYGZus{}answer}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{rctx}\PYG{p}{,}
 1087                                         \PYG{n}{KRB5\PYGZus{}RESPONDER\PYGZus{}QUESTION\PYGZus{}PASSWORD}\PYG{p}{,}
 1088                                         \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{open sesame}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
 1089         \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
 1090             \PYG{k}{return} \PYG{n}{ret}\PYG{p}{;}
 1091     \PYG{p}{\PYGZcb{}}
 1092     \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}responder\PYGZus{}otp\PYGZus{}get\PYGZus{}challenge}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{rctx}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{chl}\PYG{p}{)}\PYG{p}{;}
 1093     \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret} \PYG{o}{==} \PYG{l+m+mi}{0} \PYG{o}{\PYGZam{}}\PYG{o}{\PYGZam{}} \PYG{n}{chl} \PYG{o}{!=} \PYG{n}{NULL}\PYG{p}{)} \PYG{p}{\PYGZob{}}
 1094         \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}responder\PYGZus{}otp\PYGZus{}set\PYGZus{}answer}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{rctx}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{1234}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
 1095                                             \PYG{n}{NULL}\PYG{p}{)}\PYG{p}{;}
 1096         \PYG{n}{krb5\PYGZus{}responder\PYGZus{}otp\PYGZus{}challenge\PYGZus{}free}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{rctx}\PYG{p}{,} \PYG{n}{chl}\PYG{p}{)}\PYG{p}{;}
 1097         \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
 1098             \PYG{k}{return} \PYG{n}{ret}\PYG{p}{;}
 1099     \PYG{p}{\PYGZcb{}}
 1100     \PYG{k}{return} \PYG{l+m+mi}{0}\PYG{p}{;}
 1101 \PYG{p}{\PYGZcb{}}
 1102 
 1103 \PYG{n}{static} \PYG{n}{krb5\PYGZus{}error\PYGZus{}code}
 1104 \PYG{n}{get\PYGZus{}creds}\PYG{p}{(}\PYG{n}{krb5\PYGZus{}context} \PYG{n}{context}\PYG{p}{,} \PYG{n}{krb5\PYGZus{}principal} \PYG{n}{client\PYGZus{}princ}\PYG{p}{)}
 1105 \PYG{p}{\PYGZob{}}
 1106     \PYG{n}{krb5\PYGZus{}error\PYGZus{}code} \PYG{n}{ret}\PYG{p}{;}
 1107     \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt} \PYG{o}{*}\PYG{n}{opt} \PYG{o}{=} \PYG{n}{NULL}\PYG{p}{;}
 1108     \PYG{n}{krb5\PYGZus{}creds} \PYG{n}{creds}\PYG{p}{;}
 1109 
 1110     \PYG{n}{memset}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{sizeof}\PYG{p}{(}\PYG{n}{creds}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
 1111     \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}alloc}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{opt}\PYG{p}{)}\PYG{p}{;}
 1112     \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
 1113         \PYG{n}{goto} \PYG{n}{cleanup}\PYG{p}{;}
 1114     \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}set\PYGZus{}responder}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{opt}\PYG{p}{,} \PYG{n}{my\PYGZus{}responder}\PYG{p}{,}
 1115                                                 \PYG{n}{NULL}\PYG{p}{)}\PYG{p}{;}
 1116     \PYG{k}{if} \PYG{p}{(}\PYG{n}{ret}\PYG{p}{)}
 1117         \PYG{n}{goto} \PYG{n}{cleanup}\PYG{p}{;}
 1118     \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}password}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{n}{client\PYGZus{}princ}\PYG{p}{,}
 1119                                        \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{l+m+mi}{0}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{opt}\PYG{p}{)}\PYG{p}{;}
 1120 
 1121 \PYG{n}{cleanup}\PYG{p}{:}
 1122     \PYG{n}{krb5\PYGZus{}get\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}free}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{opt}\PYG{p}{)}\PYG{p}{;}
 1123     \PYG{n}{krb5\PYGZus{}free\PYGZus{}cred\PYGZus{}contents}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{)}\PYG{p}{;}
 1124     \PYG{k}{return} \PYG{n}{ret}\PYG{p}{;}
 1125 \PYG{p}{\PYGZcb{}}
 1126 \end{sphinxVerbatim}
 1127 
 1128 
 1129 \section{Verifying initial credentials}
 1130 \label{\detokenize{appdev/init_creds:verifying-initial-credentials}}
 1131 Use the function {\hyperref[\detokenize{appdev/refs/api/krb5_verify_init_creds:c.krb5_verify_init_creds}]{\sphinxcrossref{\sphinxcode{krb5\_verify\_init\_creds()}}}} to verify initial
 1132 credentials.  It takes an options structure (which can be a null
 1133 pointer).  Use {\hyperref[\detokenize{appdev/refs/api/krb5_verify_init_creds_opt_init:c.krb5_verify_init_creds_opt_init}]{\sphinxcrossref{\sphinxcode{krb5\_verify\_init\_creds\_opt\_init()}}}} to initialize
 1134 the caller-allocated options structure, and
 1135 {\hyperref[\detokenize{appdev/refs/api/krb5_verify_init_creds_opt_set_ap_req_nofail:c.krb5_verify_init_creds_opt_set_ap_req_nofail}]{\sphinxcrossref{\sphinxcode{krb5\_verify\_init\_creds\_opt\_set\_ap\_req\_nofail()}}}} to set the
 1136 “nofail” option.  For example:
 1137 
 1138 \fvset{hllines={, ,}}%
 1139 \begin{sphinxVerbatim}[commandchars=\\\{\}]
 1140 \PYG{n}{krb5\PYGZus{}verify\PYGZus{}init\PYGZus{}creds\PYGZus{}opt} \PYG{n}{vopt}\PYG{p}{;}
 1141 
 1142 \PYG{n}{krb5\PYGZus{}verify\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}init}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{vopt}\PYG{p}{)}\PYG{p}{;}
 1143 \PYG{n}{krb5\PYGZus{}verify\PYGZus{}init\PYGZus{}creds\PYGZus{}opt\PYGZus{}set\PYGZus{}ap\PYGZus{}req\PYGZus{}nofail}\PYG{p}{(}\PYG{o}{\PYGZam{}}\PYG{n}{vopt}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{p}{;}
 1144 \PYG{n}{ret} \PYG{o}{=} \PYG{n}{krb5\PYGZus{}verify\PYGZus{}init\PYGZus{}creds}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{creds}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{n}{NULL}\PYG{p}{,} \PYG{o}{\PYGZam{}}\PYG{n}{vopt}\PYG{p}{)}\PYG{p}{;}
 1145 \end{sphinxVerbatim}
 1146 
 1147 The confusingly named “nofail” option, when set, means that the
 1148 verification must actually succeed in order for
 1149 {\hyperref[\detokenize{appdev/refs/api/krb5_verify_init_creds:c.krb5_verify_init_creds}]{\sphinxcrossref{\sphinxcode{krb5\_verify\_init\_creds()}}}} to indicate success.  The default
 1150 state of this option (cleared) means that if there is no key material
 1151 available to verify the user credentials, the verification will
 1152 succeed anyway.  (The default can be changed by a configuration file
 1153 setting.)
 1154 
 1155 This accommodates a use case where a large number of unkeyed shared
 1156 desktop workstations need to allow users to log in using Kerberos.
 1157 The security risks from this practice are mitigated by the absence of
 1158 valuable state on the shared workstations—any valuable resources
 1159 that the users would access reside on networked servers.
 1160 
 1161 
 1162 \chapter{Principal manipulation and parsing}
 1163 \label{\detokenize{appdev/princ_handle:principal-manipulation-and-parsing}}\label{\detokenize{appdev/princ_handle::doc}}
 1164 Kerberos principal structure
 1165 
 1166 {\hyperref[\detokenize{appdev/refs/types/krb5_principal_data:c.krb5_principal_data}]{\sphinxcrossref{\sphinxcode{krb5\_principal\_data}}}}
 1167 
 1168 {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{\sphinxcode{krb5\_principal}}}}
 1169 
 1170 Create and free principal
 1171 
 1172 {\hyperref[\detokenize{appdev/refs/api/krb5_build_principal:c.krb5_build_principal}]{\sphinxcrossref{\sphinxcode{krb5\_build\_principal()}}}}
 1173 
 1174 {\hyperref[\detokenize{appdev/refs/api/krb5_build_principal_alloc_va:c.krb5_build_principal_alloc_va}]{\sphinxcrossref{\sphinxcode{krb5\_build\_principal\_alloc\_va()}}}}
 1175 
 1176 {\hyperref[\detokenize{appdev/refs/api/krb5_build_principal_ext:c.krb5_build_principal_ext}]{\sphinxcrossref{\sphinxcode{krb5\_build\_principal\_ext()}}}}
 1177 
 1178 {\hyperref[\detokenize{appdev/refs/api/krb5_copy_principal:c.krb5_copy_principal}]{\sphinxcrossref{\sphinxcode{krb5\_copy\_principal()}}}}
 1179 
 1180 {\hyperref[\detokenize{appdev/refs/api/krb5_free_principal:c.krb5_free_principal}]{\sphinxcrossref{\sphinxcode{krb5\_free\_principal()}}}}
 1181 
 1182 {\hyperref[\detokenize{appdev/refs/api/krb5_cc_get_principal:c.krb5_cc_get_principal}]{\sphinxcrossref{\sphinxcode{krb5\_cc\_get\_principal()}}}}
 1183 
 1184 Comparing
 1185 
 1186 {\hyperref[\detokenize{appdev/refs/api/krb5_principal_compare:c.krb5_principal_compare}]{\sphinxcrossref{\sphinxcode{krb5\_principal\_compare()}}}}
 1187 
 1188 {\hyperref[\detokenize{appdev/refs/api/krb5_principal_compare_flags:c.krb5_principal_compare_flags}]{\sphinxcrossref{\sphinxcode{krb5\_principal\_compare\_flags()}}}}
 1189 
 1190 {\hyperref[\detokenize{appdev/refs/api/krb5_principal_compare_any_realm:c.krb5_principal_compare_any_realm}]{\sphinxcrossref{\sphinxcode{krb5\_principal\_compare\_any\_realm()}}}}
 1191 
 1192 {\hyperref[\detokenize{appdev/refs/api/krb5_sname_match:c.krb5_sname_match}]{\sphinxcrossref{\sphinxcode{krb5\_sname\_match()}}}}
 1193 
 1194 {\hyperref[\detokenize{appdev/refs/api/krb5_sname_to_principal:c.krb5_sname_to_principal}]{\sphinxcrossref{\sphinxcode{krb5\_sname\_to\_principal()}}}}
 1195 
 1196 Parsing:
 1197 
 1198 {\hyperref[\detokenize{appdev/refs/api/krb5_parse_name:c.krb5_parse_name}]{\sphinxcrossref{\sphinxcode{krb5\_parse\_name()}}}}
 1199 
 1200 {\hyperref[\detokenize{appdev/refs/api/krb5_parse_name_flags:c.krb5_parse_name_flags}]{\sphinxcrossref{\sphinxcode{krb5\_parse\_name\_flags()}}}}
 1201 
 1202 {\hyperref[\detokenize{appdev/refs/api/krb5_unparse_name:c.krb5_unparse_name}]{\sphinxcrossref{\sphinxcode{krb5\_unparse\_name()}}}}
 1203 
 1204 {\hyperref[\detokenize{appdev/refs/api/krb5_unparse_name_flags:c.krb5_unparse_name_flags}]{\sphinxcrossref{\sphinxcode{krb5\_unparse\_name\_flags()}}}}
 1205 
 1206 Utilities:
 1207 
 1208 {\hyperref[\detokenize{appdev/refs/api/krb5_is_config_principal:c.krb5_is_config_principal}]{\sphinxcrossref{\sphinxcode{krb5\_is\_config\_principal()}}}}
 1209 
 1210 {\hyperref[\detokenize{appdev/refs/api/krb5_kuserok:c.krb5_kuserok}]{\sphinxcrossref{\sphinxcode{krb5\_kuserok()}}}}
 1211 
 1212 {\hyperref[\detokenize{appdev/refs/api/krb5_set_password:c.krb5_set_password}]{\sphinxcrossref{\sphinxcode{krb5\_set\_password()}}}}
 1213 
 1214 {\hyperref[\detokenize{appdev/refs/api/krb5_set_password_using_ccache:c.krb5_set_password_using_ccache}]{\sphinxcrossref{\sphinxcode{krb5\_set\_password\_using\_ccache()}}}}
 1215 
 1216 {\hyperref[\detokenize{appdev/refs/api/krb5_set_principal_realm:c.krb5_set_principal_realm}]{\sphinxcrossref{\sphinxcode{krb5\_set\_principal\_realm()}}}}
 1217 
 1218 {\hyperref[\detokenize{appdev/refs/api/krb5_realm_compare:c.krb5_realm_compare}]{\sphinxcrossref{\sphinxcode{krb5\_realm\_compare()}}}}
 1219 
 1220 
 1221 \chapter{Complete reference - API and datatypes}
 1222 \label{\detokenize{appdev/refs/index:complete-reference-api-and-datatypes}}\label{\detokenize{appdev/refs/index::doc}}
 1223 
 1224 \section{krb5 API}
 1225 \label{\detokenize{appdev/refs/api/index:krb5-api}}\label{\detokenize{appdev/refs/api/index::doc}}
 1226 
 1227 \subsection{Frequently used public interfaces}
 1228 \label{\detokenize{appdev/refs/api/index:frequently-used-public-interfaces}}
 1229 
 1230 \subsubsection{krb5\_build\_principal -  Build a principal name using null-terminated strings.}
 1231 \label{\detokenize{appdev/refs/api/krb5_build_principal:krb5-build-principal-build-a-principal-name-using-null-terminated-strings}}\label{\detokenize{appdev/refs/api/krb5_build_principal::doc}}\index{krb5\_build\_principal (C function)}
 1232 
 1233 \begin{fulllineitems}
 1234 \phantomsection\label{\detokenize{appdev/refs/api/krb5_build_principal:c.krb5_build_principal}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_build\_principal}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}} *\sphinxstyleemphasis{ princ}, unsigned int\sphinxstyleemphasis{ rlen}, const char *\sphinxstyleemphasis{ realm}, ...}{}
 1235 \end{fulllineitems}
 1236 
 1237 \begin{quote}\begin{description}
 1238 \item[{param}] \leavevmode
 1239 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1240 
 1241 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{princ} - Principal name
 1242 
 1243 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{rlen} - Realm name length
 1244 
 1245 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{realm} - Realm name
 1246 
 1247 \end{description}\end{quote}
 1248 \begin{quote}\begin{description}
 1249 \item[{retval}] \leavevmode\begin{itemize}
 1250 \item {} 
 1251 0   Success
 1252 
 1253 \end{itemize}
 1254 
 1255 \item[{return}] \leavevmode\begin{itemize}
 1256 \item {} 
 1257 Kerberos error codes
 1258 
 1259 \end{itemize}
 1260 
 1261 \end{description}\end{quote}
 1262 
 1263 Call {\hyperref[\detokenize{appdev/refs/api/krb5_free_principal:c.krb5_free_principal}]{\sphinxcrossref{\sphinxcode{krb5\_free\_principal()}}}} to free \sphinxstyleemphasis{princ} when it is no longer needed.
 1264 
 1265 \begin{sphinxadmonition}{note}{Note:}
 1266 {\hyperref[\detokenize{appdev/refs/api/krb5_build_principal:c.krb5_build_principal}]{\sphinxcrossref{\sphinxcode{krb5\_build\_principal()}}}} and {\hyperref[\detokenize{appdev/refs/api/krb5_build_principal_alloc_va:c.krb5_build_principal_alloc_va}]{\sphinxcrossref{\sphinxcode{krb5\_build\_principal\_alloc\_va()}}}} perform the same task. {\hyperref[\detokenize{appdev/refs/api/krb5_build_principal:c.krb5_build_principal}]{\sphinxcrossref{\sphinxcode{krb5\_build\_principal()}}}} takes variadic arguments. {\hyperref[\detokenize{appdev/refs/api/krb5_build_principal_alloc_va:c.krb5_build_principal_alloc_va}]{\sphinxcrossref{\sphinxcode{krb5\_build\_principal\_alloc\_va()}}}} takes a pre-computed \sphinxstyleemphasis{varargs} pointer.
 1267 \end{sphinxadmonition}
 1268 
 1269 
 1270 \subsubsection{krb5\_build\_principal\_alloc\_va -  Build a principal name, using a precomputed variable argument list.}
 1271 \label{\detokenize{appdev/refs/api/krb5_build_principal_alloc_va:krb5-build-principal-alloc-va-build-a-principal-name-using-a-precomputed-variable-argument-list}}\label{\detokenize{appdev/refs/api/krb5_build_principal_alloc_va::doc}}\index{krb5\_build\_principal\_alloc\_va (C function)}
 1272 
 1273 \begin{fulllineitems}
 1274 \phantomsection\label{\detokenize{appdev/refs/api/krb5_build_principal_alloc_va:c.krb5_build_principal_alloc_va}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_build\_principal\_alloc\_va}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}} *\sphinxstyleemphasis{ princ}, unsigned int\sphinxstyleemphasis{ rlen}, const char *\sphinxstyleemphasis{ realm}, va\_list\sphinxstyleemphasis{ ap}}{}
 1275 \end{fulllineitems}
 1276 
 1277 \begin{quote}\begin{description}
 1278 \item[{param}] \leavevmode
 1279 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1280 
 1281 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{princ} - Principal structure
 1282 
 1283 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{rlen} - Realm name length
 1284 
 1285 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{realm} - Realm name
 1286 
 1287 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ap} - List of char * components, ending with NULL
 1288 
 1289 \end{description}\end{quote}
 1290 \begin{quote}\begin{description}
 1291 \item[{retval}] \leavevmode\begin{itemize}
 1292 \item {} 
 1293 0   Success
 1294 
 1295 \end{itemize}
 1296 
 1297 \item[{return}] \leavevmode\begin{itemize}
 1298 \item {} 
 1299 Kerberos error codes
 1300 
 1301 \end{itemize}
 1302 
 1303 \end{description}\end{quote}
 1304 
 1305 Similar to {\hyperref[\detokenize{appdev/refs/api/krb5_build_principal:c.krb5_build_principal}]{\sphinxcrossref{\sphinxcode{krb5\_build\_principal()}}}} , this function builds a principal name, but its name components are specified as a va\_list.
 1306 
 1307 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_principal:c.krb5_free_principal}]{\sphinxcrossref{\sphinxcode{krb5\_free\_principal()}}}} to deallocate \sphinxstyleemphasis{princ} when it is no longer needed.
 1308 
 1309 
 1310 \subsubsection{krb5\_build\_principal\_ext -  Build a principal name using length-counted strings.}
 1311 \label{\detokenize{appdev/refs/api/krb5_build_principal_ext:krb5-build-principal-ext-build-a-principal-name-using-length-counted-strings}}\label{\detokenize{appdev/refs/api/krb5_build_principal_ext::doc}}\index{krb5\_build\_principal\_ext (C function)}
 1312 
 1313 \begin{fulllineitems}
 1314 \phantomsection\label{\detokenize{appdev/refs/api/krb5_build_principal_ext:c.krb5_build_principal_ext}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_build\_principal\_ext}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}} *\sphinxstyleemphasis{ princ}, unsigned int\sphinxstyleemphasis{ rlen}, const char *\sphinxstyleemphasis{ realm}, ...}{}
 1315 \end{fulllineitems}
 1316 
 1317 \begin{quote}\begin{description}
 1318 \item[{param}] \leavevmode
 1319 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1320 
 1321 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{princ} - Principal name
 1322 
 1323 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{rlen} - Realm name length
 1324 
 1325 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{realm} - Realm name
 1326 
 1327 \end{description}\end{quote}
 1328 \begin{quote}\begin{description}
 1329 \item[{retval}] \leavevmode\begin{itemize}
 1330 \item {} 
 1331 0   Success
 1332 
 1333 \end{itemize}
 1334 
 1335 \item[{return}] \leavevmode\begin{itemize}
 1336 \item {} 
 1337 Kerberos error codes
 1338 
 1339 \end{itemize}
 1340 
 1341 \end{description}\end{quote}
 1342 
 1343 This function creates a principal from a length-counted string and a variable-length list of length-counted components. The list of components ends with the first 0 length argument (so it is not possible to specify an empty component with this function). Call {\hyperref[\detokenize{appdev/refs/api/krb5_free_principal:c.krb5_free_principal}]{\sphinxcrossref{\sphinxcode{krb5\_free\_principal()}}}} to free allocated memory for principal when it is no longer needed.
 1344 
 1345 
 1346 \subsubsection{krb5\_cc\_close -  Close a credential cache handle.}
 1347 \label{\detokenize{appdev/refs/api/krb5_cc_close:krb5-cc-close-close-a-credential-cache-handle}}\label{\detokenize{appdev/refs/api/krb5_cc_close::doc}}\index{krb5\_cc\_close (C function)}
 1348 
 1349 \begin{fulllineitems}
 1350 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_close:c.krb5_cc_close}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_cc\_close}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ cache}}{}
 1351 \end{fulllineitems}
 1352 
 1353 \begin{quote}\begin{description}
 1354 \item[{param}] \leavevmode
 1355 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1356 
 1357 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{cache} - Credential cache handle
 1358 
 1359 \end{description}\end{quote}
 1360 \begin{quote}\begin{description}
 1361 \item[{retval}] \leavevmode\begin{itemize}
 1362 \item {} 
 1363 0   Success
 1364 
 1365 \end{itemize}
 1366 
 1367 \item[{return}] \leavevmode\begin{itemize}
 1368 \item {} 
 1369 Kerberos error codes
 1370 
 1371 \end{itemize}
 1372 
 1373 \end{description}\end{quote}
 1374 
 1375 This function closes a credential cache handle \sphinxstyleemphasis{cache} without affecting the contents of the cache.
 1376 
 1377 
 1378 \subsubsection{krb5\_cc\_default -  Resolve the default credential cache name.}
 1379 \label{\detokenize{appdev/refs/api/krb5_cc_default::doc}}\label{\detokenize{appdev/refs/api/krb5_cc_default:krb5-cc-default-resolve-the-default-credential-cache-name}}\index{krb5\_cc\_default (C function)}
 1380 
 1381 \begin{fulllineitems}
 1382 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_default:c.krb5_cc_default}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_cc\_default}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}} *\sphinxstyleemphasis{ ccache}}{}
 1383 \end{fulllineitems}
 1384 
 1385 \begin{quote}\begin{description}
 1386 \item[{param}] \leavevmode
 1387 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1388 
 1389 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{ccache} - Pointer to credential cache name
 1390 
 1391 \end{description}\end{quote}
 1392 \begin{quote}\begin{description}
 1393 \item[{retval}] \leavevmode\begin{itemize}
 1394 \item {} 
 1395 0   Success
 1396 
 1397 \item {} 
 1398 KV5M\_CONTEXT   Bad magic number for \_krb5\_context structure
 1399 
 1400 \item {} 
 1401 KRB5\_FCC\_INTERNAL   The name of the default credential cache cannot be obtained
 1402 
 1403 \end{itemize}
 1404 
 1405 \item[{return}] \leavevmode\begin{itemize}
 1406 \item {} 
 1407 Kerberos error codes
 1408 
 1409 \end{itemize}
 1410 
 1411 \end{description}\end{quote}
 1412 
 1413 Create a handle to the default credential cache as given by {\hyperref[\detokenize{appdev/refs/api/krb5_cc_default_name:c.krb5_cc_default_name}]{\sphinxcrossref{\sphinxcode{krb5\_cc\_default\_name()}}}} .
 1414 
 1415 
 1416 \subsubsection{krb5\_cc\_default\_name -  Return the name of the default credential cache.}
 1417 \label{\detokenize{appdev/refs/api/krb5_cc_default_name::doc}}\label{\detokenize{appdev/refs/api/krb5_cc_default_name:krb5-cc-default-name-return-the-name-of-the-default-credential-cache}}\index{krb5\_cc\_default\_name (C function)}
 1418 
 1419 \begin{fulllineitems}
 1420 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_default_name:c.krb5_cc_default_name}}\pysiglinewithargsret{const char * \sphinxbfcode{krb5\_cc\_default\_name}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}}{}
 1421 \end{fulllineitems}
 1422 
 1423 \begin{quote}\begin{description}
 1424 \item[{param}] \leavevmode
 1425 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1426 
 1427 \end{description}\end{quote}
 1428 \begin{quote}\begin{description}
 1429 \item[{return}] \leavevmode\begin{itemize}
 1430 \item {} 
 1431 Name of default credential cache for the current user.
 1432 
 1433 \end{itemize}
 1434 
 1435 \end{description}\end{quote}
 1436 
 1437 Return a pointer to the default credential cache name for \sphinxstyleemphasis{context} , as determined by a prior call to {\hyperref[\detokenize{appdev/refs/api/krb5_cc_set_default_name:c.krb5_cc_set_default_name}]{\sphinxcrossref{\sphinxcode{krb5\_cc\_set\_default\_name()}}}} , by the KRB5CCNAME environment variable, by the default\_ccache\_name profile variable, or by the operating system or build-time default value. The returned value must not be modified or freed by the caller. The returned value becomes invalid when \sphinxstyleemphasis{context} is destroyed {\hyperref[\detokenize{appdev/refs/api/krb5_free_context:c.krb5_free_context}]{\sphinxcrossref{\sphinxcode{krb5\_free\_context()}}}} or if a subsequent call to {\hyperref[\detokenize{appdev/refs/api/krb5_cc_set_default_name:c.krb5_cc_set_default_name}]{\sphinxcrossref{\sphinxcode{krb5\_cc\_set\_default\_name()}}}} is made on \sphinxstyleemphasis{context} .
 1438 
 1439 The default credential cache name is cached in \sphinxstyleemphasis{context} between calls to this function, so if the value of KRB5CCNAME changes in the process environment after the first call to this function on, that change will not be reflected in later calls with the same context. The caller can invoke {\hyperref[\detokenize{appdev/refs/api/krb5_cc_set_default_name:c.krb5_cc_set_default_name}]{\sphinxcrossref{\sphinxcode{krb5\_cc\_set\_default\_name()}}}} with a NULL value of \sphinxstyleemphasis{name} to clear the cached value and force the default name to be recomputed.
 1440 
 1441 
 1442 \subsubsection{krb5\_cc\_destroy -  Destroy a credential cache.}
 1443 \label{\detokenize{appdev/refs/api/krb5_cc_destroy:krb5-cc-destroy-destroy-a-credential-cache}}\label{\detokenize{appdev/refs/api/krb5_cc_destroy::doc}}\index{krb5\_cc\_destroy (C function)}
 1444 
 1445 \begin{fulllineitems}
 1446 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_destroy:c.krb5_cc_destroy}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_cc\_destroy}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ cache}}{}
 1447 \end{fulllineitems}
 1448 
 1449 \begin{quote}\begin{description}
 1450 \item[{param}] \leavevmode
 1451 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1452 
 1453 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{cache} - Credential cache handle
 1454 
 1455 \end{description}\end{quote}
 1456 \begin{quote}\begin{description}
 1457 \item[{retval}] \leavevmode\begin{itemize}
 1458 \item {} 
 1459 0   Success
 1460 
 1461 \end{itemize}
 1462 
 1463 \item[{return}] \leavevmode\begin{itemize}
 1464 \item {} 
 1465 Permission errors
 1466 
 1467 \end{itemize}
 1468 
 1469 \end{description}\end{quote}
 1470 
 1471 This function destroys any existing contents of \sphinxstyleemphasis{cache} and closes the handle to it.
 1472 
 1473 
 1474 \subsubsection{krb5\_cc\_dup -  Duplicate ccache handle.}
 1475 \label{\detokenize{appdev/refs/api/krb5_cc_dup:krb5-cc-dup-duplicate-ccache-handle}}\label{\detokenize{appdev/refs/api/krb5_cc_dup::doc}}\index{krb5\_cc\_dup (C function)}
 1476 
 1477 \begin{fulllineitems}
 1478 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_dup:c.krb5_cc_dup}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_cc\_dup}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ in}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}} *\sphinxstyleemphasis{ out}}{}
 1479 \end{fulllineitems}
 1480 
 1481 \begin{quote}\begin{description}
 1482 \item[{param}] \leavevmode
 1483 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1484 
 1485 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{in} - Credential cache handle to be duplicated
 1486 
 1487 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{out} - Credential cache handle
 1488 
 1489 \end{description}\end{quote}
 1490 
 1491 Create a new handle referring to the same cache as \sphinxstyleemphasis{in} . The new handle and \sphinxstyleemphasis{in} can be closed independently.
 1492 
 1493 
 1494 \subsubsection{krb5\_cc\_get\_name -  Retrieve the name, but not type of a credential cache.}
 1495 \label{\detokenize{appdev/refs/api/krb5_cc_get_name::doc}}\label{\detokenize{appdev/refs/api/krb5_cc_get_name:krb5-cc-get-name-retrieve-the-name-but-not-type-of-a-credential-cache}}\index{krb5\_cc\_get\_name (C function)}
 1496 
 1497 \begin{fulllineitems}
 1498 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_get_name:c.krb5_cc_get_name}}\pysiglinewithargsret{const char * \sphinxbfcode{krb5\_cc\_get\_name}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ cache}}{}
 1499 \end{fulllineitems}
 1500 
 1501 \begin{quote}\begin{description}
 1502 \item[{param}] \leavevmode
 1503 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1504 
 1505 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{cache} - Credential cache handle
 1506 
 1507 \end{description}\end{quote}
 1508 \begin{quote}\begin{description}
 1509 \item[{return}] \leavevmode\begin{itemize}
 1510 \item {} 
 1511 On success - the name of the credential cache.
 1512 
 1513 \end{itemize}
 1514 
 1515 \end{description}\end{quote}
 1516 
 1517 \begin{sphinxadmonition}{warning}{Warning:}
 1518 Returns the name of the credential cache. The result is an alias into \sphinxstyleemphasis{cache} and should not be freed or modified by the caller. This name does not include the cache type, so should not be used as input to {\hyperref[\detokenize{appdev/refs/api/krb5_cc_resolve:c.krb5_cc_resolve}]{\sphinxcrossref{\sphinxcode{krb5\_cc\_resolve()}}}} .
 1519 \end{sphinxadmonition}
 1520 
 1521 
 1522 \subsubsection{krb5\_cc\_get\_principal -  Get the default principal of a credential cache.}
 1523 \label{\detokenize{appdev/refs/api/krb5_cc_get_principal:krb5-cc-get-principal-get-the-default-principal-of-a-credential-cache}}\label{\detokenize{appdev/refs/api/krb5_cc_get_principal::doc}}\index{krb5\_cc\_get\_principal (C function)}
 1524 
 1525 \begin{fulllineitems}
 1526 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_get_principal:c.krb5_cc_get_principal}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_cc\_get\_principal}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ cache}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}} *\sphinxstyleemphasis{ principal}}{}
 1527 \end{fulllineitems}
 1528 
 1529 \begin{quote}\begin{description}
 1530 \item[{param}] \leavevmode
 1531 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1532 
 1533 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{cache} - Credential cache handle
 1534 
 1535 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{principal} - Primary principal
 1536 
 1537 \end{description}\end{quote}
 1538 \begin{quote}\begin{description}
 1539 \item[{retval}] \leavevmode\begin{itemize}
 1540 \item {} 
 1541 0   Success
 1542 
 1543 \end{itemize}
 1544 
 1545 \item[{return}] \leavevmode\begin{itemize}
 1546 \item {} 
 1547 Kerberos error codes
 1548 
 1549 \end{itemize}
 1550 
 1551 \end{description}\end{quote}
 1552 
 1553 Returns the default client principal of a credential cache as set by {\hyperref[\detokenize{appdev/refs/api/krb5_cc_initialize:c.krb5_cc_initialize}]{\sphinxcrossref{\sphinxcode{krb5\_cc\_initialize()}}}} .
 1554 
 1555 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_principal:c.krb5_free_principal}]{\sphinxcrossref{\sphinxcode{krb5\_free\_principal()}}}} to free \sphinxstyleemphasis{principal} when it is no longer needed.
 1556 
 1557 
 1558 \subsubsection{krb5\_cc\_get\_type -  Retrieve the type of a credential cache.}
 1559 \label{\detokenize{appdev/refs/api/krb5_cc_get_type:krb5-cc-get-type-retrieve-the-type-of-a-credential-cache}}\label{\detokenize{appdev/refs/api/krb5_cc_get_type::doc}}\index{krb5\_cc\_get\_type (C function)}
 1560 
 1561 \begin{fulllineitems}
 1562 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_get_type:c.krb5_cc_get_type}}\pysiglinewithargsret{const char * \sphinxbfcode{krb5\_cc\_get\_type}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ cache}}{}
 1563 \end{fulllineitems}
 1564 
 1565 \begin{quote}\begin{description}
 1566 \item[{param}] \leavevmode
 1567 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1568 
 1569 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{cache} - Credential cache handle
 1570 
 1571 \end{description}\end{quote}
 1572 \begin{quote}\begin{description}
 1573 \item[{return}] \leavevmode\begin{itemize}
 1574 \item {} 
 1575 The type of a credential cache as an alias that must not be modified or freed by the caller.
 1576 
 1577 \end{itemize}
 1578 
 1579 \end{description}\end{quote}
 1580 
 1581 
 1582 \subsubsection{krb5\_cc\_initialize -  Initialize a credential cache.}
 1583 \label{\detokenize{appdev/refs/api/krb5_cc_initialize::doc}}\label{\detokenize{appdev/refs/api/krb5_cc_initialize:krb5-cc-initialize-initialize-a-credential-cache}}\index{krb5\_cc\_initialize (C function)}
 1584 
 1585 \begin{fulllineitems}
 1586 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_initialize:c.krb5_cc_initialize}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_cc\_initialize}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ cache}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ principal}}{}
 1587 \end{fulllineitems}
 1588 
 1589 \begin{quote}\begin{description}
 1590 \item[{param}] \leavevmode
 1591 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1592 
 1593 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{cache} - Credential cache handle
 1594 
 1595 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{principal} - Default principal name
 1596 
 1597 \end{description}\end{quote}
 1598 \begin{quote}\begin{description}
 1599 \item[{retval}] \leavevmode\begin{itemize}
 1600 \item {} 
 1601 0   Success
 1602 
 1603 \end{itemize}
 1604 
 1605 \item[{return}] \leavevmode\begin{itemize}
 1606 \item {} 
 1607 System errors; Permission errors; Kerberos error codes
 1608 
 1609 \end{itemize}
 1610 
 1611 \end{description}\end{quote}
 1612 
 1613 Destroy any existing contents of \sphinxstyleemphasis{cache} and initialize it for the default principal \sphinxstyleemphasis{principal} .
 1614 
 1615 
 1616 \subsubsection{krb5\_cc\_new\_unique -  Create a new credential cache of the specified type with a unique name.}
 1617 \label{\detokenize{appdev/refs/api/krb5_cc_new_unique:krb5-cc-new-unique-create-a-new-credential-cache-of-the-specified-type-with-a-unique-name}}\label{\detokenize{appdev/refs/api/krb5_cc_new_unique::doc}}\index{krb5\_cc\_new\_unique (C function)}
 1618 
 1619 \begin{fulllineitems}
 1620 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_new_unique:c.krb5_cc_new_unique}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_cc\_new\_unique}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, const char *\sphinxstyleemphasis{ type}, const char *\sphinxstyleemphasis{ hint}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}} *\sphinxstyleemphasis{ id}}{}
 1621 \end{fulllineitems}
 1622 
 1623 \begin{quote}\begin{description}
 1624 \item[{param}] \leavevmode
 1625 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1626 
 1627 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{type} - Credential cache type name
 1628 
 1629 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{hint} - Unused
 1630 
 1631 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{id} - Credential cache handle
 1632 
 1633 \end{description}\end{quote}
 1634 \begin{quote}\begin{description}
 1635 \item[{retval}] \leavevmode\begin{itemize}
 1636 \item {} 
 1637 0   Success
 1638 
 1639 \end{itemize}
 1640 
 1641 \item[{return}] \leavevmode\begin{itemize}
 1642 \item {} 
 1643 Kerberos error codes
 1644 
 1645 \end{itemize}
 1646 
 1647 \end{description}\end{quote}
 1648 
 1649 
 1650 \subsubsection{krb5\_cc\_resolve -  Resolve a credential cache name.}
 1651 \label{\detokenize{appdev/refs/api/krb5_cc_resolve:krb5-cc-resolve-resolve-a-credential-cache-name}}\label{\detokenize{appdev/refs/api/krb5_cc_resolve::doc}}\index{krb5\_cc\_resolve (C function)}
 1652 
 1653 \begin{fulllineitems}
 1654 \phantomsection\label{\detokenize{appdev/refs/api/krb5_cc_resolve:c.krb5_cc_resolve}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_cc\_resolve}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, const char *\sphinxstyleemphasis{ name}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}} *\sphinxstyleemphasis{ cache}}{}
 1655 \end{fulllineitems}
 1656 
 1657 \begin{quote}\begin{description}
 1658 \item[{param}] \leavevmode
 1659 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1660 
 1661 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{name} - Credential cache name to be resolved
 1662 
 1663 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{cache} - Credential cache handle
 1664 
 1665 \end{description}\end{quote}
 1666 \begin{quote}\begin{description}
 1667 \item[{retval}] \leavevmode\begin{itemize}
 1668 \item {} 
 1669 0   Success
 1670 
 1671 \end{itemize}
 1672 
 1673 \item[{return}] \leavevmode\begin{itemize}
 1674 \item {} 
 1675 Kerberos error codes
 1676 
 1677 \end{itemize}
 1678 
 1679 \end{description}\end{quote}
 1680 
 1681 Fills in \sphinxstyleemphasis{cache} with a \sphinxstyleemphasis{cache} handle that corresponds to the name in \sphinxstyleemphasis{name} . \sphinxstyleemphasis{name} should be of the form \sphinxstylestrong{type:residual} , and \sphinxstyleemphasis{type} must be a type known to the library. If the \sphinxstyleemphasis{name} does not contain a colon, interpret it as a file name.
 1682 
 1683 
 1684 \subsubsection{krb5\_change\_password -  Change a password for an existing Kerberos account.}
 1685 \label{\detokenize{appdev/refs/api/krb5_change_password:krb5-change-password-change-a-password-for-an-existing-kerberos-account}}\label{\detokenize{appdev/refs/api/krb5_change_password::doc}}\index{krb5\_change\_password (C function)}
 1686 
 1687 \begin{fulllineitems}
 1688 \phantomsection\label{\detokenize{appdev/refs/api/krb5_change_password:c.krb5_change_password}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_change\_password}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_creds:c.krb5_creds}]{\sphinxcrossref{krb5\_creds}}} *\sphinxstyleemphasis{ creds}, const char *\sphinxstyleemphasis{ newpw}, int *\sphinxstyleemphasis{ result\_code}, {\hyperref[\detokenize{appdev/refs/types/krb5_data:c.krb5_data}]{\sphinxcrossref{krb5\_data}}} *\sphinxstyleemphasis{ result\_code\_string}, {\hyperref[\detokenize{appdev/refs/types/krb5_data:c.krb5_data}]{\sphinxcrossref{krb5\_data}}} *\sphinxstyleemphasis{ result\_string}}{}
 1689 \end{fulllineitems}
 1690 
 1691 \begin{quote}\begin{description}
 1692 \item[{param}] \leavevmode
 1693 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1694 
 1695 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{creds} - Credentials for kadmin/changepw service
 1696 
 1697 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{newpw} - New password
 1698 
 1699 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{result\_code} - Numeric error code from server
 1700 
 1701 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{result\_code\_string} - String equivalent to \sphinxstyleemphasis{result\_code}
 1702 
 1703 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{result\_string} - Change password response from the KDC
 1704 
 1705 \end{description}\end{quote}
 1706 \begin{quote}\begin{description}
 1707 \item[{retval}] \leavevmode\begin{itemize}
 1708 \item {} 
 1709 0   Success; otherwise - Kerberos error codes
 1710 
 1711 \end{itemize}
 1712 
 1713 \end{description}\end{quote}
 1714 
 1715 Change the password for the existing principal identified by \sphinxstyleemphasis{creds} .
 1716 
 1717 The possible values of the output \sphinxstyleemphasis{result\_code} are:
 1718 \begin{itemize}
 1719 \item {} 
 1720 {\hyperref[\detokenize{appdev/refs/macros/KRB5_KPASSWD_SUCCESS:KRB5_KPASSWD_SUCCESS}]{\sphinxcrossref{\sphinxcode{KRB5\_KPASSWD\_SUCCESS}}}} (0) - success
 1721 
 1722 \item {} 
 1723 {\hyperref[\detokenize{appdev/refs/macros/KRB5_KPASSWD_MALFORMED:KRB5_KPASSWD_MALFORMED}]{\sphinxcrossref{\sphinxcode{KRB5\_KPASSWD\_MALFORMED}}}} (1) - Malformed request error
 1724 
 1725 \item {} 
 1726 {\hyperref[\detokenize{appdev/refs/macros/KRB5_KPASSWD_HARDERROR:KRB5_KPASSWD_HARDERROR}]{\sphinxcrossref{\sphinxcode{KRB5\_KPASSWD\_HARDERROR}}}} (2) - Server error
 1727 
 1728 \item {} 
 1729 {\hyperref[\detokenize{appdev/refs/macros/KRB5_KPASSWD_AUTHERROR:KRB5_KPASSWD_AUTHERROR}]{\sphinxcrossref{\sphinxcode{KRB5\_KPASSWD\_AUTHERROR}}}} (3) - Authentication error
 1730 
 1731 \item {} 
 1732 {\hyperref[\detokenize{appdev/refs/macros/KRB5_KPASSWD_SOFTERROR:KRB5_KPASSWD_SOFTERROR}]{\sphinxcrossref{\sphinxcode{KRB5\_KPASSWD\_SOFTERROR}}}} (4) - Password change rejected
 1733 
 1734 \end{itemize}
 1735 
 1736 
 1737 \subsubsection{krb5\_chpw\_message -  Get a result message for changing or setting a password.}
 1738 \label{\detokenize{appdev/refs/api/krb5_chpw_message:krb5-chpw-message-get-a-result-message-for-changing-or-setting-a-password}}\label{\detokenize{appdev/refs/api/krb5_chpw_message::doc}}\index{krb5\_chpw\_message (C function)}
 1739 
 1740 \begin{fulllineitems}
 1741 \phantomsection\label{\detokenize{appdev/refs/api/krb5_chpw_message:c.krb5_chpw_message}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_chpw\_message}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, const {\hyperref[\detokenize{appdev/refs/types/krb5_data:c.krb5_data}]{\sphinxcrossref{krb5\_data}}} *\sphinxstyleemphasis{ server\_string}, char **\sphinxstyleemphasis{ message\_out}}{}
 1742 \end{fulllineitems}
 1743 
 1744 \begin{quote}\begin{description}
 1745 \item[{param}] \leavevmode
 1746 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1747 
 1748 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{server\_string} - Data returned from the remote system
 1749 
 1750 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{message\_out} - A message displayable to the user
 1751 
 1752 \end{description}\end{quote}
 1753 \begin{quote}\begin{description}
 1754 \item[{retval}] \leavevmode\begin{itemize}
 1755 \item {} 
 1756 0   Success
 1757 
 1758 \end{itemize}
 1759 
 1760 \item[{return}] \leavevmode\begin{itemize}
 1761 \item {} 
 1762 Kerberos error codes
 1763 
 1764 \end{itemize}
 1765 
 1766 \end{description}\end{quote}
 1767 
 1768 This function processes the \sphinxstyleemphasis{server\_string} returned in the \sphinxstyleemphasis{result\_string} parameter of {\hyperref[\detokenize{appdev/refs/api/krb5_change_password:c.krb5_change_password}]{\sphinxcrossref{\sphinxcode{krb5\_change\_password()}}}} , {\hyperref[\detokenize{appdev/refs/api/krb5_set_password:c.krb5_set_password}]{\sphinxcrossref{\sphinxcode{krb5\_set\_password()}}}} , and related functions, and returns a displayable string. If \sphinxstyleemphasis{server\_string} contains Active Directory structured policy information, it will be converted into human-readable text.
 1769 
 1770 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_string:c.krb5_free_string}]{\sphinxcrossref{\sphinxcode{krb5\_free\_string()}}}} to free \sphinxstyleemphasis{message\_out} when it is no longer needed.
 1771 
 1772 \begin{sphinxadmonition}{note}{Note:}
 1773 New in 1.11
 1774 \end{sphinxadmonition}
 1775 
 1776 
 1777 \subsubsection{krb5\_expand\_hostname -  Canonicalize a hostname, possibly using name service.}
 1778 \label{\detokenize{appdev/refs/api/krb5_expand_hostname:krb5-expand-hostname-canonicalize-a-hostname-possibly-using-name-service}}\label{\detokenize{appdev/refs/api/krb5_expand_hostname::doc}}\index{krb5\_expand\_hostname (C function)}
 1779 
 1780 \begin{fulllineitems}
 1781 \phantomsection\label{\detokenize{appdev/refs/api/krb5_expand_hostname:c.krb5_expand_hostname}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_expand\_hostname}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, const char *\sphinxstyleemphasis{ host}, char **\sphinxstyleemphasis{ canonhost\_out}}{}
 1782 \end{fulllineitems}
 1783 
 1784 \begin{quote}\begin{description}
 1785 \item[{param}] \leavevmode
 1786 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1787 
 1788 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{host} - Input hostname
 1789 
 1790 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{canonhost\_out} - Canonicalized hostname
 1791 
 1792 \end{description}\end{quote}
 1793 
 1794 This function canonicalizes orig\_hostname, possibly using name service lookups if configuration permits. Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_string:c.krb5_free_string}]{\sphinxcrossref{\sphinxcode{krb5\_free\_string()}}}} to free \sphinxstyleemphasis{canonhost\_out} when it is no longer needed.
 1795 
 1796 \begin{sphinxadmonition}{note}{Note:}
 1797 New in 1.15
 1798 \end{sphinxadmonition}
 1799 
 1800 
 1801 \subsubsection{krb5\_free\_context -  Free a krb5 library context.}
 1802 \label{\detokenize{appdev/refs/api/krb5_free_context:krb5-free-context-free-a-krb5-library-context}}\label{\detokenize{appdev/refs/api/krb5_free_context::doc}}\index{krb5\_free\_context (C function)}
 1803 
 1804 \begin{fulllineitems}
 1805 \phantomsection\label{\detokenize{appdev/refs/api/krb5_free_context:c.krb5_free_context}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_free\_context}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}}{}
 1806 \end{fulllineitems}
 1807 
 1808 \begin{quote}\begin{description}
 1809 \item[{param}] \leavevmode
 1810 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1811 
 1812 \end{description}\end{quote}
 1813 
 1814 This function frees a \sphinxstyleemphasis{context} that was created by {\hyperref[\detokenize{appdev/refs/api/krb5_init_context:c.krb5_init_context}]{\sphinxcrossref{\sphinxcode{krb5\_init\_context()}}}} or {\hyperref[\detokenize{appdev/refs/api/krb5_init_secure_context:c.krb5_init_secure_context}]{\sphinxcrossref{\sphinxcode{krb5\_init\_secure\_context()}}}} .
 1815 
 1816 
 1817 \subsubsection{krb5\_free\_error\_message -  Free an error message generated by krb5\_get\_error\_message() .}
 1818 \label{\detokenize{appdev/refs/api/krb5_free_error_message:krb5-free-error-message-free-an-error-message-generated-by-krb5-get-error-message}}\label{\detokenize{appdev/refs/api/krb5_free_error_message::doc}}\index{krb5\_free\_error\_message (C function)}
 1819 
 1820 \begin{fulllineitems}
 1821 \phantomsection\label{\detokenize{appdev/refs/api/krb5_free_error_message:c.krb5_free_error_message}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_free\_error\_message}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ ctx}, const char *\sphinxstyleemphasis{ msg}}{}
 1822 \end{fulllineitems}
 1823 
 1824 \begin{quote}\begin{description}
 1825 \item[{param}] \leavevmode
 1826 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ctx} - Library context
 1827 
 1828 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{msg} - Pointer to error message
 1829 
 1830 \end{description}\end{quote}
 1831 
 1832 
 1833 \subsubsection{krb5\_free\_principal -  Free the storage assigned to a principal.}
 1834 \label{\detokenize{appdev/refs/api/krb5_free_principal::doc}}\label{\detokenize{appdev/refs/api/krb5_free_principal:krb5-free-principal-free-the-storage-assigned-to-a-principal}}\index{krb5\_free\_principal (C function)}
 1835 
 1836 \begin{fulllineitems}
 1837 \phantomsection\label{\detokenize{appdev/refs/api/krb5_free_principal:c.krb5_free_principal}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_free\_principal}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ val}}{}
 1838 \end{fulllineitems}
 1839 
 1840 \begin{quote}\begin{description}
 1841 \item[{param}] \leavevmode
 1842 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1843 
 1844 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{val} - Principal to be freed
 1845 
 1846 \end{description}\end{quote}
 1847 
 1848 
 1849 \subsubsection{krb5\_fwd\_tgt\_creds -  Get a forwarded TGT and format a KRB-CRED message.}
 1850 \label{\detokenize{appdev/refs/api/krb5_fwd_tgt_creds:krb5-fwd-tgt-creds-get-a-forwarded-tgt-and-format-a-krb-cred-message}}\label{\detokenize{appdev/refs/api/krb5_fwd_tgt_creds::doc}}\index{krb5\_fwd\_tgt\_creds (C function)}
 1851 
 1852 \begin{fulllineitems}
 1853 \phantomsection\label{\detokenize{appdev/refs/api/krb5_fwd_tgt_creds:c.krb5_fwd_tgt_creds}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_fwd\_tgt\_creds}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_auth_context:c.krb5_auth_context}]{\sphinxcrossref{krb5\_auth\_context}}}\sphinxstyleemphasis{ auth\_context}, const char *\sphinxstyleemphasis{ rhost}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ client}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ server}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ cc}, int\sphinxstyleemphasis{ forwardable}, {\hyperref[\detokenize{appdev/refs/types/krb5_data:c.krb5_data}]{\sphinxcrossref{krb5\_data}}} *\sphinxstyleemphasis{ outbuf}}{}
 1854 \end{fulllineitems}
 1855 
 1856 \begin{quote}\begin{description}
 1857 \item[{param}] \leavevmode
 1858 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1859 
 1860 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{auth\_context} - Authentication context
 1861 
 1862 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{rhost} - Remote host
 1863 
 1864 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{client} - Client principal of TGT
 1865 
 1866 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{server} - Principal of server to receive TGT
 1867 
 1868 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{cc} - Credential cache handle (NULL to use default)
 1869 
 1870 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{forwardable} - Whether TGT should be forwardable
 1871 
 1872 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{outbuf} - KRB-CRED message
 1873 
 1874 \end{description}\end{quote}
 1875 \begin{quote}\begin{description}
 1876 \item[{retval}] \leavevmode\begin{itemize}
 1877 \item {} 
 1878 0   Success
 1879 
 1880 \item {} 
 1881 ENOMEM   Insufficient memory
 1882 
 1883 \item {} 
 1884 KRB5\_PRINC\_NOMATCH   Requested principal and ticket do not match
 1885 
 1886 \item {} 
 1887 KRB5\_NO\_TKT\_SUPPLIED   Request did not supply a ticket
 1888 
 1889 \item {} 
 1890 KRB5\_CC\_BADNAME   Credential cache name or principal name malformed
 1891 
 1892 \end{itemize}
 1893 
 1894 \item[{return}] \leavevmode\begin{itemize}
 1895 \item {} 
 1896 Kerberos error codes
 1897 
 1898 \end{itemize}
 1899 
 1900 \end{description}\end{quote}
 1901 
 1902 Get a TGT for use at the remote host \sphinxstyleemphasis{rhost} and format it into a KRB-CRED message. If \sphinxstyleemphasis{rhost} is NULL and \sphinxstyleemphasis{server} is of type {\hyperref[\detokenize{appdev/refs/macros/KRB5_NT_SRV_HST:KRB5_NT_SRV_HST}]{\sphinxcrossref{\sphinxcode{KRB5\_NT\_SRV\_HST}}}} , the second component of \sphinxstyleemphasis{server} will be used.
 1903 
 1904 
 1905 \subsubsection{krb5\_get\_default\_realm -  Retrieve the default realm.}
 1906 \label{\detokenize{appdev/refs/api/krb5_get_default_realm:krb5-get-default-realm-retrieve-the-default-realm}}\label{\detokenize{appdev/refs/api/krb5_get_default_realm::doc}}\index{krb5\_get\_default\_realm (C function)}
 1907 
 1908 \begin{fulllineitems}
 1909 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_default_realm:c.krb5_get_default_realm}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_default\_realm}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, char **\sphinxstyleemphasis{ lrealm}}{}
 1910 \end{fulllineitems}
 1911 
 1912 \begin{quote}\begin{description}
 1913 \item[{param}] \leavevmode
 1914 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1915 
 1916 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{lrealm} - Default realm name
 1917 
 1918 \end{description}\end{quote}
 1919 \begin{quote}\begin{description}
 1920 \item[{retval}] \leavevmode\begin{itemize}
 1921 \item {} 
 1922 0   Success
 1923 
 1924 \end{itemize}
 1925 
 1926 \item[{return}] \leavevmode\begin{itemize}
 1927 \item {} 
 1928 Kerberos error codes
 1929 
 1930 \end{itemize}
 1931 
 1932 \end{description}\end{quote}
 1933 
 1934 Retrieves the default realm to be used if no user-specified realm is available.
 1935 
 1936 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_default_realm:c.krb5_free_default_realm}]{\sphinxcrossref{\sphinxcode{krb5\_free\_default\_realm()}}}} to free \sphinxstyleemphasis{lrealm} when it is no longer needed.
 1937 
 1938 
 1939 \subsubsection{krb5\_get\_error\_message -  Get the (possibly extended) error message for a code.}
 1940 \label{\detokenize{appdev/refs/api/krb5_get_error_message::doc}}\label{\detokenize{appdev/refs/api/krb5_get_error_message:krb5-get-error-message-get-the-possibly-extended-error-message-for-a-code}}\index{krb5\_get\_error\_message (C function)}
 1941 
 1942 \begin{fulllineitems}
 1943 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_error_message:c.krb5_get_error_message}}\pysiglinewithargsret{const char * \sphinxbfcode{krb5\_get\_error\_message}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ ctx}, {\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}}\sphinxstyleemphasis{ code}}{}
 1944 \end{fulllineitems}
 1945 
 1946 \begin{quote}\begin{description}
 1947 \item[{param}] \leavevmode
 1948 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ctx} - Library context
 1949 
 1950 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{code} - Error code
 1951 
 1952 \end{description}\end{quote}
 1953 
 1954 The behavior of {\hyperref[\detokenize{appdev/refs/api/krb5_get_error_message:c.krb5_get_error_message}]{\sphinxcrossref{\sphinxcode{krb5\_get\_error\_message()}}}} is only defined the first time it is called after a failed call to a krb5 function using the same context, and only when the error code passed in is the same as that returned by the krb5 function.
 1955 
 1956 This function never returns NULL, so its result may be used unconditionally as a C string.
 1957 
 1958 The string returned by this function must be freed using {\hyperref[\detokenize{appdev/refs/api/krb5_free_error_message:c.krb5_free_error_message}]{\sphinxcrossref{\sphinxcode{krb5\_free\_error\_message()}}}}
 1959 
 1960 \begin{sphinxadmonition}{note}{Note:}
 1961 Future versions may return the same string for the second and following calls.
 1962 \end{sphinxadmonition}
 1963 
 1964 
 1965 \subsubsection{krb5\_get\_host\_realm -  Get the Kerberos realm names for a host.}
 1966 \label{\detokenize{appdev/refs/api/krb5_get_host_realm:krb5-get-host-realm-get-the-kerberos-realm-names-for-a-host}}\label{\detokenize{appdev/refs/api/krb5_get_host_realm::doc}}\index{krb5\_get\_host\_realm (C function)}
 1967 
 1968 \begin{fulllineitems}
 1969 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_host_realm:c.krb5_get_host_realm}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_host\_realm}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, const char *\sphinxstyleemphasis{ host}, char ***\sphinxstyleemphasis{ realmsp}}{}
 1970 \end{fulllineitems}
 1971 
 1972 \begin{quote}\begin{description}
 1973 \item[{param}] \leavevmode
 1974 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 1975 
 1976 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{host} - Host name (or NULL)
 1977 
 1978 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{realmsp} - Null-terminated list of realm names
 1979 
 1980 \end{description}\end{quote}
 1981 \begin{quote}\begin{description}
 1982 \item[{retval}] \leavevmode\begin{itemize}
 1983 \item {} 
 1984 0   Success
 1985 
 1986 \item {} 
 1987 ENOMEM   Insufficient memory
 1988 
 1989 \end{itemize}
 1990 
 1991 \item[{return}] \leavevmode\begin{itemize}
 1992 \item {} 
 1993 Kerberos error codes
 1994 
 1995 \end{itemize}
 1996 
 1997 \end{description}\end{quote}
 1998 
 1999 Fill in \sphinxstyleemphasis{realmsp} with a pointer to a null-terminated list of realm names. If there are no known realms for the host, a list containing the referral (empty) realm is returned.
 2000 
 2001 If \sphinxstyleemphasis{host} is NULL, the local host’s realms are determined.
 2002 
 2003 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_host_realm:c.krb5_free_host_realm}]{\sphinxcrossref{\sphinxcode{krb5\_free\_host\_realm()}}}} to release \sphinxstyleemphasis{realmsp} when it is no longer needed.
 2004 
 2005 
 2006 \subsubsection{krb5\_get\_credentials -  Get an additional ticket.}
 2007 \label{\detokenize{appdev/refs/api/krb5_get_credentials:krb5-get-credentials-get-an-additional-ticket}}\label{\detokenize{appdev/refs/api/krb5_get_credentials::doc}}\index{krb5\_get\_credentials (C function)}
 2008 
 2009 \begin{fulllineitems}
 2010 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_credentials:c.krb5_get_credentials}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_credentials}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_flags:c.krb5_flags}]{\sphinxcrossref{krb5\_flags}}}\sphinxstyleemphasis{ options}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ ccache}, {\hyperref[\detokenize{appdev/refs/types/krb5_creds:c.krb5_creds}]{\sphinxcrossref{krb5\_creds}}} *\sphinxstyleemphasis{ in\_creds}, {\hyperref[\detokenize{appdev/refs/types/krb5_creds:c.krb5_creds}]{\sphinxcrossref{krb5\_creds}}} **\sphinxstyleemphasis{ out\_creds}}{}
 2011 \end{fulllineitems}
 2012 
 2013 \begin{quote}\begin{description}
 2014 \item[{param}] \leavevmode
 2015 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2016 
 2017 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{options} - Options
 2018 
 2019 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ccache} - Credential cache handle
 2020 
 2021 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{in\_creds} - Input credentials
 2022 
 2023 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{out\_creds} - Output updated credentials
 2024 
 2025 \end{description}\end{quote}
 2026 \begin{quote}\begin{description}
 2027 \item[{retval}] \leavevmode\begin{itemize}
 2028 \item {} 
 2029 0   Success
 2030 
 2031 \end{itemize}
 2032 
 2033 \item[{return}] \leavevmode\begin{itemize}
 2034 \item {} 
 2035 Kerberos error codes
 2036 
 2037 \end{itemize}
 2038 
 2039 \end{description}\end{quote}
 2040 
 2041 Use \sphinxstyleemphasis{ccache} or a TGS exchange to get a service ticket matching \sphinxstyleemphasis{in\_creds} .
 2042 
 2043 Valid values for \sphinxstyleemphasis{options} are:
 2044 \begin{quote}
 2045 \begin{itemize}
 2046 \item {} 
 2047 {\hyperref[\detokenize{appdev/refs/macros/KRB5_GC_CACHED:KRB5_GC_CACHED}]{\sphinxcrossref{\sphinxcode{KRB5\_GC\_CACHED}}}} Search only credential cache for the ticket
 2048 
 2049 \item {} 
 2050 {\hyperref[\detokenize{appdev/refs/macros/KRB5_GC_USER_USER:KRB5_GC_USER_USER}]{\sphinxcrossref{\sphinxcode{KRB5\_GC\_USER\_USER}}}} Return a user to user authentication ticket
 2051 
 2052 \end{itemize}
 2053 
 2054 \sphinxstyleemphasis{in\_creds} must be non-null. \sphinxstyleemphasis{in\_creds-\textgreater{}client} and \sphinxstyleemphasis{in\_creds-\textgreater{}server} must be filled in to specify the client and the server respectively. If any authorization data needs to be requested for the service ticket (such as restrictions on how the ticket can be used), specify it in \sphinxstyleemphasis{in\_creds-\textgreater{}authdata} ; otherwise set \sphinxstyleemphasis{in\_creds-\textgreater{}authdata} to NULL. The session key type is specified in \sphinxstyleemphasis{in\_creds-\textgreater{}keyblock.enctype} , if it is nonzero.
 2055 \end{quote}
 2056 
 2057 The expiration date is specified in \sphinxstyleemphasis{in\_creds-\textgreater{}times.endtime} . The KDC may return tickets with an earlier expiration date. If \sphinxstyleemphasis{in\_creds-\textgreater{}times.endtime} is set to 0, the latest possible expiration date will be requested.
 2058 
 2059 Any returned ticket and intermediate ticket-granting tickets are stored in \sphinxstyleemphasis{ccache} .
 2060 
 2061 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_creds:c.krb5_free_creds}]{\sphinxcrossref{\sphinxcode{krb5\_free\_creds()}}}} to free \sphinxstyleemphasis{out\_creds} when it is no longer needed.
 2062 
 2063 
 2064 \subsubsection{krb5\_get\_fallback\_host\_realm}
 2065 \label{\detokenize{appdev/refs/api/krb5_get_fallback_host_realm:krb5-get-fallback-host-realm}}\label{\detokenize{appdev/refs/api/krb5_get_fallback_host_realm::doc}}\index{krb5\_get\_fallback\_host\_realm (C function)}
 2066 
 2067 \begin{fulllineitems}
 2068 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_fallback_host_realm:c.krb5_get_fallback_host_realm}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_fallback\_host\_realm}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_data:c.krb5_data}]{\sphinxcrossref{krb5\_data}}} *\sphinxstyleemphasis{ hdata}, char ***\sphinxstyleemphasis{ realmsp}}{}
 2069 \end{fulllineitems}
 2070 
 2071 \begin{quote}\begin{description}
 2072 \item[{param}] \leavevmode
 2073 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2074 
 2075 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{hdata} - Host name (or NULL)
 2076 
 2077 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{realmsp} - Null-terminated list of realm names
 2078 
 2079 \end{description}\end{quote}
 2080 
 2081 Fill in \sphinxstyleemphasis{realmsp} with a pointer to a null-terminated list of realm names obtained through heuristics or insecure resolution methods which have lower priority than KDC referrals.
 2082 
 2083 If \sphinxstyleemphasis{host} is NULL, the local host’s realms are determined.
 2084 
 2085 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_host_realm:c.krb5_free_host_realm}]{\sphinxcrossref{\sphinxcode{krb5\_free\_host\_realm()}}}} to release \sphinxstyleemphasis{realmsp} when it is no longer needed.
 2086 
 2087 
 2088 \subsubsection{krb5\_get\_init\_creds\_keytab -  Get initial credentials using a key table.}
 2089 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_keytab:krb5-get-init-creds-keytab-get-initial-credentials-using-a-key-table}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_keytab::doc}}\index{krb5\_get\_init\_creds\_keytab (C function)}
 2090 
 2091 \begin{fulllineitems}
 2092 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_keytab:c.krb5_get_init_creds_keytab}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_keytab}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_creds:c.krb5_creds}]{\sphinxcrossref{krb5\_creds}}} *\sphinxstyleemphasis{ creds}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ client}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}}\sphinxstyleemphasis{ arg\_keytab}, {\hyperref[\detokenize{appdev/refs/types/krb5_deltat:c.krb5_deltat}]{\sphinxcrossref{krb5\_deltat}}}\sphinxstyleemphasis{ start\_time}, const char *\sphinxstyleemphasis{ in\_tkt\_service}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ k5\_gic\_options}}{}
 2093 \end{fulllineitems}
 2094 
 2095 \begin{quote}\begin{description}
 2096 \item[{param}] \leavevmode
 2097 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2098 
 2099 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{creds} - New credentials
 2100 
 2101 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{client} - Client principal
 2102 
 2103 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{arg\_keytab} - Key table handle
 2104 
 2105 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{start\_time} - Time when ticket becomes valid (0 for now)
 2106 
 2107 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{in\_tkt\_service} - Service name of initial credentials (or NULL)
 2108 
 2109 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{k5\_gic\_options} - Initial credential options
 2110 
 2111 \end{description}\end{quote}
 2112 \begin{quote}\begin{description}
 2113 \item[{retval}] \leavevmode\begin{itemize}
 2114 \item {} 
 2115 0   Success
 2116 
 2117 \end{itemize}
 2118 
 2119 \item[{return}] \leavevmode\begin{itemize}
 2120 \item {} 
 2121 Kerberos error codes
 2122 
 2123 \end{itemize}
 2124 
 2125 \end{description}\end{quote}
 2126 
 2127 This function requests KDC for an initial credentials for \sphinxstyleemphasis{client} using a client key stored in \sphinxstyleemphasis{arg\_keytab} . If \sphinxstyleemphasis{in\_tkt\_service} is specified, it is parsed as a principal name (with the realm ignored) and used as the service principal for the request; otherwise the ticket-granting service is used.
 2128 
 2129 
 2130 \subsubsection{krb5\_get\_init\_creds\_opt\_alloc -  Allocate a new initial credential options structure.}
 2131 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_alloc:krb5-get-init-creds-opt-alloc-allocate-a-new-initial-credential-options-structure}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_alloc::doc}}\index{krb5\_get\_init\_creds\_opt\_alloc (C function)}
 2132 
 2133 \begin{fulllineitems}
 2134 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_alloc:c.krb5_get_init_creds_opt_alloc}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_alloc}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} **\sphinxstyleemphasis{ opt}}{}
 2135 \end{fulllineitems}
 2136 
 2137 \begin{quote}\begin{description}
 2138 \item[{param}] \leavevmode
 2139 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2140 
 2141 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{opt} - New options structure
 2142 
 2143 \end{description}\end{quote}
 2144 \begin{quote}\begin{description}
 2145 \item[{retval}] \leavevmode\begin{itemize}
 2146 \item {} 
 2147 0   - Success; Kerberos errors otherwise.
 2148 
 2149 \end{itemize}
 2150 
 2151 \end{description}\end{quote}
 2152 
 2153 This function is the preferred way to create an options structure for getting initial credentials, and is required to make use of certain options. Use {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_free:c.krb5_get_init_creds_opt_free}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_free()}}}} to free \sphinxstyleemphasis{opt} when it is no longer needed.
 2154 
 2155 
 2156 \subsubsection{krb5\_get\_init\_creds\_opt\_free -  Free initial credential options.}
 2157 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_free::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_free:krb5-get-init-creds-opt-free-free-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_free (C function)}
 2158 
 2159 \begin{fulllineitems}
 2160 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_free:c.krb5_get_init_creds_opt_free}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_free}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}}{}
 2161 \end{fulllineitems}
 2162 
 2163 \begin{quote}\begin{description}
 2164 \item[{param}] \leavevmode
 2165 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2166 
 2167 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure to free
 2168 
 2169 \end{description}\end{quote}
 2170 
 2171 
 2172 \sphinxstrong{See also:}
 2173 
 2174 
 2175 {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_alloc:c.krb5_get_init_creds_opt_alloc}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_alloc()}}}}
 2176 
 2177 
 2178 
 2179 
 2180 \subsubsection{krb5\_get\_init\_creds\_opt\_get\_fast\_flags -  Retrieve FAST flags from initial credential options.}
 2181 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_get_fast_flags::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_get_fast_flags:krb5-get-init-creds-opt-get-fast-flags-retrieve-fast-flags-from-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_get\_fast\_flags (C function)}
 2182 
 2183 \begin{fulllineitems}
 2184 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_get_fast_flags:c.krb5_get_init_creds_opt_get_fast_flags}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_get\_fast\_flags}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_flags:c.krb5_flags}]{\sphinxcrossref{krb5\_flags}}} *\sphinxstyleemphasis{ out\_flags}}{}
 2185 \end{fulllineitems}
 2186 
 2187 \begin{quote}\begin{description}
 2188 \item[{param}] \leavevmode
 2189 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2190 
 2191 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options
 2192 
 2193 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{out\_flags} - FAST flags
 2194 
 2195 \end{description}\end{quote}
 2196 \begin{quote}\begin{description}
 2197 \item[{retval}] \leavevmode\begin{itemize}
 2198 \item {} 
 2199 0   - Success; Kerberos errors otherwise.
 2200 
 2201 \end{itemize}
 2202 
 2203 \end{description}\end{quote}
 2204 
 2205 
 2206 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_address\_list -  Set address restrictions in initial credential options.}
 2207 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_address_list:krb5-get-init-creds-opt-set-address-list-set-address-restrictions-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_address_list::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_address\_list (C function)}
 2208 
 2209 \begin{fulllineitems}
 2210 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_address_list:c.krb5_get_init_creds_opt_set_address_list}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_address\_list}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_address:c.krb5_address}]{\sphinxcrossref{krb5\_address}}} **\sphinxstyleemphasis{ addresses}}{}
 2211 \end{fulllineitems}
 2212 
 2213 \begin{quote}\begin{description}
 2214 \item[{param}] \leavevmode
 2215 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2216 
 2217 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{addresses} - Null-terminated array of addresses
 2218 
 2219 \end{description}\end{quote}
 2220 
 2221 
 2222 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_anonymous -  Set or unset the anonymous flag in initial credential options.}
 2223 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_anonymous:krb5-get-init-creds-opt-set-anonymous-set-or-unset-the-anonymous-flag-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_anonymous::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_anonymous (C function)}
 2224 
 2225 \begin{fulllineitems}
 2226 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_anonymous:c.krb5_get_init_creds_opt_set_anonymous}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_anonymous}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, int\sphinxstyleemphasis{ anonymous}}{}
 2227 \end{fulllineitems}
 2228 
 2229 \begin{quote}\begin{description}
 2230 \item[{param}] \leavevmode
 2231 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2232 
 2233 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{anonymous} - Whether to make an anonymous request
 2234 
 2235 \end{description}\end{quote}
 2236 
 2237 This function may be used to request anonymous credentials from the KDC by setting \sphinxstyleemphasis{anonymous} to non-zero. Note that anonymous credentials are only a request; clients must verify that credentials are anonymous if that is a requirement.
 2238 
 2239 
 2240 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_canonicalize -  Set or unset the canonicalize flag in initial credential options.}
 2241 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_canonicalize:krb5-get-init-creds-opt-set-canonicalize-set-or-unset-the-canonicalize-flag-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_canonicalize::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_canonicalize (C function)}
 2242 
 2243 \begin{fulllineitems}
 2244 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_canonicalize:c.krb5_get_init_creds_opt_set_canonicalize}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_canonicalize}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, int\sphinxstyleemphasis{ canonicalize}}{}
 2245 \end{fulllineitems}
 2246 
 2247 \begin{quote}\begin{description}
 2248 \item[{param}] \leavevmode
 2249 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2250 
 2251 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{canonicalize} - Whether to canonicalize client principal
 2252 
 2253 \end{description}\end{quote}
 2254 
 2255 
 2256 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_change\_password\_prompt -  Set or unset change-password-prompt flag in initial credential options.}
 2257 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_change_password_prompt::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_change_password_prompt:krb5-get-init-creds-opt-set-change-password-prompt-set-or-unset-change-password-prompt-flag-in-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_set\_change\_password\_prompt (C function)}
 2258 
 2259 \begin{fulllineitems}
 2260 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_change_password_prompt:c.krb5_get_init_creds_opt_set_change_password_prompt}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_change\_password\_prompt}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, int\sphinxstyleemphasis{ prompt}}{}
 2261 \end{fulllineitems}
 2262 
 2263 \begin{quote}\begin{description}
 2264 \item[{param}] \leavevmode
 2265 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2266 
 2267 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{prompt} - Whether to prompt to change password
 2268 
 2269 \end{description}\end{quote}
 2270 
 2271 This flag is on by default. It controls whether {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_password()}}}} will react to an expired-password error by prompting for a new password and attempting to change the old one.
 2272 
 2273 
 2274 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_etype\_list -  Set allowable encryption types in initial credential options.}
 2275 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_etype_list:krb5-get-init-creds-opt-set-etype-list-set-allowable-encryption-types-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_etype_list::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_etype\_list (C function)}
 2276 
 2277 \begin{fulllineitems}
 2278 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_etype_list:c.krb5_get_init_creds_opt_set_etype_list}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_etype\_list}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_enctype:c.krb5_enctype}]{\sphinxcrossref{krb5\_enctype}}} *\sphinxstyleemphasis{ etype\_list}, int\sphinxstyleemphasis{ etype\_list\_length}}{}
 2279 \end{fulllineitems}
 2280 
 2281 \begin{quote}\begin{description}
 2282 \item[{param}] \leavevmode
 2283 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2284 
 2285 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{etype\_list} - Array of encryption types
 2286 
 2287 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{etype\_list\_length} - Length of \sphinxstyleemphasis{etype\_list}
 2288 
 2289 \end{description}\end{quote}
 2290 
 2291 
 2292 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_expire\_callback -  Set an expiration callback in initial credential options.}
 2293 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_expire_callback::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_expire_callback:krb5-get-init-creds-opt-set-expire-callback-set-an-expiration-callback-in-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_set\_expire\_callback (C function)}
 2294 
 2295 \begin{fulllineitems}
 2296 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_expire_callback:c.krb5_get_init_creds_opt_set_expire_callback}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_expire\_callback}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_expire_callback_func:c.krb5_expire_callback_func}]{\sphinxcrossref{krb5\_expire\_callback\_func}}}\sphinxstyleemphasis{ cb}, void *\sphinxstyleemphasis{ data}}{}
 2297 \end{fulllineitems}
 2298 
 2299 \begin{quote}\begin{description}
 2300 \item[{param}] \leavevmode
 2301 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2302 
 2303 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2304 
 2305 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{cb} - Callback function
 2306 
 2307 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{data} - Callback argument
 2308 
 2309 \end{description}\end{quote}
 2310 
 2311 Set a callback to receive password and account expiration times.
 2312 
 2313 This option only applies to {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_password()}}}} . \sphinxstyleemphasis{cb} will be invoked if and only if credentials are successfully acquired. The callback will receive the \sphinxstyleemphasis{context} from the {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_password()}}}} call and the \sphinxstyleemphasis{data} argument supplied with this API. The remaining arguments should be interpreted as follows:
 2314 
 2315 If \sphinxstyleemphasis{is\_last\_req} is true, then the KDC reply contained last-req entries which unambiguously indicated the password expiration, account expiration, or both. (If either value was not present, the corresponding argument will be 0.) Furthermore, a non-zero \sphinxstyleemphasis{password\_expiration} should be taken as a suggestion from the KDC that a warning be displayed.
 2316 
 2317 If \sphinxstyleemphasis{is\_last\_req} is false, then \sphinxstyleemphasis{account\_expiration} will be 0 and \sphinxstyleemphasis{password\_expiration} will contain the expiration time of either the password or account, or 0 if no expiration time was indicated in the KDC reply. The callback should independently decide whether to display a password expiration warning.
 2318 
 2319 Note that \sphinxstyleemphasis{cb} may be invoked even if credentials are being acquired for the kadmin/changepw service in order to change the password. It is the caller’s responsibility to avoid displaying a password expiry warning in this case.
 2320 
 2321 \begin{sphinxadmonition}{warning}{Warning:}
 2322 Setting an expire callback with this API will cause {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_password()}}}} not to send password expiry warnings to the prompter, as it ordinarily may.
 2323 \end{sphinxadmonition}
 2324 
 2325 \begin{sphinxadmonition}{note}{Note:}
 2326 New in 1.9
 2327 \end{sphinxadmonition}
 2328 
 2329 
 2330 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_fast\_ccache -  Set FAST armor cache in initial credential options.}
 2331 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_ccache::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_ccache:krb5-get-init-creds-opt-set-fast-ccache-set-fast-armor-cache-in-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_set\_fast\_ccache (C function)}
 2332 
 2333 \begin{fulllineitems}
 2334 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_ccache:c.krb5_get_init_creds_opt_set_fast_ccache}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_fast\_ccache}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ ccache}}{}
 2335 \end{fulllineitems}
 2336 
 2337 \begin{quote}\begin{description}
 2338 \item[{param}] \leavevmode
 2339 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2340 
 2341 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options
 2342 
 2343 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ccache} - Credential cache handle
 2344 
 2345 \end{description}\end{quote}
 2346 
 2347 This function is similar to {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_ccache_name:c.krb5_get_init_creds_opt_set_fast_ccache_name}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_set\_fast\_ccache\_name()}}}} , but uses a credential cache handle instead of a name.
 2348 
 2349 \begin{sphinxadmonition}{note}{Note:}
 2350 New in 1.9
 2351 \end{sphinxadmonition}
 2352 
 2353 
 2354 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_fast\_ccache\_name -  Set location of FAST armor ccache in initial credential options.}
 2355 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_ccache_name:krb5-get-init-creds-opt-set-fast-ccache-name-set-location-of-fast-armor-ccache-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_ccache_name::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_fast\_ccache\_name (C function)}
 2356 
 2357 \begin{fulllineitems}
 2358 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_ccache_name:c.krb5_get_init_creds_opt_set_fast_ccache_name}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_fast\_ccache\_name}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, const char *\sphinxstyleemphasis{ fast\_ccache\_name}}{}
 2359 \end{fulllineitems}
 2360 
 2361 \begin{quote}\begin{description}
 2362 \item[{param}] \leavevmode
 2363 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2364 
 2365 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options
 2366 
 2367 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{fast\_ccache\_name} - Credential cache name
 2368 
 2369 \end{description}\end{quote}
 2370 
 2371 Sets the location of a credential cache containing an armor ticket to protect an initial credential exchange using the FAST protocol extension.
 2372 
 2373 In version 1.7, setting an armor ccache requires that FAST be used for the exchange. In version 1.8 or later, setting the armor ccache causes FAST to be used if the KDC supports it; {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_flags:c.krb5_get_init_creds_opt_set_fast_flags}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_set\_fast\_flags()}}}} must be used to require that FAST be used.
 2374 
 2375 
 2376 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_fast\_flags -  Set FAST flags in initial credential options.}
 2377 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_flags:krb5-get-init-creds-opt-set-fast-flags-set-fast-flags-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_flags::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_fast\_flags (C function)}
 2378 
 2379 \begin{fulllineitems}
 2380 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_fast_flags:c.krb5_get_init_creds_opt_set_fast_flags}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_fast\_flags}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_flags:c.krb5_flags}]{\sphinxcrossref{krb5\_flags}}}\sphinxstyleemphasis{ flags}}{}
 2381 \end{fulllineitems}
 2382 
 2383 \begin{quote}\begin{description}
 2384 \item[{param}] \leavevmode
 2385 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2386 
 2387 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options
 2388 
 2389 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{flags} - FAST flags
 2390 
 2391 \end{description}\end{quote}
 2392 \begin{quote}\begin{description}
 2393 \item[{retval}] \leavevmode\begin{itemize}
 2394 \item {} 
 2395 0   - Success; Kerberos errors otherwise.
 2396 
 2397 \end{itemize}
 2398 
 2399 \end{description}\end{quote}
 2400 
 2401 The following flag values are valid:
 2402 \begin{itemize}
 2403 \item {} 
 2404 {\hyperref[\detokenize{appdev/refs/macros/KRB5_FAST_REQUIRED:KRB5_FAST_REQUIRED}]{\sphinxcrossref{\sphinxcode{KRB5\_FAST\_REQUIRED}}}} - Require FAST to be used
 2405 
 2406 \end{itemize}
 2407 
 2408 
 2409 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_forwardable -  Set or unset the forwardable flag in initial credential options.}
 2410 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_forwardable:krb5-get-init-creds-opt-set-forwardable-set-or-unset-the-forwardable-flag-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_forwardable::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_forwardable (C function)}
 2411 
 2412 \begin{fulllineitems}
 2413 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_forwardable:c.krb5_get_init_creds_opt_set_forwardable}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_forwardable}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, int\sphinxstyleemphasis{ forwardable}}{}
 2414 \end{fulllineitems}
 2415 
 2416 \begin{quote}\begin{description}
 2417 \item[{param}] \leavevmode
 2418 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2419 
 2420 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{forwardable} - Whether credentials should be forwardable
 2421 
 2422 \end{description}\end{quote}
 2423 
 2424 
 2425 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_in\_ccache -  Set an input credential cache in initial credential options.}
 2426 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_in_ccache::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_in_ccache:krb5-get-init-creds-opt-set-in-ccache-set-an-input-credential-cache-in-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_set\_in\_ccache (C function)}
 2427 
 2428 \begin{fulllineitems}
 2429 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_in_ccache:c.krb5_get_init_creds_opt_set_in_ccache}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_in\_ccache}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ ccache}}{}
 2430 \end{fulllineitems}
 2431 
 2432 \begin{quote}\begin{description}
 2433 \item[{param}] \leavevmode
 2434 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2435 
 2436 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options
 2437 
 2438 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ccache} - Credential cache handle
 2439 
 2440 \end{description}\end{quote}
 2441 
 2442 If an input credential cache is set, then the krb5\_get\_init\_creds family of APIs will read settings from it. Setting an input ccache is desirable when the application wishes to perform authentication in the same way (using the same preauthentication mechanisms, and making the same non-security- sensitive choices) as the previous authentication attempt, which stored information in the passed-in ccache.
 2443 
 2444 \begin{sphinxadmonition}{note}{Note:}
 2445 New in 1.11
 2446 \end{sphinxadmonition}
 2447 
 2448 
 2449 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_out\_ccache -  Set an output credential cache in initial credential options.}
 2450 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_out_ccache:krb5-get-init-creds-opt-set-out-ccache-set-an-output-credential-cache-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_out_ccache::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_out\_ccache (C function)}
 2451 
 2452 \begin{fulllineitems}
 2453 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_out_ccache:c.krb5_get_init_creds_opt_set_out_ccache}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_out\_ccache}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ ccache}}{}
 2454 \end{fulllineitems}
 2455 
 2456 \begin{quote}\begin{description}
 2457 \item[{param}] \leavevmode
 2458 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2459 
 2460 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options
 2461 
 2462 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ccache} - Credential cache handle
 2463 
 2464 \end{description}\end{quote}
 2465 
 2466 If an output credential cache is set, then the krb5\_get\_init\_creds family of APIs will write credentials to it. Setting an output ccache is desirable both because it simplifies calling code and because it permits the krb5\_get\_init\_creds APIs to write out configuration information about the realm to the ccache.
 2467 
 2468 
 2469 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_pa -  Supply options for preauthentication in initial credential options.}
 2470 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_pa::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_pa:krb5-get-init-creds-opt-set-pa-supply-options-for-preauthentication-in-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_set\_pa (C function)}
 2471 
 2472 \begin{fulllineitems}
 2473 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_pa:c.krb5_get_init_creds_opt_set_pa}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_pa}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, const char *\sphinxstyleemphasis{ attr}, const char *\sphinxstyleemphasis{ value}}{}
 2474 \end{fulllineitems}
 2475 
 2476 \begin{quote}\begin{description}
 2477 \item[{param}] \leavevmode
 2478 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2479 
 2480 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2481 
 2482 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{attr} - Preauthentication option name
 2483 
 2484 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{value} - Preauthentication option value
 2485 
 2486 \end{description}\end{quote}
 2487 
 2488 This function allows the caller to supply options for preauthentication. The values of \sphinxstyleemphasis{attr} and \sphinxstyleemphasis{value} are supplied to each preauthentication module available within \sphinxstyleemphasis{context} .
 2489 
 2490 
 2491 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_pac\_request -  Ask the KDC to include or not include a PAC in the ticket.}
 2492 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_pac_request:krb5-get-init-creds-opt-set-pac-request-ask-the-kdc-to-include-or-not-include-a-pac-in-the-ticket}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_pac_request::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_pac\_request (C function)}
 2493 
 2494 \begin{fulllineitems}
 2495 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_pac_request:c.krb5_get_init_creds_opt_set_pac_request}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_pac\_request}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_boolean:c.krb5_boolean}]{\sphinxcrossref{krb5\_boolean}}}\sphinxstyleemphasis{ req\_pac}}{}
 2496 \end{fulllineitems}
 2497 
 2498 \begin{quote}\begin{description}
 2499 \item[{param}] \leavevmode
 2500 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2501 
 2502 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2503 
 2504 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{req\_pac} - Whether to request a PAC or not
 2505 
 2506 \end{description}\end{quote}
 2507 
 2508 If this option is set, the AS request will include a PAC-REQUEST pa-data item explicitly asking the KDC to either include or not include a privilege attribute certificate in the ticket authorization data. By default, no request is made; typically the KDC will default to including a PAC if it supports them.
 2509 
 2510 \begin{sphinxadmonition}{note}{Note:}
 2511 New in 1.15
 2512 \end{sphinxadmonition}
 2513 
 2514 
 2515 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_preauth\_list -  Set preauthentication types in initial credential options.}
 2516 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_preauth_list:krb5-get-init-creds-opt-set-preauth-list-set-preauthentication-types-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_preauth_list::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_preauth\_list (C function)}
 2517 
 2518 \begin{fulllineitems}
 2519 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_preauth_list:c.krb5_get_init_creds_opt_set_preauth_list}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_preauth\_list}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_preauthtype:c.krb5_preauthtype}]{\sphinxcrossref{krb5\_preauthtype}}} *\sphinxstyleemphasis{ preauth\_list}, int\sphinxstyleemphasis{ preauth\_list\_length}}{}
 2520 \end{fulllineitems}
 2521 
 2522 \begin{quote}\begin{description}
 2523 \item[{param}] \leavevmode
 2524 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2525 
 2526 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{preauth\_list} - Array of preauthentication types
 2527 
 2528 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{preauth\_list\_length} - Length of \sphinxstyleemphasis{preauth\_list}
 2529 
 2530 \end{description}\end{quote}
 2531 
 2532 This function can be used to perform optimistic preauthentication when getting initial credentials, in combination with {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_salt:c.krb5_get_init_creds_opt_set_salt}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_set\_salt()}}}} and {\hyperref[\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_pa:c.krb5_get_init_creds_opt_set_pa}]{\sphinxcrossref{\sphinxcode{krb5\_get\_init\_creds\_opt\_set\_pa()}}}} .
 2533 
 2534 
 2535 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_proxiable -  Set or unset the proxiable flag in initial credential options.}
 2536 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_proxiable::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_proxiable:krb5-get-init-creds-opt-set-proxiable-set-or-unset-the-proxiable-flag-in-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_set\_proxiable (C function)}
 2537 
 2538 \begin{fulllineitems}
 2539 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_proxiable:c.krb5_get_init_creds_opt_set_proxiable}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_proxiable}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, int\sphinxstyleemphasis{ proxiable}}{}
 2540 \end{fulllineitems}
 2541 
 2542 \begin{quote}\begin{description}
 2543 \item[{param}] \leavevmode
 2544 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2545 
 2546 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{proxiable} - Whether credentials should be proxiable
 2547 
 2548 \end{description}\end{quote}
 2549 
 2550 
 2551 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_renew\_life -  Set the ticket renewal lifetime in initial credential options.}
 2552 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_renew_life::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_renew_life:krb5-get-init-creds-opt-set-renew-life-set-the-ticket-renewal-lifetime-in-initial-credential-options}}\index{krb5\_get\_init\_creds\_opt\_set\_renew\_life (C function)}
 2553 
 2554 \begin{fulllineitems}
 2555 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_renew_life:c.krb5_get_init_creds_opt_set_renew_life}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_renew\_life}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_deltat:c.krb5_deltat}]{\sphinxcrossref{krb5\_deltat}}}\sphinxstyleemphasis{ renew\_life}}{}
 2556 \end{fulllineitems}
 2557 
 2558 \begin{quote}\begin{description}
 2559 \item[{param}] \leavevmode
 2560 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Pointer to \sphinxstyleemphasis{options} field
 2561 
 2562 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{renew\_life} - Ticket renewal lifetime
 2563 
 2564 \end{description}\end{quote}
 2565 
 2566 
 2567 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_responder -  Set the responder function in initial credential options.}
 2568 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_responder:krb5-get-init-creds-opt-set-responder-set-the-responder-function-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_responder::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_responder (C function)}
 2569 
 2570 \begin{fulllineitems}
 2571 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_responder:c.krb5_get_init_creds_opt_set_responder}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_responder}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_responder_fn:c.krb5_responder_fn}]{\sphinxcrossref{krb5\_responder\_fn}}}\sphinxstyleemphasis{ responder}, void *\sphinxstyleemphasis{ data}}{}
 2572 \end{fulllineitems}
 2573 
 2574 \begin{quote}\begin{description}
 2575 \item[{param}] \leavevmode
 2576 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2577 
 2578 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2579 
 2580 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{responder} - Responder function
 2581 
 2582 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{data} - Responder data argument
 2583 
 2584 \end{description}\end{quote}
 2585 
 2586 \begin{sphinxadmonition}{note}{Note:}
 2587 New in 1.11
 2588 \end{sphinxadmonition}
 2589 
 2590 
 2591 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_salt -  Set salt for optimistic preauthentication in initial credential options.}
 2592 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_salt:krb5-get-init-creds-opt-set-salt-set-salt-for-optimistic-preauthentication-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_salt::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_salt (C function)}
 2593 
 2594 \begin{fulllineitems}
 2595 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_salt:c.krb5_get_init_creds_opt_set_salt}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_salt}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_data:c.krb5_data}]{\sphinxcrossref{krb5\_data}}} *\sphinxstyleemphasis{ salt}}{}
 2596 \end{fulllineitems}
 2597 
 2598 \begin{quote}\begin{description}
 2599 \item[{param}] \leavevmode
 2600 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2601 
 2602 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{salt} - Salt data
 2603 
 2604 \end{description}\end{quote}
 2605 
 2606 When getting initial credentials with a password, a salt string it used to convert the password to a key. Normally this salt is obtained from the first KDC reply, but when performing optimistic preauthentication, the client may need to supply the salt string with this function.
 2607 
 2608 
 2609 \subsubsection{krb5\_get\_init\_creds\_opt\_set\_tkt\_life -  Set the ticket lifetime in initial credential options.}
 2610 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_tkt_life:krb5-get-init-creds-opt-set-tkt-life-set-the-ticket-lifetime-in-initial-credential-options}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_tkt_life::doc}}\index{krb5\_get\_init\_creds\_opt\_set\_tkt\_life (C function)}
 2611 
 2612 \begin{fulllineitems}
 2613 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_opt_set_tkt_life:c.krb5_get_init_creds_opt_set_tkt_life}}\pysiglinewithargsret{void \sphinxbfcode{krb5\_get\_init\_creds\_opt\_set\_tkt\_life}}{{\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ opt}, {\hyperref[\detokenize{appdev/refs/types/krb5_deltat:c.krb5_deltat}]{\sphinxcrossref{krb5\_deltat}}}\sphinxstyleemphasis{ tkt\_life}}{}
 2614 \end{fulllineitems}
 2615 
 2616 \begin{quote}\begin{description}
 2617 \item[{param}] \leavevmode
 2618 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{opt} - Options structure
 2619 
 2620 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{tkt\_life} - Ticket lifetime
 2621 
 2622 \end{description}\end{quote}
 2623 
 2624 
 2625 \subsubsection{krb5\_get\_init\_creds\_password -  Get initial credentials using a password.}
 2626 \label{\detokenize{appdev/refs/api/krb5_get_init_creds_password::doc}}\label{\detokenize{appdev/refs/api/krb5_get_init_creds_password:krb5-get-init-creds-password-get-initial-credentials-using-a-password}}\index{krb5\_get\_init\_creds\_password (C function)}
 2627 
 2628 \begin{fulllineitems}
 2629 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_init_creds_password:c.krb5_get_init_creds_password}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_init\_creds\_password}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_creds:c.krb5_creds}]{\sphinxcrossref{krb5\_creds}}} *\sphinxstyleemphasis{ creds}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ client}, const char *\sphinxstyleemphasis{ password}, {\hyperref[\detokenize{appdev/refs/types/krb5_prompter_fct:c.krb5_prompter_fct}]{\sphinxcrossref{krb5\_prompter\_fct}}}\sphinxstyleemphasis{ prompter}, void *\sphinxstyleemphasis{ data}, {\hyperref[\detokenize{appdev/refs/types/krb5_deltat:c.krb5_deltat}]{\sphinxcrossref{krb5\_deltat}}}\sphinxstyleemphasis{ start\_time}, const char *\sphinxstyleemphasis{ in\_tkt\_service}, {\hyperref[\detokenize{appdev/refs/types/krb5_get_init_creds_opt:c.krb5_get_init_creds_opt}]{\sphinxcrossref{krb5\_get\_init\_creds\_opt}}} *\sphinxstyleemphasis{ k5\_gic\_options}}{}
 2630 \end{fulllineitems}
 2631 
 2632 \begin{quote}\begin{description}
 2633 \item[{param}] \leavevmode
 2634 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2635 
 2636 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{creds} - New credentials
 2637 
 2638 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{client} - Client principal
 2639 
 2640 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{password} - Password (or NULL)
 2641 
 2642 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{prompter} - Prompter function
 2643 
 2644 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{data} - Prompter callback data
 2645 
 2646 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{start\_time} - Time when ticket becomes valid (0 for now)
 2647 
 2648 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{in\_tkt\_service} - Service name of initial credentials (or NULL)
 2649 
 2650 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{k5\_gic\_options} - Initial credential options
 2651 
 2652 \end{description}\end{quote}
 2653 \begin{quote}\begin{description}
 2654 \item[{retval}] \leavevmode\begin{itemize}
 2655 \item {} 
 2656 0   Success
 2657 
 2658 \item {} 
 2659 EINVAL   Invalid argument
 2660 
 2661 \item {} 
 2662 KRB5\_KDC\_UNREACH   Cannot contact any KDC for requested realm
 2663 
 2664 \item {} 
 2665 KRB5\_PREAUTH\_FAILED   Generic Pre-athentication failure
 2666 
 2667 \item {} 
 2668 KRB5\_LIBOS\_PWDINTR   Password read interrupted
 2669 
 2670 \item {} 
 2671 KRB5\_REALM\_CANT\_RESOLVE   Cannot resolve network address for KDC in requested realm
 2672 
 2673 \item {} 
 2674 KRB5KDC\_ERR\_KEY\_EXP   Password has expired
 2675 
 2676 \item {} 
 2677 KRB5\_LIBOS\_BADPWDMATCH   Password mismatch
 2678 
 2679 \item {} 
 2680 KRB5\_CHPW\_PWDNULL   New password cannot be zero length
 2681 
 2682 \item {} 
 2683 KRB5\_CHPW\_FAIL   Password change failed
 2684 
 2685 \end{itemize}
 2686 
 2687 \item[{return}] \leavevmode\begin{itemize}
 2688 \item {} 
 2689 Kerberos error codes
 2690 
 2691 \end{itemize}
 2692 
 2693 \end{description}\end{quote}
 2694 
 2695 This function requests KDC for an initial credentials for \sphinxstyleemphasis{client} using \sphinxstyleemphasis{password} . If \sphinxstyleemphasis{password} is NULL, a password will be prompted for using \sphinxstyleemphasis{prompter} if necessary. If \sphinxstyleemphasis{in\_tkt\_service} is specified, it is parsed as a principal name (with the realm ignored) and used as the service principal for the request; otherwise the ticket-granting service is used.
 2696 
 2697 
 2698 \subsubsection{krb5\_get\_profile -  Retrieve configuration profile from the context.}
 2699 \label{\detokenize{appdev/refs/api/krb5_get_profile::doc}}\label{\detokenize{appdev/refs/api/krb5_get_profile:krb5-get-profile-retrieve-configuration-profile-from-the-context}}\index{krb5\_get\_profile (C function)}
 2700 
 2701 \begin{fulllineitems}
 2702 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_profile:c.krb5_get_profile}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_profile}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, struct \_profile\_t **\sphinxstyleemphasis{ profile}}{}
 2703 \end{fulllineitems}
 2704 
 2705 \begin{quote}\begin{description}
 2706 \item[{param}] \leavevmode
 2707 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2708 
 2709 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{profile} - Pointer to data read from a configuration file
 2710 
 2711 \end{description}\end{quote}
 2712 \begin{quote}\begin{description}
 2713 \item[{retval}] \leavevmode\begin{itemize}
 2714 \item {} 
 2715 0   Success
 2716 
 2717 \end{itemize}
 2718 
 2719 \item[{return}] \leavevmode\begin{itemize}
 2720 \item {} 
 2721 Kerberos error codes
 2722 
 2723 \end{itemize}
 2724 
 2725 \end{description}\end{quote}
 2726 
 2727 This function creates a new \sphinxstyleemphasis{profile} object that reflects profile in the supplied \sphinxstyleemphasis{context} .
 2728 
 2729 The \sphinxstyleemphasis{profile} object may be freed with profile\_release() function. See profile.h and profile API for more details.
 2730 
 2731 
 2732 \subsubsection{krb5\_get\_prompt\_types -  Get prompt types array from a context.}
 2733 \label{\detokenize{appdev/refs/api/krb5_get_prompt_types::doc}}\label{\detokenize{appdev/refs/api/krb5_get_prompt_types:krb5-get-prompt-types-get-prompt-types-array-from-a-context}}\index{krb5\_get\_prompt\_types (C function)}
 2734 
 2735 \begin{fulllineitems}
 2736 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_prompt_types:c.krb5_get_prompt_types}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_prompt_type:c.krb5_prompt_type}]{\sphinxcrossref{krb5\_prompt\_type}}} * \sphinxbfcode{krb5\_get\_prompt\_types}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}}{}
 2737 \end{fulllineitems}
 2738 
 2739 \begin{quote}\begin{description}
 2740 \item[{param}] \leavevmode
 2741 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2742 
 2743 \end{description}\end{quote}
 2744 \begin{quote}\begin{description}
 2745 \item[{return}] \leavevmode\begin{itemize}
 2746 \item {} 
 2747 Pointer to an array of prompt types corresponding to the prompter’s prompts arguments. Each type has one of the following values: KRB5\_PROMPT\_TYPE\_PASSWORD KRB5\_PROMPT\_TYPE\_NEW\_PASSWORD KRB5\_PROMPT\_TYPE\_NEW\_PASSWORD\_AGAIN KRB5\_PROMPT\_TYPE\_PREAUTH
 2748 
 2749 \end{itemize}
 2750 
 2751 \end{description}\end{quote}
 2752 
 2753 
 2754 \subsubsection{krb5\_get\_renewed\_creds -  Get renewed credential from KDC using an existing credential.}
 2755 \label{\detokenize{appdev/refs/api/krb5_get_renewed_creds:krb5-get-renewed-creds-get-renewed-credential-from-kdc-using-an-existing-credential}}\label{\detokenize{appdev/refs/api/krb5_get_renewed_creds::doc}}\index{krb5\_get\_renewed\_creds (C function)}
 2756 
 2757 \begin{fulllineitems}
 2758 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_renewed_creds:c.krb5_get_renewed_creds}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_renewed\_creds}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_creds:c.krb5_creds}]{\sphinxcrossref{krb5\_creds}}} *\sphinxstyleemphasis{ creds}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ client}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ ccache}, const char *\sphinxstyleemphasis{ in\_tkt\_service}}{}
 2759 \end{fulllineitems}
 2760 
 2761 \begin{quote}\begin{description}
 2762 \item[{param}] \leavevmode
 2763 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2764 
 2765 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{creds} - Renewed credentials
 2766 
 2767 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{client} - Client principal name
 2768 
 2769 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ccache} - Credential cache
 2770 
 2771 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{in\_tkt\_service} - Server principal string (or NULL)
 2772 
 2773 \end{description}\end{quote}
 2774 \begin{quote}\begin{description}
 2775 \item[{retval}] \leavevmode\begin{itemize}
 2776 \item {} 
 2777 0   Success
 2778 
 2779 \end{itemize}
 2780 
 2781 \item[{return}] \leavevmode\begin{itemize}
 2782 \item {} 
 2783 Kerberos error codes
 2784 
 2785 \end{itemize}
 2786 
 2787 \end{description}\end{quote}
 2788 
 2789 This function gets a renewed credential using an existing one from \sphinxstyleemphasis{ccache} . If \sphinxstyleemphasis{in\_tkt\_service} is specified, it is parsed (with the realm part ignored) and used as the server principal of the credential; otherwise, the ticket-granting service is used.
 2790 
 2791 If successful, the renewed credential is placed in \sphinxstyleemphasis{creds} .
 2792 
 2793 
 2794 \subsubsection{krb5\_get\_validated\_creds -  Get validated credentials from the KDC.}
 2795 \label{\detokenize{appdev/refs/api/krb5_get_validated_creds:krb5-get-validated-creds-get-validated-credentials-from-the-kdc}}\label{\detokenize{appdev/refs/api/krb5_get_validated_creds::doc}}\index{krb5\_get\_validated\_creds (C function)}
 2796 
 2797 \begin{fulllineitems}
 2798 \phantomsection\label{\detokenize{appdev/refs/api/krb5_get_validated_creds:c.krb5_get_validated_creds}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_get\_validated\_creds}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_creds:c.krb5_creds}]{\sphinxcrossref{krb5\_creds}}} *\sphinxstyleemphasis{ creds}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ client}, {\hyperref[\detokenize{appdev/refs/types/krb5_ccache:c.krb5_ccache}]{\sphinxcrossref{krb5\_ccache}}}\sphinxstyleemphasis{ ccache}, const char *\sphinxstyleemphasis{ in\_tkt\_service}}{}
 2799 \end{fulllineitems}
 2800 
 2801 \begin{quote}\begin{description}
 2802 \item[{param}] \leavevmode
 2803 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2804 
 2805 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{creds} - Validated credentials
 2806 
 2807 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{client} - Client principal name
 2808 
 2809 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{ccache} - Credential cache
 2810 
 2811 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{in\_tkt\_service} - Server principal string (or NULL)
 2812 
 2813 \end{description}\end{quote}
 2814 \begin{quote}\begin{description}
 2815 \item[{retval}] \leavevmode\begin{itemize}
 2816 \item {} 
 2817 0   Success
 2818 
 2819 \item {} 
 2820 KRB5\_NO\_2ND\_TKT   Request missing second ticket
 2821 
 2822 \item {} 
 2823 KRB5\_NO\_TKT\_SUPPLIED   Request did not supply a ticket
 2824 
 2825 \item {} 
 2826 KRB5\_PRINC\_NOMATCH   Requested principal and ticket do not match
 2827 
 2828 \item {} 
 2829 KRB5\_KDCREP\_MODIFIED   KDC reply did not match expectations
 2830 
 2831 \item {} 
 2832 KRB5\_KDCREP\_SKEW   Clock skew too great in KDC reply
 2833 
 2834 \end{itemize}
 2835 
 2836 \item[{return}] \leavevmode\begin{itemize}
 2837 \item {} 
 2838 Kerberos error codes
 2839 
 2840 \end{itemize}
 2841 
 2842 \end{description}\end{quote}
 2843 
 2844 This function gets a validated credential using a postdated credential from \sphinxstyleemphasis{ccache} . If \sphinxstyleemphasis{in\_tkt\_service} is specified, it is parsed (with the realm part ignored) and used as the server principal of the credential; otherwise, the ticket-granting service is used.
 2845 
 2846 If successful, the validated credential is placed in \sphinxstyleemphasis{creds} .
 2847 
 2848 
 2849 \subsubsection{krb5\_init\_context -  Create a krb5 library context.}
 2850 \label{\detokenize{appdev/refs/api/krb5_init_context:krb5-init-context-create-a-krb5-library-context}}\label{\detokenize{appdev/refs/api/krb5_init_context::doc}}\index{krb5\_init\_context (C function)}
 2851 
 2852 \begin{fulllineitems}
 2853 \phantomsection\label{\detokenize{appdev/refs/api/krb5_init_context:c.krb5_init_context}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_init\_context}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}} *\sphinxstyleemphasis{ context}}{}
 2854 \end{fulllineitems}
 2855 
 2856 \begin{quote}\begin{description}
 2857 \item[{param}] \leavevmode
 2858 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{context} - Library context
 2859 
 2860 \end{description}\end{quote}
 2861 \begin{quote}\begin{description}
 2862 \item[{retval}] \leavevmode\begin{itemize}
 2863 \item {} 
 2864 0   Success
 2865 
 2866 \end{itemize}
 2867 
 2868 \item[{return}] \leavevmode\begin{itemize}
 2869 \item {} 
 2870 Kerberos error codes
 2871 
 2872 \end{itemize}
 2873 
 2874 \end{description}\end{quote}
 2875 
 2876 The \sphinxstyleemphasis{context} must be released by calling {\hyperref[\detokenize{appdev/refs/api/krb5_free_context:c.krb5_free_context}]{\sphinxcrossref{\sphinxcode{krb5\_free\_context()}}}} when it is no longer needed.
 2877 
 2878 \begin{sphinxadmonition}{warning}{Warning:}
 2879 Any program or module that needs the Kerberos code to not trust the environment must use {\hyperref[\detokenize{appdev/refs/api/krb5_init_secure_context:c.krb5_init_secure_context}]{\sphinxcrossref{\sphinxcode{krb5\_init\_secure\_context()}}}} , or clean out the environment.
 2880 \end{sphinxadmonition}
 2881 
 2882 
 2883 \subsubsection{krb5\_init\_secure\_context -  Create a krb5 library context using only configuration files.}
 2884 \label{\detokenize{appdev/refs/api/krb5_init_secure_context::doc}}\label{\detokenize{appdev/refs/api/krb5_init_secure_context:krb5-init-secure-context-create-a-krb5-library-context-using-only-configuration-files}}\index{krb5\_init\_secure\_context (C function)}
 2885 
 2886 \begin{fulllineitems}
 2887 \phantomsection\label{\detokenize{appdev/refs/api/krb5_init_secure_context:c.krb5_init_secure_context}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_init\_secure\_context}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}} *\sphinxstyleemphasis{ context}}{}
 2888 \end{fulllineitems}
 2889 
 2890 \begin{quote}\begin{description}
 2891 \item[{param}] \leavevmode
 2892 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{context} - Library context
 2893 
 2894 \end{description}\end{quote}
 2895 \begin{quote}\begin{description}
 2896 \item[{retval}] \leavevmode\begin{itemize}
 2897 \item {} 
 2898 0   Success
 2899 
 2900 \end{itemize}
 2901 
 2902 \item[{return}] \leavevmode\begin{itemize}
 2903 \item {} 
 2904 Kerberos error codes
 2905 
 2906 \end{itemize}
 2907 
 2908 \end{description}\end{quote}
 2909 
 2910 Create a context structure, using only system configuration files. All information passed through the environment variables is ignored.
 2911 
 2912 The \sphinxstyleemphasis{context} must be released by calling {\hyperref[\detokenize{appdev/refs/api/krb5_free_context:c.krb5_free_context}]{\sphinxcrossref{\sphinxcode{krb5\_free\_context()}}}} when it is no longer needed.
 2913 
 2914 
 2915 \subsubsection{krb5\_is\_config\_principal -  Test whether a principal is a configuration principal.}
 2916 \label{\detokenize{appdev/refs/api/krb5_is_config_principal:krb5-is-config-principal-test-whether-a-principal-is-a-configuration-principal}}\label{\detokenize{appdev/refs/api/krb5_is_config_principal::doc}}\index{krb5\_is\_config\_principal (C function)}
 2917 
 2918 \begin{fulllineitems}
 2919 \phantomsection\label{\detokenize{appdev/refs/api/krb5_is_config_principal:c.krb5_is_config_principal}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_boolean:c.krb5_boolean}]{\sphinxcrossref{krb5\_boolean}}} \sphinxbfcode{krb5\_is\_config\_principal}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_const_principal:c.krb5_const_principal}]{\sphinxcrossref{krb5\_const\_principal}}}\sphinxstyleemphasis{ principal}}{}
 2920 \end{fulllineitems}
 2921 
 2922 \begin{quote}\begin{description}
 2923 \item[{param}] \leavevmode
 2924 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2925 
 2926 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{principal} - Principal to check
 2927 
 2928 \end{description}\end{quote}
 2929 \begin{quote}\begin{description}
 2930 \item[{return}] \leavevmode\begin{itemize}
 2931 \item {} 
 2932 TRUE if the principal is a configuration principal (generated part of krb5\_cc\_set\_config() ); FALSE otherwise.
 2933 
 2934 \end{itemize}
 2935 
 2936 \end{description}\end{quote}
 2937 
 2938 
 2939 \subsubsection{krb5\_is\_thread\_safe -  Test whether the Kerberos library was built with multithread support.}
 2940 \label{\detokenize{appdev/refs/api/krb5_is_thread_safe::doc}}\label{\detokenize{appdev/refs/api/krb5_is_thread_safe:krb5-is-thread-safe-test-whether-the-kerberos-library-was-built-with-multithread-support}}\index{krb5\_is\_thread\_safe (C function)}
 2941 
 2942 \begin{fulllineitems}
 2943 \phantomsection\label{\detokenize{appdev/refs/api/krb5_is_thread_safe:c.krb5_is_thread_safe}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_boolean:c.krb5_boolean}]{\sphinxcrossref{krb5\_boolean}}} \sphinxbfcode{krb5\_is\_thread\_safe}}{void\sphinxstyleemphasis{ None}}{}
 2944 \end{fulllineitems}
 2945 
 2946 \begin{quote}\begin{description}
 2947 \item[{param}] \leavevmode
 2948 \sphinxstylestrong{None}
 2949 
 2950 \end{description}\end{quote}
 2951 \begin{quote}\begin{description}
 2952 \item[{retval}] \leavevmode\begin{itemize}
 2953 \item {} 
 2954 TRUE   if the library is threadsafe; FALSE otherwise
 2955 
 2956 \end{itemize}
 2957 
 2958 \end{description}\end{quote}
 2959 
 2960 
 2961 \subsubsection{krb5\_kt\_close -  Close a key table handle.}
 2962 \label{\detokenize{appdev/refs/api/krb5_kt_close:krb5-kt-close-close-a-key-table-handle}}\label{\detokenize{appdev/refs/api/krb5_kt_close::doc}}\index{krb5\_kt\_close (C function)}
 2963 
 2964 \begin{fulllineitems}
 2965 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kt_close:c.krb5_kt_close}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_kt\_close}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}}\sphinxstyleemphasis{ keytab}}{}
 2966 \end{fulllineitems}
 2967 
 2968 \begin{quote}\begin{description}
 2969 \item[{param}] \leavevmode
 2970 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2971 
 2972 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{keytab} - Key table handle
 2973 
 2974 \end{description}\end{quote}
 2975 \begin{quote}\begin{description}
 2976 \item[{retval}] \leavevmode\begin{itemize}
 2977 \item {} 
 2978 0   None
 2979 
 2980 \end{itemize}
 2981 
 2982 \end{description}\end{quote}
 2983 
 2984 
 2985 \subsubsection{krb5\_kt\_client\_default -  Resolve the default client key table.}
 2986 \label{\detokenize{appdev/refs/api/krb5_kt_client_default::doc}}\label{\detokenize{appdev/refs/api/krb5_kt_client_default:krb5-kt-client-default-resolve-the-default-client-key-table}}\index{krb5\_kt\_client\_default (C function)}
 2987 
 2988 \begin{fulllineitems}
 2989 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kt_client_default:c.krb5_kt_client_default}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_kt\_client\_default}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}} *\sphinxstyleemphasis{ keytab\_out}}{}
 2990 \end{fulllineitems}
 2991 
 2992 \begin{quote}\begin{description}
 2993 \item[{param}] \leavevmode
 2994 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 2995 
 2996 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{keytab\_out} - Key table handle
 2997 
 2998 \end{description}\end{quote}
 2999 \begin{quote}\begin{description}
 3000 \item[{retval}] \leavevmode\begin{itemize}
 3001 \item {} 
 3002 0   Success
 3003 
 3004 \end{itemize}
 3005 
 3006 \item[{return}] \leavevmode\begin{itemize}
 3007 \item {} 
 3008 Kerberos error codes
 3009 
 3010 \end{itemize}
 3011 
 3012 \end{description}\end{quote}
 3013 
 3014 Fill \sphinxstyleemphasis{keytab\_out} with a handle to the default client key table.
 3015 
 3016 \begin{sphinxadmonition}{note}{Note:}
 3017 New in 1.11
 3018 \end{sphinxadmonition}
 3019 
 3020 
 3021 \subsubsection{krb5\_kt\_default -  Resolve the default key table.}
 3022 \label{\detokenize{appdev/refs/api/krb5_kt_default:krb5-kt-default-resolve-the-default-key-table}}\label{\detokenize{appdev/refs/api/krb5_kt_default::doc}}\index{krb5\_kt\_default (C function)}
 3023 
 3024 \begin{fulllineitems}
 3025 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kt_default:c.krb5_kt_default}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_kt\_default}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}} *\sphinxstyleemphasis{ id}}{}
 3026 \end{fulllineitems}
 3027 
 3028 \begin{quote}\begin{description}
 3029 \item[{param}] \leavevmode
 3030 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3031 
 3032 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{id} - Key table handle
 3033 
 3034 \end{description}\end{quote}
 3035 \begin{quote}\begin{description}
 3036 \item[{retval}] \leavevmode\begin{itemize}
 3037 \item {} 
 3038 0   Success
 3039 
 3040 \end{itemize}
 3041 
 3042 \item[{return}] \leavevmode\begin{itemize}
 3043 \item {} 
 3044 Kerberos error codes
 3045 
 3046 \end{itemize}
 3047 
 3048 \end{description}\end{quote}
 3049 
 3050 Set \sphinxstyleemphasis{id} to a handle to the default key table. The key table is not opened.
 3051 
 3052 
 3053 \subsubsection{krb5\_kt\_default\_name -  Get the default key table name.}
 3054 \label{\detokenize{appdev/refs/api/krb5_kt_default_name::doc}}\label{\detokenize{appdev/refs/api/krb5_kt_default_name:krb5-kt-default-name-get-the-default-key-table-name}}\index{krb5\_kt\_default\_name (C function)}
 3055 
 3056 \begin{fulllineitems}
 3057 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kt_default_name:c.krb5_kt_default_name}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_kt\_default\_name}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, char *\sphinxstyleemphasis{ name}, int\sphinxstyleemphasis{ name\_size}}{}
 3058 \end{fulllineitems}
 3059 
 3060 \begin{quote}\begin{description}
 3061 \item[{param}] \leavevmode
 3062 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3063 
 3064 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{name} - Default key table name
 3065 
 3066 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{name\_size} - Space available in \sphinxstyleemphasis{name}
 3067 
 3068 \end{description}\end{quote}
 3069 \begin{quote}\begin{description}
 3070 \item[{retval}] \leavevmode\begin{itemize}
 3071 \item {} 
 3072 0   Success
 3073 
 3074 \item {} 
 3075 KRB5\_CONFIG\_NOTENUFSPACE   Buffer is too short
 3076 
 3077 \end{itemize}
 3078 
 3079 \item[{return}] \leavevmode\begin{itemize}
 3080 \item {} 
 3081 Kerberos error codes
 3082 
 3083 \end{itemize}
 3084 
 3085 \end{description}\end{quote}
 3086 
 3087 Fill \sphinxstyleemphasis{name} with the name of the default key table for \sphinxstyleemphasis{context} .
 3088 
 3089 
 3090 \subsubsection{krb5\_kt\_dup -  Duplicate keytab handle.}
 3091 \label{\detokenize{appdev/refs/api/krb5_kt_dup:krb5-kt-dup-duplicate-keytab-handle}}\label{\detokenize{appdev/refs/api/krb5_kt_dup::doc}}\index{krb5\_kt\_dup (C function)}
 3092 
 3093 \begin{fulllineitems}
 3094 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kt_dup:c.krb5_kt_dup}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_kt\_dup}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}}\sphinxstyleemphasis{ in}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}} *\sphinxstyleemphasis{ out}}{}
 3095 \end{fulllineitems}
 3096 
 3097 \begin{quote}\begin{description}
 3098 \item[{param}] \leavevmode
 3099 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3100 
 3101 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{in} - Key table handle to be duplicated
 3102 
 3103 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{out} - Key table handle
 3104 
 3105 \end{description}\end{quote}
 3106 
 3107 Create a new handle referring to the same key table as \sphinxstyleemphasis{in} . The new handle and \sphinxstyleemphasis{in} can be closed independently.
 3108 
 3109 \begin{sphinxadmonition}{note}{Note:}
 3110 New in 1.12
 3111 \end{sphinxadmonition}
 3112 
 3113 
 3114 \subsubsection{krb5\_kt\_get\_name -  Get a key table name.}
 3115 \label{\detokenize{appdev/refs/api/krb5_kt_get_name::doc}}\label{\detokenize{appdev/refs/api/krb5_kt_get_name:krb5-kt-get-name-get-a-key-table-name}}\index{krb5\_kt\_get\_name (C function)}
 3116 
 3117 \begin{fulllineitems}
 3118 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kt_get_name:c.krb5_kt_get_name}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_kt\_get\_name}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}}\sphinxstyleemphasis{ keytab}, char *\sphinxstyleemphasis{ name}, unsigned int\sphinxstyleemphasis{ namelen}}{}
 3119 \end{fulllineitems}
 3120 
 3121 \begin{quote}\begin{description}
 3122 \item[{param}] \leavevmode
 3123 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3124 
 3125 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{keytab} - Key table handle
 3126 
 3127 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{name} - Key table name
 3128 
 3129 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{namelen} - Maximum length to fill in name
 3130 
 3131 \end{description}\end{quote}
 3132 \begin{quote}\begin{description}
 3133 \item[{retval}] \leavevmode\begin{itemize}
 3134 \item {} 
 3135 0   Success
 3136 
 3137 \item {} 
 3138 KRB5\_KT\_NAME\_TOOLONG   Key table name does not fit in namelen bytes
 3139 
 3140 \end{itemize}
 3141 
 3142 \item[{return}] \leavevmode\begin{itemize}
 3143 \item {} 
 3144 Kerberos error codes
 3145 
 3146 \end{itemize}
 3147 
 3148 \end{description}\end{quote}
 3149 
 3150 Fill \sphinxstyleemphasis{name} with the name of \sphinxstyleemphasis{keytab} including the type and delimiter.
 3151 
 3152 
 3153 \subsubsection{krb5\_kt\_get\_type -  Return the type of a key table.}
 3154 \label{\detokenize{appdev/refs/api/krb5_kt_get_type:krb5-kt-get-type-return-the-type-of-a-key-table}}\label{\detokenize{appdev/refs/api/krb5_kt_get_type::doc}}\index{krb5\_kt\_get\_type (C function)}
 3155 
 3156 \begin{fulllineitems}
 3157 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kt_get_type:c.krb5_kt_get_type}}\pysiglinewithargsret{const char * \sphinxbfcode{krb5\_kt\_get\_type}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}}\sphinxstyleemphasis{ keytab}}{}
 3158 \end{fulllineitems}
 3159 
 3160 \begin{quote}\begin{description}
 3161 \item[{param}] \leavevmode
 3162 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3163 
 3164 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{keytab} - Key table handle
 3165 
 3166 \end{description}\end{quote}
 3167 \begin{quote}\begin{description}
 3168 \item[{return}] \leavevmode\begin{itemize}
 3169 \item {} 
 3170 The type of a key table as an alias that must not be modified or freed by the caller.
 3171 
 3172 \end{itemize}
 3173 
 3174 \end{description}\end{quote}
 3175 
 3176 
 3177 \subsubsection{krb5\_kt\_resolve -  Get a handle for a key table.}
 3178 \label{\detokenize{appdev/refs/api/krb5_kt_resolve:krb5-kt-resolve-get-a-handle-for-a-key-table}}\label{\detokenize{appdev/refs/api/krb5_kt_resolve::doc}}\index{krb5\_kt\_resolve (C function)}
 3179 
 3180 \begin{fulllineitems}
 3181 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kt_resolve:c.krb5_kt_resolve}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_kt\_resolve}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, const char *\sphinxstyleemphasis{ name}, {\hyperref[\detokenize{appdev/refs/types/krb5_keytab:c.krb5_keytab}]{\sphinxcrossref{krb5\_keytab}}} *\sphinxstyleemphasis{ ktid}}{}
 3182 \end{fulllineitems}
 3183 
 3184 \begin{quote}\begin{description}
 3185 \item[{param}] \leavevmode
 3186 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3187 
 3188 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{name} - Name of the key table
 3189 
 3190 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{ktid} - Key table handle
 3191 
 3192 \end{description}\end{quote}
 3193 \begin{quote}\begin{description}
 3194 \item[{retval}] \leavevmode\begin{itemize}
 3195 \item {} 
 3196 0   Success
 3197 
 3198 \end{itemize}
 3199 
 3200 \item[{return}] \leavevmode\begin{itemize}
 3201 \item {} 
 3202 Kerberos error codes
 3203 
 3204 \end{itemize}
 3205 
 3206 \end{description}\end{quote}
 3207 
 3208 Resolve the key table name \sphinxstyleemphasis{name} and set \sphinxstyleemphasis{ktid} to a handle identifying the key table. Use {\hyperref[\detokenize{appdev/refs/api/krb5_kt_close:c.krb5_kt_close}]{\sphinxcrossref{\sphinxcode{krb5\_kt\_close()}}}} to free \sphinxstyleemphasis{ktid} when it is no longer needed.
 3209 \begin{quote}
 3210 
 3211 \sphinxstyleemphasis{name} must be of the form \sphinxstylestrong{type:residual} , where \sphinxstyleemphasis{type} must be a type known to the library and \sphinxstyleemphasis{residual} portion should be specific to the particular keytab type. If no \sphinxstyleemphasis{type} is given, the default is \sphinxstylestrong{FILE} .
 3212 \end{quote}
 3213 
 3214 If \sphinxstyleemphasis{name} is of type \sphinxstylestrong{FILE} , the keytab file is not opened by this call.
 3215 
 3216 
 3217 \subsubsection{krb5\_kuserok -  Determine if a principal is authorized to log in as a local user.}
 3218 \label{\detokenize{appdev/refs/api/krb5_kuserok:krb5-kuserok-determine-if-a-principal-is-authorized-to-log-in-as-a-local-user}}\label{\detokenize{appdev/refs/api/krb5_kuserok::doc}}\index{krb5\_kuserok (C function)}
 3219 
 3220 \begin{fulllineitems}
 3221 \phantomsection\label{\detokenize{appdev/refs/api/krb5_kuserok:c.krb5_kuserok}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_boolean:c.krb5_boolean}]{\sphinxcrossref{krb5\_boolean}}} \sphinxbfcode{krb5\_kuserok}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}}\sphinxstyleemphasis{ principal}, const char *\sphinxstyleemphasis{ luser}}{}
 3222 \end{fulllineitems}
 3223 
 3224 \begin{quote}\begin{description}
 3225 \item[{param}] \leavevmode
 3226 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3227 
 3228 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{principal} - Principal name
 3229 
 3230 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{luser} - Local username
 3231 
 3232 \end{description}\end{quote}
 3233 \begin{quote}\begin{description}
 3234 \item[{retval}] \leavevmode\begin{itemize}
 3235 \item {} 
 3236 TRUE   Principal is authorized to log in as user; FALSE otherwise.
 3237 
 3238 \end{itemize}
 3239 
 3240 \end{description}\end{quote}
 3241 
 3242 Determine whether \sphinxstyleemphasis{principal} is authorized to log in as a local user \sphinxstyleemphasis{luser} .
 3243 
 3244 
 3245 \subsubsection{krb5\_parse\_name -  Convert a string principal name to a krb5\_principal structure.}
 3246 \label{\detokenize{appdev/refs/api/krb5_parse_name::doc}}\label{\detokenize{appdev/refs/api/krb5_parse_name:krb5-parse-name-convert-a-string-principal-name-to-a-krb5-principal-structure}}\index{krb5\_parse\_name (C function)}
 3247 
 3248 \begin{fulllineitems}
 3249 \phantomsection\label{\detokenize{appdev/refs/api/krb5_parse_name:c.krb5_parse_name}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_parse\_name}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, const char *\sphinxstyleemphasis{ name}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}} *\sphinxstyleemphasis{ principal\_out}}{}
 3250 \end{fulllineitems}
 3251 
 3252 \begin{quote}\begin{description}
 3253 \item[{param}] \leavevmode
 3254 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3255 
 3256 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{name} - String representation of a principal name
 3257 
 3258 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{principal\_out} - New principal
 3259 
 3260 \end{description}\end{quote}
 3261 \begin{quote}\begin{description}
 3262 \item[{retval}] \leavevmode\begin{itemize}
 3263 \item {} 
 3264 0   Success
 3265 
 3266 \end{itemize}
 3267 
 3268 \item[{return}] \leavevmode\begin{itemize}
 3269 \item {} 
 3270 Kerberos error codes
 3271 
 3272 \end{itemize}
 3273 
 3274 \end{description}\end{quote}
 3275 
 3276 Convert a string representation of a principal name to a krb5\_principal structure.
 3277 
 3278 A string representation of a Kerberos name consists of one or more principal name components, separated by slashes, optionally followed by the @ character and a realm name. If the realm name is not specified, the local realm is used.
 3279 
 3280 To use the slash and @ symbols as part of a component (quoted) instead of using them as a component separator or as a realm prefix), put a backslash () character in front of the symbol. Similarly, newline, tab, backspace, and NULL characters can be included in a component by using \sphinxstylestrong{n} , \sphinxstylestrong{t} , \sphinxstylestrong{b} or \sphinxstylestrong{0} , respectively.
 3281 
 3282 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_principal:c.krb5_free_principal}]{\sphinxcrossref{\sphinxcode{krb5\_free\_principal()}}}} to free \sphinxstyleemphasis{principal\_out} when it is no longer needed.
 3283 
 3284 \begin{sphinxadmonition}{note}{Note:}
 3285 The realm in a Kerberos \sphinxstyleemphasis{name} cannot contain slash, colon, or NULL characters.
 3286 \end{sphinxadmonition}
 3287 
 3288 
 3289 \subsubsection{krb5\_parse\_name\_flags -  Convert a string principal name to a krb5\_principal with flags.}
 3290 \label{\detokenize{appdev/refs/api/krb5_parse_name_flags:krb5-parse-name-flags-convert-a-string-principal-name-to-a-krb5-principal-with-flags}}\label{\detokenize{appdev/refs/api/krb5_parse_name_flags::doc}}\index{krb5\_parse\_name\_flags (C function)}
 3291 
 3292 \begin{fulllineitems}
 3293 \phantomsection\label{\detokenize{appdev/refs/api/krb5_parse_name_flags:c.krb5_parse_name_flags}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_error_code:c.krb5_error_code}]{\sphinxcrossref{krb5\_error\_code}}} \sphinxbfcode{krb5\_parse\_name\_flags}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, const char *\sphinxstyleemphasis{ name}, int\sphinxstyleemphasis{ flags}, {\hyperref[\detokenize{appdev/refs/types/krb5_principal:c.krb5_principal}]{\sphinxcrossref{krb5\_principal}}} *\sphinxstyleemphasis{ principal\_out}}{}
 3294 \end{fulllineitems}
 3295 
 3296 \begin{quote}\begin{description}
 3297 \item[{param}] \leavevmode
 3298 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3299 
 3300 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{name} - String representation of a principal name
 3301 
 3302 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{flags} - Flag
 3303 
 3304 \sphinxstylestrong{{[}out{]}} \sphinxstylestrong{principal\_out} - New principal
 3305 
 3306 \end{description}\end{quote}
 3307 \begin{quote}\begin{description}
 3308 \item[{retval}] \leavevmode\begin{itemize}
 3309 \item {} 
 3310 0   Success
 3311 
 3312 \end{itemize}
 3313 
 3314 \item[{return}] \leavevmode\begin{itemize}
 3315 \item {} 
 3316 Kerberos error codes
 3317 
 3318 \end{itemize}
 3319 
 3320 \end{description}\end{quote}
 3321 
 3322 Similar to {\hyperref[\detokenize{appdev/refs/api/krb5_parse_name:c.krb5_parse_name}]{\sphinxcrossref{\sphinxcode{krb5\_parse\_name()}}}} , this function converts a single-string representation of a principal name to a krb5\_principal structure.
 3323 
 3324 The following flags are valid:
 3325 \begin{quote}
 3326 \begin{itemize}
 3327 \item {} 
 3328 {\hyperref[\detokenize{appdev/refs/macros/KRB5_PRINCIPAL_PARSE_NO_REALM:KRB5_PRINCIPAL_PARSE_NO_REALM}]{\sphinxcrossref{\sphinxcode{KRB5\_PRINCIPAL\_PARSE\_NO\_REALM}}}} - no realm must be present in \sphinxstyleemphasis{name}
 3329 
 3330 \item {} 
 3331 {\hyperref[\detokenize{appdev/refs/macros/KRB5_PRINCIPAL_PARSE_REQUIRE_REALM:KRB5_PRINCIPAL_PARSE_REQUIRE_REALM}]{\sphinxcrossref{\sphinxcode{KRB5\_PRINCIPAL\_PARSE\_REQUIRE\_REALM}}}} - realm must be present in \sphinxstyleemphasis{name}
 3332 
 3333 \item {} 
 3334 {\hyperref[\detokenize{appdev/refs/macros/KRB5_PRINCIPAL_PARSE_ENTERPRISE:KRB5_PRINCIPAL_PARSE_ENTERPRISE}]{\sphinxcrossref{\sphinxcode{KRB5\_PRINCIPAL\_PARSE\_ENTERPRISE}}}} - create single-component enterprise principal
 3335 
 3336 \item {} 
 3337 {\hyperref[\detokenize{appdev/refs/macros/KRB5_PRINCIPAL_PARSE_IGNORE_REALM:KRB5_PRINCIPAL_PARSE_IGNORE_REALM}]{\sphinxcrossref{\sphinxcode{KRB5\_PRINCIPAL\_PARSE\_IGNORE\_REALM}}}} - ignore realm if present in \sphinxstyleemphasis{name}
 3338 
 3339 \end{itemize}
 3340 
 3341 If \sphinxstylestrong{KRB5\_PRINCIPAL\_PARSE\_NO\_REALM} or \sphinxstylestrong{KRB5\_PRINCIPAL\_PARSE\_IGNORE\_REALM} is specified in \sphinxstyleemphasis{flags} , the realm of the new principal will be empty. Otherwise, the default realm for \sphinxstyleemphasis{context} will be used if \sphinxstyleemphasis{name} does not specify a realm.
 3342 \end{quote}
 3343 
 3344 Use {\hyperref[\detokenize{appdev/refs/api/krb5_free_principal:c.krb5_free_principal}]{\sphinxcrossref{\sphinxcode{krb5\_free\_principal()}}}} to free \sphinxstyleemphasis{principal\_out} when it is no longer needed.
 3345 
 3346 
 3347 \subsubsection{krb5\_principal\_compare -  Compare two principals.}
 3348 \label{\detokenize{appdev/refs/api/krb5_principal_compare:krb5-principal-compare-compare-two-principals}}\label{\detokenize{appdev/refs/api/krb5_principal_compare::doc}}\index{krb5\_principal\_compare (C function)}
 3349 
 3350 \begin{fulllineitems}
 3351 \phantomsection\label{\detokenize{appdev/refs/api/krb5_principal_compare:c.krb5_principal_compare}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_boolean:c.krb5_boolean}]{\sphinxcrossref{krb5\_boolean}}} \sphinxbfcode{krb5\_principal\_compare}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_const_principal:c.krb5_const_principal}]{\sphinxcrossref{krb5\_const\_principal}}}\sphinxstyleemphasis{ princ1}, {\hyperref[\detokenize{appdev/refs/types/krb5_const_principal:c.krb5_const_principal}]{\sphinxcrossref{krb5\_const\_principal}}}\sphinxstyleemphasis{ princ2}}{}
 3352 \end{fulllineitems}
 3353 
 3354 \begin{quote}\begin{description}
 3355 \item[{param}] \leavevmode
 3356 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{context} - Library context
 3357 
 3358 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{princ1} - First principal
 3359 
 3360 \sphinxstylestrong{{[}in{]}} \sphinxstylestrong{princ2} - Second principal
 3361 
 3362 \end{description}\end{quote}
 3363 \begin{quote}\begin{description}
 3364 \item[{retval}] \leavevmode\begin{itemize}
 3365 \item {} 
 3366 TRUE   if the principals are the same; FALSE otherwise
 3367 
 3368 \end{itemize}
 3369 
 3370 \end{description}\end{quote}
 3371 
 3372 
 3373 \subsubsection{krb5\_principal\_compare\_any\_realm -  Compare two principals ignoring realm components.}
 3374 \label{\detokenize{appdev/refs/api/krb5_principal_compare_any_realm:krb5-principal-compare-any-realm-compare-two-principals-ignoring-realm-components}}\label{\detokenize{appdev/refs/api/krb5_principal_compare_any_realm::doc}}\index{krb5\_principal\_compare\_any\_realm (C function)}
 3375 
 3376 \begin{fulllineitems}
 3377 \phantomsection\label{\detokenize{appdev/refs/api/krb5_principal_compare_any_realm:c.krb5_principal_compare_any_realm}}\pysiglinewithargsret{{\hyperref[\detokenize{appdev/refs/types/krb5_boolean:c.krb5_boolean}]{\sphinxcrossref{krb5\_boolean}}} \sphinxbfcode{krb5\_principal\_compare\_any\_realm}}{{\hyperref[\detokenize{appdev/refs/types/krb5_context:c.krb5_context}]{\sphinxcrossref{krb5\_context}}}\sphinxstyleemphasis{ context}, {\hyperref[\detokenize{appdev/refs/types/krb5_const_principal:c.krb5_const_principal}]{\sphinxcrossref{krb5\_const\_principal}}}\sphinxstyleemphasis{ princ1}, {