krb5: Import MIT 1.21.3 - src - FreeBSD source tree

diff options


context:
space:
mode:

author	Cy Schubert <cy@FreeBSD.org>	2025-03-19 22:12:25 +0000
committer	Cy Schubert <cy@FreeBSD.org>	2025-03-19 22:12:25 +0000
commit	8f7d3ef26dec89a92ec0665de84a5936310a5574 (patch)
tree	9a465418bd4056bf0d369751320a414eaed29fa4 /doc/html/appdev/init_creds.html
parent	1a79b20663ca26acc2998b90ea2ff2aefd8af5b1 (diff)

Diffstat (limited to 'doc/html/appdev/init_creds.html')

-rw-r--r--

doc/html/appdev/init_creds.html

162

1 files changed, 78 insertions, 84 deletions

diff --git a/doc/html/appdev/init_creds.html b/doc/html/appdev/init_creds.html
index da025b16ed34..8822189cbd15 100644
--- a/doc/html/appdev/init_creds.html
+++ b/doc/html/appdev/init_creds.html

@@ -1,35 +1,26 @@

-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

+<!DOCTYPE html>

-<html xmlns="http://www.w3.org/1999/xhtml">

+<html>

<head>

- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

+ <meta charset="utf-8" />

+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

<title>Initial credentials — MIT Kerberos Documentation</title>

- <link rel="stylesheet" href="../_static/agogo.css" type="text/css" />

- <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />

- <link rel="stylesheet" href="../_static/kerb.css" type="text/css" />

- <script type="text/javascript">

- var DOCUMENTATION_OPTIONS = {

- URL_ROOT: '../',

- VERSION: '1.21.2',

- COLLAPSE_INDEX: false,

- FILE_SUFFIX: '.html',

- HAS_SOURCE: true,

- SOURCELINK_SUFFIX: '.txt'

- };

- </script>

- <script type="text/javascript" src="../_static/jquery.js"></script>

- <script type="text/javascript" src="../_static/underscore.js"></script>

- <script type="text/javascript" src="../_static/doctools.js"></script>

+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />

+ <link rel="stylesheet" type="text/css" href="../_static/agogo.css" />

+ <link rel="stylesheet" type="text/css" href="../_static/kerb.css" />

+ <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>

+ <script src="../_static/jquery.js"></script>

+ <script src="../_static/underscore.js"></script>

+ <script src="../_static/doctools.js"></script>

- </head>

- <body>

+ </head><body>

@@ -61,7 +52,7 @@

- <div class="section" id="initial-credentials">

+ <section id="initial-credentials">

<h1>Initial credentials<a class="headerlink" href="#initial-credentials" title="Permalink to this headline">¶</a></h1>

<p>Software that performs tasks such as logging users into a computer

when they type their Kerberos password needs to get initial

@@ -81,13 +72,13 @@ over a secure channel), which they then verify against the KDC. While

this technique may be the only practical way to integrate Kerberos

into some existing legacy systems, its use is contrary to the original

design goals of Kerberos.</p>

-<p>The function <a class="reference internal" href="refs/api/krb5_get_init_creds_password.html#c.krb5_get_init_creds_password" title="krb5_get_init_creds_password"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_init_creds_password()</span></code></a> will get initial

+<p>The function <a class="reference internal" href="refs/api/krb5_get_init_creds_password.html#c.krb5_get_init_creds_password" title="krb5_get_init_creds_password"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_init_creds_password()</span></code></a> will get initial

credentials for a client using a password. An application that needs

-to verify the credentials can call <a class="reference internal" href="refs/api/krb5_verify_init_creds.html#c.krb5_verify_init_creds" title="krb5_verify_init_creds"><code class="xref c c-func docutils literal"><span class="pre">krb5_verify_init_creds()</span></code></a>.

+to verify the credentials can call <a class="reference internal" href="refs/api/krb5_verify_init_creds.html#c.krb5_verify_init_creds" title="krb5_verify_init_creds"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_verify_init_creds()</span></code></a>.

Here is an example of code to obtain and verify TGT credentials, given

strings <em>princname</em> and <em>password</em> for the client principal name and

password:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">krb5_error_code</span> <span class="n">ret</span><span class="p">;</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">krb5_error_code</span> <span class="n">ret</span><span class="p">;</span>

<span class="n">krb5_creds</span> <span class="n">creds</span><span class="p">;</span>

<span class="n">krb5_principal</span> <span class="n">client_princ</span> <span class="o">=</span> <span class="n">NULL</span><span class="p">;</span>

@@ -107,14 +98,14 @@ password:</p>

<span class="k">return</span> <span class="n">ret</span><span class="p">;</span>

</pre></div>

</div>

-<div class="section" id="options-for-get-init-creds">

+<section id="options-for-get-init-creds">

<h2>Options for get_init_creds<a class="headerlink" href="#options-for-get-init-creds" title="Permalink to this headline">¶</a></h2>

parameter (which can be a null pointer). Use the function

-<a class="reference internal" href="refs/api/krb5_get_init_creds_opt_alloc.html#c.krb5_get_init_creds_opt_alloc" title="krb5_get_init_creds_opt_alloc"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_init_creds_opt_alloc()</span></code></a> to allocate an options

-structure, and <a class="reference internal" href="refs/api/krb5_get_init_creds_opt_free.html#c.krb5_get_init_creds_opt_free" title="krb5_get_init_creds_opt_free"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_init_creds_opt_free()</span></code></a> to free it. For

+<a class="reference internal" href="refs/api/krb5_get_init_creds_opt_alloc.html#c.krb5_get_init_creds_opt_alloc" title="krb5_get_init_creds_opt_alloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_init_creds_opt_alloc()</span></code></a> to allocate an options

+structure, and <a class="reference internal" href="refs/api/krb5_get_init_creds_opt_free.html#c.krb5_get_init_creds_opt_free" title="krb5_get_init_creds_opt_free"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_init_creds_opt_free()</span></code></a> to free it. For

example:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">krb5_error_code</span> <span class="n">ret</span><span class="p">;</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">krb5_error_code</span> <span class="n">ret</span><span class="p">;</span>

<span class="n">krb5_get_init_creds_opt</span> <span class="o">*</span><span class="n">opt</span> <span class="o">=</span> <span class="n">NULL</span><span class="p">;</span>

<span class="n">krb5_creds</span> <span class="n">creds</span><span class="p">;</span>

@@ -134,8 +125,8 @@ example:</p>

<span class="k">return</span> <span class="n">ret</span><span class="p">;</span>

</pre></div>

</div>

-</div>

-<div class="section" id="getting-anonymous-credentials">

+</section>

+<section id="getting-anonymous-credentials">

<h2>Getting anonymous credentials<a class="headerlink" href="#getting-anonymous-credentials" title="Permalink to this headline">¶</a></h2>

<p>As of release 1.8, it is possible to obtain fully anonymous or

partially anonymous (realm-exposed) credentials, if the KDC supports

@@ -144,14 +135,14 @@ release 1.8 if configured appropriately (see <a class="reference internal" href=

but does not support issuing realm-exposed anonymous credentials at

this time.</p>

<p>To obtain fully anonymous credentials, call

-<a class="reference internal" href="refs/api/krb5_get_init_creds_opt_set_anonymous.html#c.krb5_get_init_creds_opt_set_anonymous" title="krb5_get_init_creds_opt_set_anonymous"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_init_creds_opt_set_anonymous()</span></code></a> on the options

+<a class="reference internal" href="refs/api/krb5_get_init_creds_opt_set_anonymous.html#c.krb5_get_init_creds_opt_set_anonymous" title="krb5_get_init_creds_opt_set_anonymous"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_init_creds_opt_set_anonymous()</span></code></a> on the options

structure to set the anonymous flag, and specify a client principal

with the KDC’s realm and a single empty data component (the principal

-obtained by parsing <code class="docutils literal"><span class="pre">@</span></code><em>realmname</em>). Authentication will take

+obtained by parsing <code class="docutils literal notranslate"><span class="pre">@</span></code><em>realmname</em>). Authentication will take

place using anonymous PKINIT; if successful, the client principal of

the resulting tickets will be

-<code class="docutils literal"><span class="pre">WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS</span></code>. Here is an example:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">krb5_get_init_creds_opt_set_anonymous</span><span class="p">(</span><span class="n">opt</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>

+<code class="docutils literal notranslate"><span class="pre">WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS</span></code>. Here is an example:</p>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">krb5_get_init_creds_opt_set_anonymous</span><span class="p">(</span><span class="n">opt</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>

<span class="n">ret</span> <span class="o">=</span> <span class="n">krb5_build_principal</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="o">&</span><span class="n">client_princ</span><span class="p">,</span> <span class="n">strlen</span><span class="p">(</span><span class="n">myrealm</span><span class="p">),</span>

<span class="n">myrealm</span><span class="p">,</span> <span class="s2">""</span><span class="p">,</span> <span class="p">(</span><span class="n">char</span> <span class="o">*</span><span class="p">)</span><span class="n">NULL</span><span class="p">);</span>

@@ -166,22 +157,22 @@ the resulting tickets will be

on the options structure as above, but specify a normal client

principal in order to prove membership in the realm. Authentication

will take place as it normally does; if successful, the client

-principal of the resulting tickets will be <code class="docutils literal"><span class="pre">WELLKNOWN/ANONYMOUS@</span></code><em>realmname</em>.</p>

-</div>

-<div class="section" id="user-interaction">

+principal of the resulting tickets will be <code class="docutils literal notranslate"><span class="pre">WELLKNOWN/ANONYMOUS@</span></code><em>realmname</em>.</p>

+</section>

+<section id="user-interaction">

<h2>User interaction<a class="headerlink" href="#user-interaction" title="Permalink to this headline">¶</a></h2>

<p>Authenticating a user usually requires the entry of secret

information, such as a password. A password can be supplied directly

-to <a class="reference internal" href="refs/api/krb5_get_init_creds_password.html#c.krb5_get_init_creds_password" title="krb5_get_init_creds_password"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_init_creds_password()</span></code></a> via the <em>password</em>

+to <a class="reference internal" href="refs/api/krb5_get_init_creds_password.html#c.krb5_get_init_creds_password" title="krb5_get_init_creds_password"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_init_creds_password()</span></code></a> via the <em>password</em>

parameter, or the application can supply prompter and/or responder

callbacks instead. If callbacks are used, the user can also be

queried for other secret information such as a PIN, informed of

impending password expiration, or prompted to change a password which

has expired.</p>

-<div class="section" id="prompter-callback">

+<section id="prompter-callback">

<h3>Prompter callback<a class="headerlink" href="#prompter-callback" title="Permalink to this headline">¶</a></h3>

<p>A prompter callback can be specified via the <em>prompter</em> and <em>data</em>

-parameters to <a class="reference internal" href="refs/api/krb5_get_init_creds_password.html#c.krb5_get_init_creds_password" title="krb5_get_init_creds_password"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_init_creds_password()</span></code></a>. The prompter

+parameters to <a class="reference internal" href="refs/api/krb5_get_init_creds_password.html#c.krb5_get_init_creds_password" title="krb5_get_init_creds_password"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_init_creds_password()</span></code></a>. The prompter

will be invoked each time the krb5 library has a question to ask or

information to present. When the prompter callback is invoked, the

<em>banner</em> argument (if not null) is intended to be displayed to the

@@ -189,82 +180,82 @@ user, and the questions to be answered are specified in the <em>prompts</em>

array. Each prompt contains a text question in the <em>prompt</em> field, a

<em>hidden</em> bit to indicate whether the answer should be hidden from

display, and a storage area for the answer in the <em>reply</em> field. The

-callback should fill in each question’s <code class="docutils literal"><span class="pre">reply->data</span></code> with the

-answer, up to a maximum number of <code class="docutils literal"><span class="pre">reply->length</span></code> bytes, and then

-reset <code class="docutils literal"><span class="pre">reply->length</span></code> to the length of the answer.</p>

-<p>A prompter callback can call <a class="reference internal" href="refs/api/krb5_get_prompt_types.html#c.krb5_get_prompt_types" title="krb5_get_prompt_types"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_prompt_types()</span></code></a> to get an

+callback should fill in each question’s <code class="docutils literal notranslate"><span class="pre">reply->data</span></code> with the

+answer, up to a maximum number of <code class="docutils literal notranslate"><span class="pre">reply->length</span></code> bytes, and then

+reset <code class="docutils literal notranslate"><span class="pre">reply->length</span></code> to the length of the answer.</p>

+<p>A prompter callback can call <a class="reference internal" href="refs/api/krb5_get_prompt_types.html#c.krb5_get_prompt_types" title="krb5_get_prompt_types"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_prompt_types()</span></code></a> to get an

array of type constants corresponding to the prompts, to get

programmatic information about the semantic meaning of the questions.

-<a class="reference internal" href="refs/api/krb5_get_prompt_types.html#c.krb5_get_prompt_types" title="krb5_get_prompt_types"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_prompt_types()</span></code></a> may return a null pointer if no prompt

+<a class="reference internal" href="refs/api/krb5_get_prompt_types.html#c.krb5_get_prompt_types" title="krb5_get_prompt_types"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_prompt_types()</span></code></a> may return a null pointer if no prompt

type information is available.</p>

<p>Text-based applications can use a built-in text prompter

-implementation by supplying <a class="reference internal" href="refs/api/krb5_prompter_posix.html#c.krb5_prompter_posix" title="krb5_prompter_posix"><code class="xref c c-func docutils literal"><span class="pre">krb5_prompter_posix()</span></code></a> as the

+implementation by supplying <a class="reference internal" href="refs/api/krb5_prompter_posix.html#c.krb5_prompter_posix" title="krb5_prompter_posix"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_prompter_posix()</span></code></a> as the

<em>prompter</em> parameter and a null pointer as the <em>data</em> parameter. For

example:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">ret</span> <span class="o">=</span> <span class="n">krb5_get_init_creds_password</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="o">&</span><span class="n">creds</span><span class="p">,</span> <span class="n">client_princ</span><span class="p">,</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ret</span> <span class="o">=</span> <span class="n">krb5_get_init_creds_password</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="o">&</span><span class="n">creds</span><span class="p">,</span> <span class="n">client_princ</span><span class="p">,</span>

<span class="n">NULL</span><span class="p">,</span> <span class="n">krb5_prompter_posix</span><span class="p">,</span> <span class="n">NULL</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span>

</pre></div>

</div>

-</div>

-<div class="section" id="responder-callback">

+</section>

+<section id="responder-callback">

<h3>Responder callback<a class="headerlink" href="#responder-callback" title="Permalink to this headline">¶</a></h3>

<p>A responder callback can be specified through the init_creds options

-using the <a class="reference internal" href="refs/api/krb5_get_init_creds_opt_set_responder.html#c.krb5_get_init_creds_opt_set_responder" title="krb5_get_init_creds_opt_set_responder"><code class="xref c c-func docutils literal"><span class="pre">krb5_get_init_creds_opt_set_responder()</span></code></a> function.

+using the <a class="reference internal" href="refs/api/krb5_get_init_creds_opt_set_responder.html#c.krb5_get_init_creds_opt_set_responder" title="krb5_get_init_creds_opt_set_responder"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_get_init_creds_opt_set_responder()</span></code></a> function.

Responder callbacks can present a more sophisticated user interface

for authentication secrets. The responder callback is usually invoked

only once per authentication, with a list of questions produced by all

of the allowed preauthentication mechanisms.</p>

<p>When the responder callback is invoked, the <em>rctx</em> argument can be

accessed to obtain the list of questions and to answer them. The

-<a class="reference internal" href="refs/api/krb5_responder_list_questions.html#c.krb5_responder_list_questions" title="krb5_responder_list_questions"><code class="xref c c-func docutils literal"><span class="pre">krb5_responder_list_questions()</span></code></a> function retrieves an array of

+<a class="reference internal" href="refs/api/krb5_responder_list_questions.html#c.krb5_responder_list_questions" title="krb5_responder_list_questions"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_responder_list_questions()</span></code></a> function retrieves an array of

question types. For each question type, the

-<a class="reference internal" href="refs/api/krb5_responder_get_challenge.html#c.krb5_responder_get_challenge" title="krb5_responder_get_challenge"><code class="xref c c-func docutils literal"><span class="pre">krb5_responder_get_challenge()</span></code></a> function retrieves additional

+<a class="reference internal" href="refs/api/krb5_responder_get_challenge.html#c.krb5_responder_get_challenge" title="krb5_responder_get_challenge"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_responder_get_challenge()</span></code></a> function retrieves additional

information about the question, if applicable, and the

-<a class="reference internal" href="refs/api/krb5_responder_set_answer.html#c.krb5_responder_set_answer" title="krb5_responder_set_answer"><code class="xref c c-func docutils literal"><span class="pre">krb5_responder_set_answer()</span></code></a> function sets the answer.</p>

+<a class="reference internal" href="refs/api/krb5_responder_set_answer.html#c.krb5_responder_set_answer" title="krb5_responder_set_answer"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_responder_set_answer()</span></code></a> function sets the answer.</p>

<p>Responder question types, challenges, and answers are UTF-8 strings.

The question type is a well-known string; the meaning of the challenge

and answer depend on the question type. If an application does not

understand a question type, it cannot interpret the challenge or

provide an answer. Failing to answer a question typically results in

the prompter callback being used as a fallback.</p>

-<div class="section" id="password-question">

+<section id="password-question">

<h4>Password question<a class="headerlink" href="#password-question" title="Permalink to this headline">¶</a></h4>

-<p>The <code class="xref c c-macro docutils literal"><span class="pre">KRB5_RESPONDER_QUESTION_PASSWORD</span></code> (or <code class="docutils literal"><span class="pre">"password"</span></code>)

+<p>The <code class="xref c c-macro docutils literal notranslate"><span class="pre">KRB5_RESPONDER_QUESTION_PASSWORD</span></code> (or <code class="docutils literal notranslate"><span class="pre">"password"</span></code>)

question type requests the user’s password. This question does not

have a challenge, and the response is simply the password string.</p>

-</div>

-<div class="section" id="one-time-password-question">

+</section>

+<section id="one-time-password-question">

<h4>One-time password question<a class="headerlink" href="#one-time-password-question" title="Permalink to this headline">¶</a></h4>

-<p>The <code class="xref c c-macro docutils literal"><span class="pre">KRB5_RESPONDER_QUESTION_OTP</span></code> (or <code class="docutils literal"><span class="pre">"otp"</span></code>) question

+<p>The <code class="xref c c-macro docutils literal notranslate"><span class="pre">KRB5_RESPONDER_QUESTION_OTP</span></code> (or <code class="docutils literal notranslate"><span class="pre">"otp"</span></code>) question

type requests a choice among one-time password tokens and the PIN and

value for the chosen token. The challenge and answer are JSON-encoded

strings, but an application can use convenience functions to avoid

doing any JSON processing itself.</p>

-<p>The <a class="reference internal" href="refs/api/krb5_responder_otp_get_challenge.html#c.krb5_responder_otp_get_challenge" title="krb5_responder_otp_get_challenge"><code class="xref c c-func docutils literal"><span class="pre">krb5_responder_otp_get_challenge()</span></code></a> function decodes the

+<p>The <a class="reference internal" href="refs/api/krb5_responder_otp_get_challenge.html#c.krb5_responder_otp_get_challenge" title="krb5_responder_otp_get_challenge"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_responder_otp_get_challenge()</span></code></a> function decodes the

challenge into a krb5_responder_otp_challenge structure. The

-<a class="reference internal" href="refs/api/krb5_responder_otp_set_answer.html#c.krb5_responder_otp_set_answer" title="krb5_responder_otp_set_answer"><code class="xref c c-func docutils literal"><span class="pre">krb5_responder_otp_set_answer()</span></code></a> function selects one of the

+<a class="reference internal" href="refs/api/krb5_responder_otp_set_answer.html#c.krb5_responder_otp_set_answer" title="krb5_responder_otp_set_answer"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_responder_otp_set_answer()</span></code></a> function selects one of the

token information elements from the challenge and supplies the value

and pin for that token.</p>

-</div>

-<div class="section" id="pkinit-password-or-pin-question">

+</section>

+<section id="pkinit-password-or-pin-question">

<h4>PKINIT password or PIN question<a class="headerlink" href="#pkinit-password-or-pin-question" title="Permalink to this headline">¶</a></h4>

-<p>The <code class="xref c c-macro docutils literal"><span class="pre">KRB5_RESPONDER_QUESTION_PKINIT</span></code> (or <code class="docutils literal"><span class="pre">"pkinit"</span></code>) question

+<p>The <code class="xref c c-macro docutils literal notranslate"><span class="pre">KRB5_RESPONDER_QUESTION_PKINIT</span></code> (or <code class="docutils literal notranslate"><span class="pre">"pkinit"</span></code>) question

type requests PINs for hardware devices and/or passwords for encrypted

credentials which are stored on disk, potentially also supplying

information about the state of the hardware devices. The challenge and

answer are JSON-encoded strings, but an application can use convenience

functions to avoid doing any JSON processing itself.</p>

-<p>The <a class="reference internal" href="refs/api/krb5_responder_pkinit_get_challenge.html#c.krb5_responder_pkinit_get_challenge" title="krb5_responder_pkinit_get_challenge"><code class="xref c c-func docutils literal"><span class="pre">krb5_responder_pkinit_get_challenge()</span></code></a> function decodes the

+<p>The <a class="reference internal" href="refs/api/krb5_responder_pkinit_get_challenge.html#c.krb5_responder_pkinit_get_challenge" title="krb5_responder_pkinit_get_challenge"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_responder_pkinit_get_challenge()</span></code></a> function decodes the

challenges into a krb5_responder_pkinit_challenge structure. The

-<a class="reference internal" href="refs/api/krb5_responder_pkinit_set_answer.html#c.krb5_responder_pkinit_set_answer" title="krb5_responder_pkinit_set_answer"><code class="xref c c-func docutils literal"><span class="pre">krb5_responder_pkinit_set_answer()</span></code></a> function can be used to

+<a class="reference internal" href="refs/api/krb5_responder_pkinit_set_answer.html#c.krb5_responder_pkinit_set_answer" title="krb5_responder_pkinit_set_answer"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_responder_pkinit_set_answer()</span></code></a> function can be used to

supply the PIN or password for a particular client credential, and can

be called multiple times.</p>

-</div>

-<div class="section" id="example">

+</section>

+<section id="example">

<h4>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h4>

<p>Here is an example of using a responder callback:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">static</span> <span class="n">krb5_error_code</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">static</span> <span class="n">krb5_error_code</span>

<span class="n">my_responder</span><span class="p">(</span><span class="n">krb5_context</span> <span class="n">context</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">data</span><span class="p">,</span>

<span class="n">krb5_responder_context</span> <span class="n">rctx</span><span class="p">)</span>

@@ -315,18 +306,18 @@ be called multiple times.</p>

</pre></div>

</div>

-</div>

-<div class="section" id="verifying-initial-credentials">

+</section>

+<section id="verifying-initial-credentials">

<h2>Verifying initial credentials<a class="headerlink" href="#verifying-initial-credentials" title="Permalink to this headline">¶</a></h2>

-<p>Use the function <a class="reference internal" href="refs/api/krb5_verify_init_creds.html#c.krb5_verify_init_creds" title="krb5_verify_init_creds"><code class="xref c c-func docutils literal"><span class="pre">krb5_verify_init_creds()</span></code></a> to verify initial

+<p>Use the function <a class="reference internal" href="refs/api/krb5_verify_init_creds.html#c.krb5_verify_init_creds" title="krb5_verify_init_creds"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_verify_init_creds()</span></code></a> to verify initial

credentials. It takes an options structure (which can be a null

-pointer). Use <a class="reference internal" href="refs/api/krb5_verify_init_creds_opt_init.html#c.krb5_verify_init_creds_opt_init" title="krb5_verify_init_creds_opt_init"><code class="xref c c-func docutils literal"><span class="pre">krb5_verify_init_creds_opt_init()</span></code></a> to initialize

+pointer). Use <a class="reference internal" href="refs/api/krb5_verify_init_creds_opt_init.html#c.krb5_verify_init_creds_opt_init" title="krb5_verify_init_creds_opt_init"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_verify_init_creds_opt_init()</span></code></a> to initialize

the caller-allocated options structure, and

-<a class="reference internal" href="refs/api/krb5_verify_init_creds_opt_set_ap_req_nofail.html#c.krb5_verify_init_creds_opt_set_ap_req_nofail" title="krb5_verify_init_creds_opt_set_ap_req_nofail"><code class="xref c c-func docutils literal"><span class="pre">krb5_verify_init_creds_opt_set_ap_req_nofail()</span></code></a> to set the

+<a class="reference internal" href="refs/api/krb5_verify_init_creds_opt_set_ap_req_nofail.html#c.krb5_verify_init_creds_opt_set_ap_req_nofail" title="krb5_verify_init_creds_opt_set_ap_req_nofail"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_verify_init_creds_opt_set_ap_req_nofail()</span></code></a> to set the

“nofail” option. For example:</p>

-<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">krb5_verify_init_creds_opt</span> <span class="n">vopt</span><span class="p">;</span>

+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">krb5_verify_init_creds_opt</span> <span class="n">vopt</span><span class="p">;</span>

<span class="n">krb5_verify_init_creds_opt_init</span><span class="p">(</span><span class="o">&</span><span class="n">vopt</span><span class="p">);</span>

<span class="n">krb5_verify_init_creds_opt_set_ap_req_nofail</span><span class="p">(</span><span class="o">&</span><span class="n">vopt</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>

@@ -335,7 +326,7 @@ the caller-allocated options structure, and

</div>

<p>The confusingly named “nofail” option, when set, means that the

verification must actually succeed in order for

-<a class="reference internal" href="refs/api/krb5_verify_init_creds.html#c.krb5_verify_init_creds" title="krb5_verify_init_creds"><code class="xref c c-func docutils literal"><span class="pre">krb5_verify_init_creds()</span></code></a> to indicate success. The default

+<a class="reference internal" href="refs/api/krb5_verify_init_creds.html#c.krb5_verify_init_creds" title="krb5_verify_init_creds"><code class="xref c c-func docutils literal notranslate"><span class="pre">krb5_verify_init_creds()</span></code></a> to indicate success. The default

state of this option (cleared) means that if there is no key material

available to verify the user credentials, the verification will

succeed anyway. (The default can be changed by a configuration file

@@ -345,15 +336,17 @@ desktop workstations need to allow users to log in using Kerberos.

The security risks from this practice are mitigated by the absence of

valuable state on the shared workstations—any valuable resources

that the users would access reside on networked servers.</p>

-</div>

+</section>

+ <div class="clearer"></div>

</div>

<ul>

<li><a class="reference internal" href="#">Initial credentials</a><ul>

@@ -408,6 +401,7 @@ that the users would access reside on networked servers.</p>

</form>

</div>

</div>

@@ -415,8 +409,8 @@ that the users would access reside on networked servers.</p>

- <div class="right" ><i>Release: 1.21.2</i><br />

+ <div class="right" ><i>Release: 1.21.3</i><br />

</div>