Correct "specifiy" typos.
[nivanova/samba-autobuild/.git] / source4 / auth / kerberos / kerberos-porting-to-mit-notes.txt
1 Copyright Andrew Bartlett <> 2005-2009
2 Copyright Donald T. Davis <>        2009
4 Released under the GPLv3
5 "Porting Samba4 to MIT-Krb"
8          From Idmwiki
11 IPA v3 will use a version of Samba4 built on top of MIT's Kerberos
12 implementation, instead of Heimdal's version of Kerberos.
14 Task list summary for porting changes needed, from Andrew Bartlett:
16       * Rewrite or extend the LDAP driver that MIT-KDC will use.
17       * MIT KDC changes:  rewrite DAL, add TGS-KBAC, enable PACs,...
18       * Full thread-safety for MIT's library code,
19       * Many small changes
21 Task list, without explanations (the list with explanations is in the
22 later sections of this document):
24 Porting Samba4 to MIT-krb comprises four main chunks of work:
25      1. Rewrite or extend the LDAP driver that MIT-KDC will use:
26           a. Our LDAP driver for the KDB needs to know how to do
27              Samba4's intricate canonicalization of server names,
28              user-names, and realm names.
29           b. AD-style aliases for HOST/ service names.
30           c. Implicit names for Win2k accounts.
31           d. Principal "types":  client / server / krbtgs
32           e. Most or all of this code is in 3 source files,
33              ~1000 lines in all;
34      2. MIT KDC changes
35           a. Rewrite the MIT KDC's Data-Abstraction Layer (DAL),
36              mostly because he MIT KDC needs to see&   manipulate
37              more LDAP detail, on Samba4's behalf;
38           b. Add HBAC to the KDC's TGT-issuance, so that Samba4
39              can refuse TGTs to kinit, based on time-of-day&
40              IP-addr constraints;
41           c. turn on MIT-krb 1.7's PAC handling
42           d. add bad-password counts, for unified account-lockouts
43              across all authT methods (Krb, NTLM, LDAP simple bind,
44              etc)
45      3. Make sure MIT's library code is more fully thread-safe,
46         by replacing all global and static variables with context
47         parameters for the library routines.  This may already be
48         done.
49      4. Many small changes (~15)
50           a. some extensions to MIT's libkrb5&   GSSAPI libraries,
51              including GSSAPI ticket-forwarding
52           b. some refitting in Samba4's use of the MIT libraries;
53           c. make sure Samba4's portable socket API works,
54              including "packet too large" errors;
55           d. MIT's GSSAPI code should support some legacy Samba3
56              clients that present incorrectly-calculated checksums;
57           e. Samba4 app-server-host holds aUTF-16 PW, plus a
58              key bitstring;
59           f. in-memory-only credentials cache;
60           g. in-memory-only keytab (nice to have);
61           h. get OSS NTLM authT library (Likewise Software?);
62           i. special Heimdal-specific functions;
63           j. principal-manipulation functions;
64           k. special check for misconfigured Samba4 hostnames;
65           l. improved krb error-messages;
66           m. improved krb logging
67           n. MS GSSMonger test-suite
68           o. testsuite for kpasswd daemon
70 0. Introduction: This document should be read alongside the Samba4
71 source code, as follows:
73     * For DAL and KDC requirements, please see Samba4's
74       source4/kdc/hdb-samba4.c in particular.  This file
75       is an implementation against Heimdal's HDB abstraction
76       layer, and is the biggest part of the samba-to-krb
77       glue layer, so the main part of the port to MIT is
78       to replace hdb-samba4 with a similar glue layer
79       that's designed for MIT's code.
80     * Samba4's PAC requirements are implemeneted in
81       source4/kdc/pac-glue.c
82     * Both of the above two layers are Heimdal plugins, and
83       both get loaded in source4/kdc/kdc.c
84     * For GSSAPI requirements, see auth/gensec/gensec_gssapi.c
85       (the consumer of GSSAPI in Samba4)
86     * For Kerberos library requirements, see
87       auth/kerberos/krb5_init_context.c
88     * Samba has its own credentials system, wrapping GSS creds,
89       just as GSS creds wrap around krb5 creds.  For the
90       interaction between Samba4 credential system and GSSAPI
91       and Kerberos, see auth/credentials/credentials_krb5.
93 1. Rewrite or extend the LDAP driver that MIT-KDC will use.
95      a. IPA'sLDAP driver for the KDB needs to know how to do
96         Samba4's intricate canonicalization of server names,
97         user-names, and realm names.
98         For hostnames&   usernames, alternate names appear in
99         LDAP as extra values in the multivalued "principal name"
100         attributes:
101           * For a hostname, the alternate names (other than
102             the short name, implied from the CN), are stored in
103             the servicePrincipalName
104           * For a username, the alternate names are stored in
105             the userPrincipalName attribute, and can be long
106             email-address-like names, such as
107             (see "Type 10 names," below).
108         GSSAPI layer requirements:  Welcome to the wonderful
109         world of canonicalisation.  The MIT Krb5 libs (including
110         GSSAPI) do not enable the AS to send kinit a TGT containing
111         a different realm-name than what the client asked for,
112         even in U/L case differences.  Heimdal has the same problem,
113         and this applies to the krb5 layer too, not just GSSAPI.
114         There are two kinds of name-canonicalization that can
115         occur on Windows:
116           * Lower-to-upper case conversion, because Windows domain
117             names are usually in upper case;
118           * An unrecognizable subsitution of names, such as might
119             happen when a user requests a ticket for a NetBIOS domain
120             name, but gets back a ticket for the corresponging FQDN.
121         As developers, we should test if the AD KDC's name-canonical-
122         isation can be turned off with the KDCOption flags in the
123         AS-REQ or TGS-REQ;  Windows clients always send the
124         Canonicalize flags as KDCOption values.
125         Principal Names, long and short names:
126         AD's KDC does not canonicalize servicePrincipalNames, except
127         for the realm in the KDC reply.  That is, the client gets
128         back the principal it asked for, with the realm portion
129         'fixed' to uppercase, long form.
130         Samba4 does some canonicalization, though Heimdal doesn't
131         canonicalize names itself:  For hostnames and usernames,
132         Samba4 canonicalizes the requested name only for the LDAP
133         principal-lookup, but then Samba4 returns the retrieved LDAP
134         record with the request's original, uncanonicalized hostname
135         replacing the canonicalized name that actually was found.
136         Usernames:  AndrewB says that Samba4 used to return
137         the canonicalized username exactly as retrieved from LDAP.
138         The reason Samba4 treated usernames differently was that
139         the user needs to present his own canonicalized username
140         to servers, for ACL-matching.  For hostnames this isn't
141         necessary.
142         Realm-names:  AD seems to accept a realm's short name
143         in krb-requests, at least for AS_REQ operations, but the
144         AD KDC always performs realm-canonicalisation, which
145         converts the short realm-name to the canonical long form.
146         So, this causes pain for current krb client libraries.
147         Punchline:  For bug-compatibility, we may need to
148         selectively or optionally disable the MIT-KDC's name-
149         canonicalization.
150         Application-code:
151         Name-canonicalisation matters not only for the KDC, but
152         also for app-server-code that has to deal with keytabs.
153         Further, with credential-caches, canonicalization can
154         lead to cache-misses, but then the client just asks for
155         new credentials for the variant server-name.  This could
156         happen, for example, if the user asks to access the
157         server twice, using different variants of the server-name.
158         Doubled realm-names:  We also need to handle type 10
159         names (NT-ENTERPRISE), which are a full principal name
160         in the principal field, unrelated to the realm.  The
161         principal field contains both principal&   realm names,
162         while the realm field contains a realm name, too, possibly
163         different.  For example, an NT-ENTERPRISE principal name
164         might look like: ,
165                           <--principal field-->|<----realm name--->|
166         Where is the leading portion, and
167         NTDEV.MICROSOFT.COM is the realm.  This is used for the
168         'email address-like login-name' feature of AD.
169      b.AD-style aliases for HOST/ service names.
170         AD keeps a list of service-prefixed aliases for the host's
171         principal name.  The AD KDC reads&   parses this list, so
172         as to allow the aliased services to share the HOST/ key.
173         This means that every ticket-request for a service-alias
174         gets a service-ticket encrypted in the HOST/ key.
175         For example, this is how HTTP/ and CIFS/ can use the
176         HOST/ AD-LDAP entry, without any explicitly CIFS-prefixed
177         entry in the host's servicePrincipalName attribute. In the
178         app-server host's AD record, the servicePrincipalName says
179         only HOST/ , but the client asks
180         for  CIFS/my.omputer@MY.REALM tickets.  So, AD looks in
181         LDAP for both name-variants, and finds the HOST/ version,
182         In AD's reply, AD replaces the HOST/ prefix with CIFS/ .
183         We implement this in hdb-ldb.
184         (TBD: Andrew, is this correct?:)
185         List of HOST/ aliases:  Samba4 currently uses only a small
186         set of  HOST/ aliases: sPNMappings: host=ldap,dns,cifs,http .
187         Also, dns's presence in this list is a bug, somehow.
188         AD's real list has 53 entries:
189         sPNMappings: host=alerter,appmgmt,cisvc,clipsrv,browser,
190           dhcp,dnscache,replicator,eventlog,eventsystem,policyagent,
191           oakley,dmserver,dns,mcsvc,fax,msiserver,ias,messenger,
192           netlogon,netman,netdde,netddedsm,nmagent,plugplay,
193           protectedstorage,rasman,rpclocator,rpc,rpcss,remoteaccess,
194           rsvp,samss,scardsvr,scesrv,seclogon,scm,dcom,cifs,spooler,
195           snmp,schedule,tapisrv,trksvr,trkwks,ups,time,wins,www,
196           http,w3svc,iisadmin,msdtc
197         Domain members that expect the longer list will break in
198         Samba4, as of 6/09.  AB says he'll try to fix this right
199         away.  There is another post somewhere (ref lost for the
200         moment) that details where in active directory the long
201         list  of stored  aliases for HOST/ is.
202      c.Implicit names for Win2000 Accounts:  AD keys its
203         server-records by CN or by servicePrincipalName, but a
204         win2k box's server-entry in LDAP doesn't include the
205         servicePrincipalName attribute,  So, win2k server-accounts
206         are keyed by the CN attribute instead.  Because AD's LDAP
207         doesn't have a servicePrincipalName for win2k servers'
208         entries, Samba4 has to have an implicit mapping from
209         host/ and from host/computer, to the
210         computer's CN-keyed entry in the AD LDAP database, so to
211         be able to find the win2k server's host name in the KDB.
212      d.Principal "types":
213         We have modified Heimdal's 'hdb' interface to specify
214         the 'class' of Principal being requested.  This allows
215         us to correctly behave with the different 'classes' of
216         Principal name.  This is necessary because of AD's LDAP
217         structure, which uses very different record-structures
218         for user-principals, trust principals&   server-principals.
219         We currently define 3 classes:
220            * client (kinit)
221            * server (tgt)
222            * krbtgt  the TGS's own ldap record
223         Samba4 also now specifies the kerberos principal as an
224         explicit parameter to LDB_fetch(), not an in/out value
225         on the struct hdb_entry parameter itself.
226      e. Most or all of this LDAP driver code is in three source
227         files, ~1000 lines in all.  These files are in
228         samba4/kdc :
229            * hdb-samba4.c  (samba4-to-kdb glue-layer plugin)
230            * pac-glue.c    (samba4's pac  glue-layer plugin)
231            * kdc.c         (loads the above two plugins).
233 2. MIT KDC changes
235      a.Data-Abstraction Layer (DAL): It would be good to
236         rewrite or circumvent the MIT KDC's DAL, mostly because
237         the MIT KDC needs to see&   manipulate more LDAP detail,
238         on Samba4's behalf.  AB says the MIT DAL may serve well-
239         enough, though, mostly as is.  AB says Samba4 will need
240         the private pointer part of the KDC plugin API, though,
241         or the PAC generation won't work (see sec.2.c, below).
242         * MIT's DAL calls lack context parameters (as of 2006),
243           so presumably they rely instead on global storage, and
244           aren't fully thread-safe.
245         * In Novell's pure DAL approach, the DAL only read in the
246           principalName as the key, so it had trouble performing
247           access-control decisions on things other than the user's
248           name (like the addresses).
249         * Here's why Samba4 needs more entry detail than the DAL
250           provides:  The AS needs to have ACL rules that will allow
251           a TGT to a user only when the user logs in from the
252           right desktop addresses, and at the right times of day.
253           This coarse-granularity access-control could be enforced
254           directly by the KDC's LDAP driver, without Samba having
255           to see the entry's pertinent authZ attributes.  But,
256           there's a notable exception:  a user whose TGT has
257           expired, and who wants to change his password, should
258           be allowed a restricted-use TGT that gives him access
259           to the kpasswd service.  This ACL-logic could be buried
260           in the LDAP driver, in the same way as the TGS ACL could
261           be enforced down there, but to do so would just be even
262           uglier than it was to put the TGS's ACL-logic in the driver.
263         * Yet another complaint is that the DAL always pulls an
264           entire LDAP entry, non-selectively.  The current DAL
265           is OK for Samba4's purposes, because Samba4 only reads,
266           and doesn't write, the KDB.  But this all-or-nothing
267           retrieval hurts the KDC's performance, and would do so
268           even more, if Samba had to use the DAL to change KDB
269           entries.
270      b.Add HBAC to the KDC's TGT-issuance, so that Samba4 can
271         refuse TGTs to kinit, based on time-of-day&   IP-address
272         constraints.  AB asks, "Is a DAL the layer we need?"
273         Looking at what we need to pass around, AB doesn't think
274         the DAL is the right layer; what we really want instead
275         is to create an account-authorization abstraction layer
276         (e.g., is this account permitted to login to this computer,
277         at this time?).  Samba4 ended up doing account-authorization
278         inside Heimdal, via a specialized KDC plugin.  For a summary
279         description of this plugin API, see Appendix 2.
280      c. Turn on MIT-krb 1.7'sPAC handling.
281         In addition, I have added a new interface hdb_fetch_ex(),
282         which returns a structure including a private data-pointer,
283         which may be used by the windc plugin inferface functions.
284         The windc plugin provides the hook for the PAC.
285      d. Samba4 needsaccess control hooks in the Heimdal&   MIT
286         KDCs.  We need to lockout accounts (eg, after 10 failed PW-
287         attemps), and perform other controls.  This is standard
288         AD behavior, that Samba4 needs to get right, whether
289         Heimdal or MIT-krb is doing the ticket work.
290         - If PADL doesn't publish their patch for this,
291           we'll need to write our own.
292         - The windc plugin proivides a function for the main
293           access control routines.  A new windc plugin function
294           should be added to increment the bad password counter
295           on failure.
296         - Samba4 doesn't yet handle bad password counts (or good
297           password notification), so that a single policy can be
298           applied against all means of checking a password (NTLM,
299           Kerberos, LDAP Simple Bind, etc).  Novell's original DAL
300           did not provide a way to update the PW counts information.
301         - Nevertheless, we know that this is very much required in
302           AD, because Samba3 + eDirectory goes to great lengths to
303           update this information.  This may have been addressed in
304           Simo's subsequent IPA-KDC design),
305         * AllowedWorkstationNames and Krb5:  Microsoft uses the
306           clientAddresses *multiple value* field in the krb5
307           protocol (particularly the AS_REQ) to communicate the
308           client's netbios name (legacy undotted name,<14 chars)
309           AB guesses that this is to support the userWorkstations
310           field (in user's AD record).  The idea is to support
311           client-address restrictions, as was standard in NT:
312           The AD authentication server probably checks the netbios
313           address against this userWorkstations value (BTW, the
314           NetLogon server does this, too).
316 3. State Machine safety
317 when using Kerberos and GSSAPI libraries
319     * Samba's client-side&   app-server-side libraries are built
320       on a giant state machine, and as such have very different
321       requirements to those traditionally expressed for kerberos
322       and GSSAPI libraries.
323     * Samba requires all of the libraries it uses to be "state
324       machine safe" in their use of internal data.  This does not
325       necessarily mean "thread safe," and an application could be
326       thread safe, but not state machine safe (if it instead used
327       thread-local variables).  so, if MIT's libraries were made
328       thread-safe only by inserting spinlock() code, then the MIT
329       libraries aren't yet "state machine safe."
330     * So, what does it mean for a library to be state machine safe?
331       This is mostly a question of context, and how the library manages
332       whatever internal state machines it has.  If the library uses a
333       context variable, passed in by the caller, which contains all
334       the information about the current state of the library, then it
335       is safe.  An example of this state is the sequence number and
336       session keys for an ongoing encrypted session).
337     * The other issue affecting state machines is 'blocking' (waiting for a
338       read on a network socket).  Samba's non-blocking I/O doesn't like
339       waiting for libkrb5 to go away for awhile to talk to the KDC.
340     * Samba4 provides a hook 'send_to_kdc', that allows Samba4 to take over the
341       IO handling, and run other events in the meantime.  This uses a
342       'nested event context' (which presents the challenges that the kerberos
343       library might be called again, while still in the send_to_kdc hook).
344     * Heimdal has this 'state machine safety' in parts, and we have modified
345       Samba4's lorikeet branch to improve this behaviour, when using a new,
346       non-standard API to tunnelling a ccache (containing a set of tickets)
347       through the gssapi, by temporarily casting the ccache pointer to a
348       gss credential pointer.  This new API is Heimdal's samba4-requested
349       gss_krb5_import_cred() fcn;  this will have to be rewritten or ported
350       in the MIT port.
351     * This tunnelling trick replaces an older scheme using the KRB5_CCACHE
352       environment variable to get the same job done.  The tunnelling trick
353       enables a command-line app-client to run kinit tacitly, before running
354       GSSAPI for service-authentication.  The tunnelling trick avoids the
355       more usual approach of keeping the ccache pointer in a global variable.
356     * [Heimdal uses a per-context variable for the 'krb5_auth_context',
357       which controls the ongoing encrypted connection, but does use global
358       variables for the ubiquitous krb5_context parameter. (No longer true,
359       because the krb5_context global is gone now.)]
360     * The modification that has added most to 'state machine safety' of
361       GSSAPI is the addition of the gss_krb5_acquire_creds() function.
362       This allows the caller to specify a keytab and ccache, for use by
363       the GSSAPI code.  Therefore there is no need to use global variables
364       to communicate this information about keytab&   ccache.
365     * At a more theoretical level (simply counting static and global
366       variables) Heimdal is not state machine safe for the GSSAPI layer.
367       (But Heimdal is now (6/09) much more nearly free of globals.)
368       The Krb5 layer alone is much closer, as far as I can tell, blocking
369       excepted. .
370     * As an alternate to fixing MIT Kerberos for better safety in this area,
371       a new design might be implemented in Samba, where blocking read/write
372       is made to the KDC in another (fork()ed) child process, and the results
373       passed back to the parent process for use in other non-blocking operations.
374     * To deal with blocking, we could have a fork()ed child per context,
375       using the 'GSSAPI export context' function to transfer
376       the GSSAPI state back into the main code for the wrap()/unwrap() part
377       of the operation.  This will still hit issues of static storage (one
378       gss_krb5_context per process, and multiple GSSAPI encrypted sessions
379       at a time) but these may not matter in practice.
380     * This approach has long been controversial in the Samba team.
381       An alternate way would be to be implement E_AGAIN in libkrb5:  similar
382       to the way to way read() works with incomplete operations.  to do this
383       in libkrb5 would be difficult, but valuable.
384     * In the short-term, we deal with blocking by taking over the network
385       send() and recv() functions, therefore making them 'semi-async'.  This
386       doens't apply to DNS yet.These thread-safety context-variables will
387       probably present porting problems, during the MIT port.  This will
388       probably be most of the work in the port to MIT.
389       This may require more thorough thread-safe-ing work on the MIT libraries.
391 4. Many small changes (~15)
393    a. Some extensions to MIT'slibkrb5&   GSSAPI libraries, including
394       GSSAPI ticket-forwarding:  This is a general list of the other
395       extensions Samba4 has made to / need from the kerberos libraries
396       * DCE_STYLE : Microsoft's hard-coded 3-msg Challenge/Response handshake
397         emulates DCE's preference for C/R.  Microsoft calls this DCE_STYLE.
398         MIT already has this nowadays (6/09).
399       * gsskrb5_get_initiator_subkey() (return the exact key that Samba3
400         has always asked for.  gsskrb5_get_subkey() might do what we need
401         anyway).  This routine is necessary, because in some spots,
402         Microsoft uses raw Kerberos keys, outside the Kerberos protocols,
403         as a direct input to MD5 and ARCFOUR, without using the make_priv()
404         or make_safe() calls, and without GSSAPI wrappings etc.
405       * gsskrb5_acquire_creds() (takes keytab and/or ccache as input
406         parameters, see keytab and state machine discussion in prev section)
407       * The new function to handle the PAC fully
408         gsskrb5_extract_authz_data_from_sec_context()
409         need to test that MIT's PAC-handling code checks the PAC's signature.
410       * gsskrb5_wrap_size (Samba still needs this one, for finding out how
411         big the wrapped packet will be, given input length).
412    b. Some refitting in Samba4's use of the MIT libraries;
413    c. Make sure Samba4'sportable socket API   works:
414       * An important detail in the use of libkdc is that we use samba4's
415         own socket lib.  This allows the KDC code to be as portable as
416         the rest of samba, but more importantly it ensures consistancy
417         in the handling of requests, binding to sockets etc.
418       * To handle TCP, we use of our socket layer in much the same way as
419         we deal with TCP for CIFS.  Tridge created a generic packet handling
420         layer for this.
421       * For the client, samba4 likewise must take over the socket functions,
422         so that our single thread smbd will not lock up talking to itself.
423         (We allow processing while waiting for packets in our socket routines).
424         send_to_kdc()  presents to its caller the samba-style socket interface,
425         but the MIT port will reimplement send_to_kdc(), and this routine will
426         use internally the same socket library that MIT-krb uses.
427       * The interface we have defined for libkdc allows for packet injection
428         into the post-socket layer, with a defined krb5_context and
429         kdb5_kdc_configuration structure.  These effectively redirect the
430         kerberos warnings, logging and database calls as we require.
431       * Samba4 socket-library's current TCP support does not send back
432         'too large' error messages if the high bit is set.  This is
433         needed for a proposed extension mechanism (SSL-armored kinit,
434         by Leif Johansson<>), but is currently unsupported
435         in both Heimdal and MIT.
436    d. MIT's GSSAPI code should support some legacy Samba3
437       clients that presentincorrectly-calculated checksums.
438     * Old Clients (samba3 and HPUX clients) use 'selfmade'
439       gssapi/krb5 tokens for use in the CIFS session setup.
440       These hand-crafted ASN.1 packets don't follow rfc1964
441       (GSSAPI) perfectly, so server-side krblib code has to
442       be flexible enough to accept these bent tokens.
443     * It turns out that Windows' GSSAPI server-side code is
444       sloppy about checking some GSSAPI tokens' checksums.
445       During initial work to implement an AD client, it was
446       easier to make an acceptable solution (acceptable to
447       Windows servers) than to correctly implement the
448       GSSAPI specification, particularly on top of the
449       (inflexible) MIT Kerberos API.  It did not seem
450       possible to write a correct, separate GSSAPI
451       implementation on top of MIT Kerberos's public
452       krb5lib API, and at the time, the effort did not
453       need to extend beyond what Windows would require.
454     * The upshot is that old Samba3 clients send GSSAPI
455       tokens bearing incorrect checksums, which AD's
456       GSSAPI library cheerfully accepts (but accepts
457       the good checksums, too).  Similarly, Samba4's
458       Heimdal krb5lib accepts these incorrect checksums.
459       Accordingly, if MIT's krb5lib wants to interoperate
460       with the old Samba3 clients, then MIT's library will
461       have to do the same.
462     * Because these old clients use krb5_mk_req()
463       the app-servers get a chksum field depending on the
464       encryption type, but that's wrong for GSSAPI (see
465       rfc 1964 section 1.1.1). The Checksum type 8003
466       should be used in the Authenticator of the AP-REQ!
467       That (correct use of the 8003 type) would allow
468       the channel bindings, the GCC_C_* req_flags and
469       optional delegation tickets to be passed from the
470       client to the server.  However windows doesn't seem
471       to care whether the checksum is of the wrong type,
472       and for CIFS SessionSetups, it seems that the
473       req_flags are just set to 0.  This deviant checksum
474       can't work for LDAP connections with sign or seal,
475       or for any DCERPC connection, because those
476       connections do not require the negotiation of
477       GSS-Wrap paraemters (signing or sealing of whole
478       payloads).  Note:  CIFS has an independent SMB
479       signing mechanism, using the Kerberos key.
480     * For the code that handles the incorrect&   correct
481       checksums, see heimdal/lib/gssapi/krb5/accept_sec_context.c,
482       lines 390-450 or so.
483     * This bug-compatibility is likely to be controversial
484       in the kerberos community, but a similar need for bug-
485       compatibility arose around MIT's&   Heimdal's both
486       failing to support TGS_SUBKEYs correctly, and there
487       are numerous other cases.
488       see
489     * So, MIT's krb5lib needs to also support old clients!
490    e. Samba4 app-server-host holds aUTF-16 PW, plus a key bitstring;
491       See Appendix 1, "Keytab Requirements."
492    f.In-memory-only credentials cache   for forwarded tickets
493       Samba4 extracts forwarded tickets from the GSSAPI layer,
494       and puts them into the memory-based credentials cache.
495       We can then use them for proxy work.  This needs to be
496       ported, if the MIT library doesn't do it yet.
497    g.In-memory-only keytab   (nice to have):
498       Heimdal used to offer "in-memory keytabs" for servers that use
499       passwords.  These server-side passwords were held in a Samba LDB
500       database called secrets.ldb .  The heimdal library would fetch
501       the server's password from the ldb file and would construct an
502       in-memory keytab struct containing the password, somewhat as if
503       the library had read an MIT-style keytab file.  Unfortunately,
504       only later, at recv_auth() time, would the Heimdal library convert
505       the server-PW into a salted-&-hashed AES key, by hashing 10,000
506       times with SHA-1.  Naturally, this is really too slow for recv_auth(),
507       which runs when an app-server authenticates a client's app-service-
508       request.  So, nowadays, this password-based in-memory keytab  is
509       falling into disuse.
510    h. Get OSSNTLM   authT library: AB says Likewise software
511       probably will give us their freeware "NTLM for MIT-krb"
512       implementation.
513    i. Special Heimdal-specific functions;  These functions didn't
514       exist in the MIT code, years ago, when Samba started.  AB
515       will try to build a final list of these functions:
516       * krb5_free_keyblock_contents()
517       *
518    j.Principal-manipulation functions:  Samba makes extensive
519       use of the principal manipulation functions in Heimdal,
520       including the known structure behind krb_principal and
521       krb5_realm (a char *).  For example,
522       * krb5_parse_name_flags(smb_krb5_context->krb5_context, name,
523                               KRB5_PRINCIPAL_PARSE_REQUIRE_REALM,&principal);
524       * krb5_unparse_name_flags(smb_krb5_context->krb5_context,    principal,
525                               KRB5_PRINCIPAL_UNPARSE_NO_REALM,&new_princ);
526       * krb5_principal_get_realm()
527       * krb5_principal_set_realm()
528       These are needed for juggling the AD variant-structures
529       for server names.
530    k. SpecialShort name rules   check for misconfigured Samba4
531       hostnames;  Samba is highly likely to be misconfigured, in
532       many weird and interesting ways.  So, we have a patch for
533       Heimdal that avoids DNS lookups on names without a "." in
534       them.  This should avoid some delay and root server load.
535       (This errors need to be caught in MIT's library.)
536    l.Improved krb error-messages;
537       krb5_get_error_string():  This Heimdal-specific function
538       does a lot to reduce the 'administrator pain' level, by
539       providing specific, English text-string error messages
540       instead of just error code translations.  (This isn't
541       necessary for the port, but it's more useful than MIT's
542       default err-handling;  Make sure this works for MIT-krb)
543    m.Improved Kerberos logging support:
544       krb5_log_facility(): Samba4 now uses this Heimdal function,
545       which allows us to redirect the warnings and status from
546       the KDC (and client/server Kerberos code) to Samba's DEBUG()
547       system.  Samba uses this logging routine optionally in the
548       main code, but it's required for KDC errors.
549    n. MSGSSMonger   test-suite:  Microsoft has released a krb-specific
550       testsuite called gssmonger, which tests interoperability.  We
551       should compile it against lorikeet-heimdal&   MIT and see if we
552       can build a 'Samba4' server for it.  GSSMonger wasn't intended
553       to be Windows-specific.
554    o.Testsuite for kpasswd daemon:  I have a partial kpasswd server
555       which needs finishing, and a Samba4 needs a client testsuite
556       written, either via the krb5 API or directly against GENSEC and
557       the ASN.1 routines.  Samba4 likes to test failure-modes, not
558       just successful behavior.  Currently Samba4's kpasswd only works
559       for Heimdal, not MIT clients.  This may be due to call-ordering
560       constraints.
563 Appendix 1: Keytab Requirements
565     Traditional 'MIT' keytab operation is very different from AD's
566     account-handling for application-servers:
567     a. Host PWs vs service-keys:
568        * Traditional 'MIT' behaviour is for the app-server to use a keytab
569          containing several named random-bitstring service-keys, created
570          by the KDC.  An MIT-style keytab holds a different service-key
571          for every kerberized application-service that the server offers
572          to clients.  Heimdal also implements this behaviour.  MIT's model
573          doesn't use AD's UTF-16 'service password', and no salting is
574          necessary for service-keys, because each service-key is random
575          enough to withstand an exhaustive key-search attack.
576        * In the Windows model, the server key's construction is very
577          different:  The app-server itself, not the KDC, generates a
578          random UTF-16 pseudo-textual password, and sends this password
579          to the KDC using SAMR, a DCE-RPC "domain-joining" protocol (but
580          for windows 7, see below).  Then, the KDC shares this server-
581          password with every application service on the whole machine.
582        * Only when the app-server uses kerberos does the password get
583          salted by the member server (ie, an AD server-host).  (That
584          is, no salt information appears to be conveyed from the AD KDC
585          to the member server, and the member server must use the rules
586          described in Luke's mail, in Appendix 3, below).  The salted-
587          and-hashed version of the server-host's PW gets stored in the
588          server-host's keytab.
589        * Samba file-servers can have many server-names simultaneously
590          (kind of like web servers' software-virtual-hosting), but since
591          these servers are running in AD, these names can be set up to
592          all share the same secret key.  In AD, co-located server names
593          almost always share a secret key like this.  In samba3, this
594          key-sharing was optional, so some samba3 hosts' keytabs did
595          hold multiple keys.  Samba4 abandons this traditional "old MIT"
596          style of keytab, and only supports one key per keytab, and
597          multiple server-names can use that keytab key in common.  In
598          dealing with this model, Samba4 uses both the traditional file
599          keytab and an in-MEMORY keytabs.
600        * Pre-Windows7 AD and samba3/4 both use SAMR, an older protocol,
601          to jumpstart the member server's PW-sharing with AD (the "windows
602          domain-join process").  This PW-sharing transfers only the PW's
603          UTF-16 text, without any salting or hashing, so that non-krb
604          security mechanisms can use the same utf-16 text PW.  For
605          Windows 7, this domain-joining uses LDAP for PW-setting.
606     b. Flexible server-naming
607        * The other big difference between AD's keytabs and MIT's is that
608          Windows offers a lot more flexibility about service-principals'
609          names. When the kerberos server-side library receives Windows-style tickets
610          from an app-client, MIT's krb library (or GSSAPI) must accommodate
611          Windows' flexibility about case-sensitivity and canonicalization.
612          This means that an incoming application-request to a member server
613          may use a wide variety of service-principal names.  These include:
614                machine$@REALM      (samba clients)
615            HOST/      (win2k clients)
616            cifs/      (winxp clients)
617                HOST/foo@realm      (win2k clients, using netbios)
618                cifs/foo@realm      (winxp clients, using netbios),
619          as well as all upper/lower-case variations on the above.
620     c. Keytabs&   Name-canonicalization
621        * Heimdal's GSSAPI expects to to be called with a principal-name&   a keytab,
622          possibly containing multiple principals' different keys.  However, AD has
623          a different problem to solve, which is that the client may know the member-
624          server by a non-canonicalized principal name, yet AD knows the keytab
625          contains exactly one key, indexed by the canonical name.  So, GSSAPI is
626          unprepared to canonicalize the server-name that the cliet requested, and
627          is also overprepared to do an unnecessary search through the keytab by
628          principal-name.  So Samba's server-side GSSAPI calls have to "game" the
629          GSSAPI, by supplying the server's known canonical name, with the one-key
630          keytab. This doesn't really affect IPA's port of Samba4 to MIT-krb.
631        * Because the number of U/L case combinations got 'too hard' to put into
632          a keytab in the traditional way (with the client to specify the name),
633          we either pre-compute the keys into a traditional keytab or make an
634          in-MEMORY keytab at run time.  In both cases we specify the principal
635          name to GSSAPI, which avoids the need to store duplicate principals.
636        * We use a 'private' keytab in our private dir, referenced from the
637          secrets.ldb by default.
639 Appendix 2: KDC Plugin for Account-Authorization
641 Here is how Samba4 ended up doing account-authorization in
642 Heimdal, via a specialized KDC plugin.  This plugin helps
643 bridge an important gap:  The user's AD record is much richer
644 than the Heimdal HDB format allows, so we do AD-specific
645 access-control checks in the plugin's AD-specific layer,
646 not in the DB-agnostic KDC server:
647     * We created a separate KDC plugin, with this API:
648       typedef struct
649            hdb_entry_ex { void     *ctx;
650                           hdb_entry entry;
651                           void    (*free_entry)(krb5_context, struct hdb_entry_ex *);
652            } hdb_entry_ex;
653       The void *ctx is a "private pointer," provided by the
654       'get' method's hdb_entry_ex retval.  The APIs below use
655       the void *ctx so as to find additional information about
656       the user, not contained in the hdb_entry structure.
657       Both the provider and the APIs below understand how to
658       cast the private void *ctx pointer.
659       typedef krb5_error_code
660             (*krb5plugin_windc_pac_generate)(void * krb5_context,
661                                           struct hdb_entry_ex *,
662                                                     krb5_pac*);
663       typedef krb5_error_code
664             (*krb5plugin_windc_pac_verify)(void *  krb5_context,
665                                         const   krb5_principal,
666                                         struct  hdb_entry_ex *,
667                                         struct  hdb_entry_ex *,
668                                                 krb5_pac *);
669       typedef krb5_error_code
670             (*krb5plugin_windc_client_access)(void * krb5_context,
671                                               struct hdb_entry_ex *,
672                                                      KDC_REQ *,
673                                                      krb5_data *);
674       The krb5_data* here is critical, so that samba's KDC can return
675       the right NTSTATUS code in the 'error string' returned to the
676       client.  Otherwise, the windows client won't get the right error
677       message to the user (such as 'password expired' etc).  The pure
678       Kerberos error is not enough)
679       typedef struct
680               krb5plugin_windc_ftable { int                            minor_version;
681                                         krb5_error_code                (*init)(krb5_context, void **);
682                                         void                           (*fini)(void *);
683                                         krb5plugin_windc_pac_generate   pac_generate;
684                                         krb5plugin_windc_pac_verify     pac_verify;
685                                         krb5plugin_windc_client_access  client_access;
686               } krb5plugin_windc_ftable;
687       This API has some Heimdal-specific stuff, that'll
688       have to change when we port this KDC plugin to MIT krb.
689     * 1st callback (pac_generate)  creates an initial PAC from the user's AD record.
690     * 2nd callback (pac_verify)    checks that a PAC is correctly signed,
691                                    adds additional groups (for cross-realm tickets)
692                                    and re-signs with the key of the target kerberos
693                                    service's account
694     * 3rd callback (client_access) performs additional access checks, such as
695                                    allowedWorkstations and account expiry.
696     * For example, to register this plugin, use the kdc's standard
697       plugin-system at Samba4's initialisation:
698          /* first, setup the table of callback pointers */
699         /* Registar WinDC hooks */
700          ret = krb5_plugin_register(krb5_context, PLUGIN_TYPE_DATA,
701                                     "windc",&windc_plugin_table);
702          /* once registered, the KDC will invoke the callbacks */
703          /* while preparing each new ticket (TGT or app-tkt)   */
704     * An alternative way to register the plugin is with a
705       config-file that names a DSO (Dynamically Shared Object).
707 Appendix 3: Samba4 stuff that doesn't need to get ported.
709 Heimdal oddities
710 * Heimdal is built such that it should be able to serve multiple realms
711     at the same time.  This isn't relevant for Samba's use, but it shows
712     up in a lot of generalisations throughout the code.
713 * Samba4's code originally tried internally to make it possible to use
714     Heimdal's multi-realms-per-KDC ability, but this was ill-conceived,
715     and AB has recently (6/09) ripped the last of that multi-realms
716     stuff out of samba4.  AB says that in AD, it's not really possible
717     to make this work;  several AD components structurally assume that
718     there's one realm per KDC.  However, we do use this to support
719     canonicalization of realm-names:  case variations, plus long-vs-short
720     variants of realm-names.  No MIT porting task here, as long as MIT kdc
721     doesn't refuse to do some LDAP lookups (eg, alias' realm-name looks
722     wrong).
723 * Heimdal supports multiple passwords on a client account:  Samba4
724     seems to call hdb_next_enctype2key() in the pre-authentication
725     routines, to allow multiple passwords per account in krb5.
726     (I think this was intended to allow multiple salts).  AD doesn't
727     support this, so the MIT port shouldn't bother with this.
728 Not needed anymore, because MIT's code now handles PACs fully:
729 * gss_krb5_copy_service_keyblock() (get the key used to actually
730     encrypt the ticket to the server, because the same key is used for
731     the PAC validation).
732 * gsskrb5_extract_authtime_from_sec_context (get authtime from
733     kerberos ticket)
734 * gsskrb5_extract_authz_data_from_sec_context (get authdata from
735     ticket, ie the PAC.  Must unwrap the data if in an AD-IFRELEVANT)]
736 Authz data extraction
737 * We use krb5_ticket_get_authorization_data_type(), and expect
738     it to return the correct authz data, even if wrapped in an
739     AD-IFRELEVANT container.  This doesn't need to be ported to MIT.
740     This should be obsoleted by MIT's new PAC code.
741 libkdc
742 * Samba4 needs to be built as a single binary (design requirement),
743     and this should include the KDC.  Samba also (and perhaps more
744     importantly) needs to control the configuration environment of
745     the KDC.
746 * But, libkdc doesn't matter for IPA; Samba invokes the Heimdal kdc
747     as a library call, but this is just a convenience, and the MIT
748     port can do otherwise w/o trouble.)
749 Returned Salt for PreAuthentication
750     When the AD-KDC replies to pre-authentication, it returns the
751     salt, which may be in the form of a principalName that is in no
752     way connected with the current names.  (ie, even if the
753     userPrincipalName and samAccountName are renamed, the old salt
754     is returned).
755     This is the kerberos standard salt, kept in the 'Key'.  The
756     AD generation rules are found in a Mail from Luke Howard dated
757     10 Nov 2004.  The MIT glue layer doesn't really need to care about
758     these salt-handling details;  the samba4 code&   the LDAP backend
759     will conspire to make sure that MIT's KDC gets correct salts.
760     >
761     >    From: Luke Howard<>
762     >    Organization: PADL Software Pty Ltd
763     >    To:
764     >    Date: Wed, 10 Nov 2004 13:31:21 +1100
765     >    Cc:,
766     >    Subject: Re: Samba-3.0.7-1.3E Active Directory Issues
767     >    -------
768     >
769     >    Did some more testing, it appears the behaviour has another
770     >    explanation. It appears that the standard Kerberos password salt
771     >    algorithm is applied in Windows 2003, just that the source principal
772     >    name is different.
773     >
774     >    Here is what I've been able to deduce from creating a bunch of
775     >    different accounts:
776     >    [SAM name in this mail means the AD attribute samAccountName .
777     >     E.g., jbob for a user and jbcomputer$ for a computer.]
778     >
779     >    [UPN is the AD userPrincipalName attribute.  For example,]
780     >    Type of account                        Principal for Salting
781     >    ========================================================================
782     >    Computer Account                host/<SAM-Name-Without-$>.realm@REALM
783     >    User Account Without UPN<SAM-Name>@REALM
784     >    User Account With UPN<LHS-Of-UPN>@REALM
785     >
786     >    Note that if the computer account's SAM account name does not include
787     >    the trailing '$', then the entire SAM account name is used as input to
788     >    the salting principal. Setting a UPN for a computer account has no
789     >    effect.
790     >
791     >    It seems to me odd that the RHS of the UPN is not used in the salting
792     >    principal. For example, a user with UPN in the realm
793     >    MYREALM.COM would have a salt of MYREALM.COMfoo. Perhaps this is to
794     >    allow a user's UPN suffix to be changed without changing the salt. And
795     >    perhaps using the UPN for salting signifies a move away SAM names and
796     >    their associated constraints.
797     >
798     >    For more information on how UPNs relate to the Kerberos protocol,
799     >    see:
800     >
801     >
802     >
803     >    -- Luke