1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>KDC preauthentication interface (kdcpreauth) — 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.16',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="MIT Kerberos Documentation" href="../index.html" />
<link rel="up" title="For plugin module developers" href="index.html" />
<link rel="next" title="Credential cache selection interface (ccselect)" href="ccselect.html" />
<link rel="prev" title="Client preauthentication interface (clpreauth)" href="clpreauth.html" />
</head>
<body>
<div class="header-wrapper">
<div class="header">
<h1><a href="../index.html">MIT Kerberos Documentation</a></h1>
<div class="rel">
<a href="../index.html" title="Full Table of Contents"
accesskey="C">Contents</a> |
<a href="clpreauth.html" title="Client preauthentication interface (clpreauth)"
accesskey="P">previous</a> |
<a href="ccselect.html" title="Credential cache selection interface (ccselect)"
accesskey="N">next</a> |
<a href="../genindex.html" title="General Index"
accesskey="I">index</a> |
<a href="../search.html" title="Enter search criteria"
accesskey="S">Search</a> |
<a href="mailto:krb5-bugs@mit.edu?subject=Documentation__KDC preauthentication interface (kdcpreauth)">feedback</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="kdc-preauthentication-interface-kdcpreauth">
<h1>KDC preauthentication interface (kdcpreauth)<a class="headerlink" href="#kdc-preauthentication-interface-kdcpreauth" title="Permalink to this headline">¶</a></h1>
<p>The kdcpreauth interface allows the addition of KDC support for
preauthentication mechanisms beyond those included in the core MIT
krb5 code base. For a detailed description of the kdcpreauth
interface, see the header file <tt class="docutils literal"><span class="pre"><krb5/kdcpreauth_plugin.h></span></tt> (or
<tt class="docutils literal"><span class="pre"><krb5/preauth_plugin.h></span></tt> before release 1.12).</p>
<p>A kdcpreauth module is generally responsible for:</p>
<ul class="simple">
<li>Supplying a list of preauth type numbers used by the module in the
<strong>pa_type_list</strong> field of the vtable structure.</li>
<li>Indicating what kind of preauthentication mechanism it implements,
with the <strong>flags</strong> method. If the mechanism computes a new reply
key, it must specify the <tt class="docutils literal"><span class="pre">PA_REPLACES_KEY</span></tt> flag. If the mechanism
is generally only used with hardware tokens, the <tt class="docutils literal"><span class="pre">PA_HARDWARE</span></tt>
flag allows the mechanism to work with principals which have the
<strong>requires_hwauth</strong> flag set.</li>
<li>Producing a padata value to be sent with a preauth_required error,
with the <strong>edata</strong> method.</li>
<li>Examining a padata value sent by a client and verifying that it
proves knowledge of the appropriate client credential information.
This is done with the <strong>verify</strong> method.</li>
<li>Producing a padata response value for the client, and possibly
computing a reply key. This is done with the <strong>return_padata</strong>
method.</li>
</ul>
<p>A module can create and destroy per-KDC state objects by implementing
the <strong>init</strong> and <strong>fini</strong> methods. Per-KDC state objects have the
type krb5_kdcpreauth_moddata, which is an abstract pointer types. A
module should typically cast this to an internal type for the state
object.</p>
<p>A module can create a per-request state object by returning one in the
<strong>verify</strong> method, receiving it in the <strong>return_padata</strong> method, and
destroying it in the <strong>free_modreq</strong> method. Note that these state
objects only apply to the processing of a single AS request packet,
not to an entire authentication exchange (since an authentication
exchange may remain unfinished by the client or may involve multiple
different KDC hosts). Per-request state objects have the type
krb5_kdcpreauth_modreq, which is an abstract pointer type.</p>
<p>The <strong>edata</strong>, <strong>verify</strong>, and <strong>return_padata</strong> methods have access
to a callback function and handle (called a “rock”) which can be used
to get additional information about the current request, including the
maximum allowable clock skew, the client’s long-term keys, the
DER-encoded request body, the FAST armor key, string attributes on the
client’s database entry, and the client’s database entry itself. The
<strong>verify</strong> method can assert one or more authentication indicators to
be included in the issued ticket using the <tt class="docutils literal"><span class="pre">add_auth_indicator</span></tt>
callback (new in release 1.14).</p>
<p>A module can generate state information to be included with the next
client request using the <tt class="docutils literal"><span class="pre">set_cookie</span></tt> callback (new in release
1.14). On the next request, the module can read this state
information using the <tt class="docutils literal"><span class="pre">get_cookie</span></tt> callback. Cookie information is
encrypted, timestamped, and transmitted to the client in a
<tt class="docutils literal"><span class="pre">PA-FX-COOKIE</span></tt> pa-data item. Older clients may not support cookies
and therefore may not transmit the cookie in the next request; in this
case, <tt class="docutils literal"><span class="pre">get_cookie</span></tt> will not yield the saved information.</p>
<p>If a module implements a mechanism which requires multiple round
trips, its <strong>verify</strong> method can respond with the code
<tt class="docutils literal"><span class="pre">KRB5KDC_ERR_MORE_PREAUTH_DATA_REQUIRED</span></tt> and a list of pa-data in
the <em>e_data</em> parameter to be processed by the client.</p>
<p>The <strong>edata</strong> and <strong>verify</strong> methods can be implemented
asynchronously. Because of this, they do not return values directly
to the caller, but must instead invoke responder functions with their
results. A synchronous implementation can invoke the responder
function immediately. An asynchronous implementation can use the
callback to get an event context for use with the <a class="reference external" href="https://fedorahosted.org/libverto/">libverto</a> API.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h2>On this page</h2>
<ul>
<li><a class="reference internal" href="#">KDC preauthentication interface (kdcpreauth)</a></li>
</ul>
<br/>
<h2>Table of contents</h2>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">For users</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin/index.html">For administrators</a></li>
<li class="toctree-l1"><a class="reference internal" href="../appdev/index.html">For application developers</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">For plugin module developers</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="general.html">General plugin concepts</a></li>
<li class="toctree-l2"><a class="reference internal" href="clpreauth.html">Client preauthentication interface (clpreauth)</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="">KDC preauthentication interface (kdcpreauth)</a></li>
<li class="toctree-l2"><a class="reference internal" href="ccselect.html">Credential cache selection interface (ccselect)</a></li>
<li class="toctree-l2"><a class="reference internal" href="pwqual.html">Password quality interface (pwqual)</a></li>
<li class="toctree-l2"><a class="reference internal" href="kadm5_hook.html">KADM5 hook interface (kadm5_hook)</a></li>
<li class="toctree-l2"><a class="reference internal" href="kadm5_auth.html">kadmin authorization interface (kadm5_auth)</a></li>
<li class="toctree-l2"><a class="reference internal" href="hostrealm.html">Host-to-realm interface (hostrealm)</a></li>
<li class="toctree-l2"><a class="reference internal" href="localauth.html">Local authorization interface (localauth)</a></li>
<li class="toctree-l2"><a class="reference internal" href="locate.html">Server location interface (locate)</a></li>
<li class="toctree-l2"><a class="reference internal" href="profile.html">Configuration interface (profile)</a></li>
<li class="toctree-l2"><a class="reference internal" href="gssapi.html">GSSAPI mechanism interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="internal.html">Internal pluggable interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="certauth.html">PKINIT certificate authorization interface (certauth)</a></li>
<li class="toctree-l2"><a class="reference internal" href="kdcpolicy.html">KDC policy interface (kdcpolicy)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../build/index.html">Building Kerberos V5</a></li>
<li class="toctree-l1"><a class="reference internal" href="../basic/index.html">Kerberos V5 concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../formats/index.html">Protocols and file formats</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mitK5features.html">MIT Kerberos features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../build_this.html">How to build this documentation from the source</a></li>
<li class="toctree-l1"><a class="reference internal" href="../about.html">Contributing to the MIT Kerberos Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li>
</ul>
<br/>
<h4><a href="../index.html">Full Table of Contents</a></h4>
<h4>Search</h4>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer" >
<div class="right" ><i>Release: 1.16</i><br />
© <a href="../copyright.html">Copyright</a> 1985-2017, MIT.
</div>
<div class="left">
<a href="../index.html" title="Full Table of Contents"
>Contents</a> |
<a href="clpreauth.html" title="Client preauthentication interface (clpreauth)"
>previous</a> |
<a href="ccselect.html" title="Credential cache selection interface (ccselect)"
>next</a> |
<a href="../genindex.html" title="General Index"
>index</a> |
<a href="../search.html" title="Enter search criteria"
>Search</a> |
<a href="mailto:krb5-bugs@mit.edu?subject=Documentation__KDC preauthentication interface (kdcpreauth)">feedback</a>
</div>
</div>
</div>
</body>
</html>
|
