1 Copyright Andrew Bartlett <abartlet@samba.org> 2005-2009
2 Copyright Donald T. Davis <don@mit.edu>
4 Released under the GPLv3
6 Important context for porting to MIT
7 ------------------------------------
9 This document should be read in conjuction with the Samba4 source code.
10 DAL and KDC requirements are expressed (as an implementation against Heimdal's
11 HDB abstraction layer) in Samba4's source4/kdc/hdb-samba4.c in particular.
12 hbd-samba4.c is the biggest piece of samba-to-krb glue layer, so the main
13 part of the port to MIT is to replace hdb-samba4 with a similar glue layer
14 that's designed for MIT's code.
16 PAC requirements are implemeneted in source4/kdc/pac-glue.c
18 The plugins (both of the above are Heimdal plugins) for the above are loaded
21 For GSSAPI requirements, see auth/gensec/gensec_gssapi.c (the consumer of
24 For Kerberos requirements, see auth/kerberos/krb5_init_context.c .
26 Samba has its own credentials system, wrapping GSS creds, just as GSS
27 creds wrap around krb5 creds. For the interaction between Samba4 credentials
28 system and GSSAPI and Kerberos see auth/credentials/credentials_krb5.c .
30 AllowedWorkstationNames and Krb5
31 --------------------------------
33 Microsoft uses the clientAddresses *multiple value* field in the krb5
34 protocol (particularly the AS_REQ) to communicate the client's netbios
35 name (legacy undotted name, <14 chars)
37 This is (my guess) to support the userWorkstations field (in user's AD record).
38 The idea is to support client-address restrictions, as was standard in NT:
39 The AD authentication server I imagine checks the netbios address against
40 this userWorkstations value (BTW, the NetLogon server does this, too).
42 The checking of this field implies a little of the next question:
44 Is a DAL the layer we need?
45 ---------------------------
47 Looking at what we need to pass around, I don't think
48 the DAL is even the right layer; what we really want
49 is to create an account-authorization abstraction layer
50 (e.g., is this account permitted to login to this computer,
52 Here is how we ended up doing this in Heimdal:
53 * We created a separate plugin, with this API:
54 typedef struct hdb_entry_ex {
57 void (*free_entry)(krb5_context, struct hdb_entry_ex *);
60 * The void *ctx is a "private pointer," provided by the 'get' method's
61 hdb_entry_ex retval. The APIs below use the void *ctx so as to find
62 additional information about the user, not contained in the hdb_entry
63 structure. Both the provider and the APIs below understand how to cast
64 the private void *ctx pointer.
66 typedef krb5_error_code
67 (*krb5plugin_windc_pac_generate)(void *, krb5_context,
68 struct hdb_entry_ex *, krb5_pac*);
69 typedef krb5_error_code
70 (*krb5plugin_windc_pac_verify)(void *, krb5_context,
72 struct hdb_entry_ex *,
73 struct hdb_entry_ex *,
75 typedef krb5_error_code
76 (*krb5plugin_windc_client_access)(void *,
78 struct hdb_entry_ex *,
79 KDC_REQ *, krb5_data *);
81 * (The krb5_data* here is critical, so that samba's KDC can return
82 the right NTSTATUS code in the 'error string' returned to the client.
83 Otherwise, the windows client won't get the right error message to
84 the user (such as 'password expired' etc). The pure Kerberos error
87 typedef struct krb5plugin_windc_ftable {
89 krb5_error_code (*init)(krb5_context, void **);
91 rb5plugin_windc_pac_generate pac_generate;
92 krb5plugin_windc_pac_verify pac_verify;
93 krb5plugin_windc_client_access client_access;
94 } krb5plugin_windc_ftable;
95 This API has some heimdal-specific stuff, that'll have to change when we port the plugin to MIT krb.
96 * 1st callback (pac_generate) creates an initial PAC from the user's AD record.
97 * 2nd callback (pac_verify) check that a PAC is correctly signed, add additional groups (for cross-realm tickets) and re-sign with the key of the target kerberos service's account
98 * 3rd callback (client_access) perform additional access checks, such as allowedWorkstations and account expiry.
99 * for example, to register this plugin, use the kdc's standard
100 plugin-system at Samba4's initialisation:
101 /* first, setup the table of callback pointers */
102 /* Registar WinDC hooks */
103 ret = krb5_plugin_register(krb5_context,
104 PLUGIN_TYPE_DATA, "windc",
105 &windc_plugin_table);
106 /* once registered, the KDC will invoke the callbacks */
107 /* while preparing each new ticket (TGT or app-tkt) */
108 * an alternate way to register the plugin is with a config-file that names
109 a DSO (Dynamically Shared Object).
112 This plugin helps bridge an important gap: The user's AD record is much
113 richer than the Heimdal HDB format allows, so we do AD-specific access
114 control checks in an AD-specific layer (ie, the plugin), not in the
115 DB-agnostic KDC server.
117 In Novell's pure DAL approach, the DAL only read in the principalName as
118 the key, so it had trouble performing access-control decisions on things
119 other than the name (like the addresses).
121 There is another, currently unhandled challenge in this area - the need to handle
122 bad password counts (and good password notification), so that a single policy can
123 be applied against all means of checking a password (NTLM, Kerberos, LDAP Simple
126 The Original work by Novell in creating a DAL did not seem to provide a way to
127 update the PW counts information. Nevertheless, we know that this is very much
128 required (and may have been addressed in Simo's subsequent IPA-KDC design),
129 because in Samba3+eDirectory, great lengths are taken to update this information.
131 GSSAPI layer requirements
132 -------------------------
134 Welcome to the wonderful world of canonicalisation
136 The MIT Krb5 libs (including GSSAPI) do not support kinit returning a different
137 realm to what the client asked for, even just in case differences.
139 Heimdal has the same problem, and this too applies to the krb5 layer, not
142 there's two kinds of name-canonicalization that can occur:
143 * lower-to-upper case conversion, because Windows domain names are
144 usually in upper case;
145 * an unrecognizable subsitution of names, such as might happen when
146 a user requests a ticket for a NetBIOS domain name, but gets back
147 a ticket for the corresponging FQDN.
149 As developers, we should test if the AD KDC's name-canonicalisation
150 can be turned off with the KDCOption flags in the AS-REQ or TGS-REQ;
151 Windows clients always send the Canonicalize flags as KDCOption values.
153 Old Clients (samba3 and HPUX clients) use 'selfmade' gssapi/krb5 tokens
154 for use in the CIFS session setup. these hand-crafted ASN.1 packets don't
155 follow rfc1964 perfectly, so server-side krblib code has to be flexible
156 enough to accept these bent tokens.
157 It turns out that Windows' GSSAPI server-side code is sloppy about checking
158 some GSSAPI tokens' checksums. During initial work to implement an AD client,
159 it was easier to make an acceptable solution (to Windows servers) than to
160 correctly implement the GSSAPI specification, particularly on top of the
161 (inflexible) MIT Kerberos API. It did not seem possible to write a correct,
162 seperate GSSAPI implementation on top of MIT Kerberos's public krb5lib API,
163 and at the time, the effort did not need to extend beyond what Windows would
166 The upshot is that old Samba3 clients send GSSAPI tokens bearing incorrect
167 checksums, which AD's Krb5lib cheerfully accepts (but accepts the good checksums,
168 too). Similarly, Samba4's heimdal krb5lib accepts these incorrect checksums.
169 Accordingly, if MIT's krb5lib wants to interoperate with the old Samba3 clients,
170 then MIT's library will have to do the same.
172 Because these old clients use krb5_mk_req()
173 the app-servers get a chksum field depending on the encryption type, but that's
174 wrong for GSSAPI (see rfc 1964 section 1.1.1). The Checksum type 8003 should
175 be used in the Authenticator of the AP-REQ! That (correct use of the 8003 type)
176 would allows the channel bindings, the GCC_C_* req_flags and optional delegation
177 tickets to be passed from the client to the server. However windows doesn't
178 seem to care whether the checksum is of the wrong type, and for CIFS SessionSetups,
179 it seems that the req_flags are just set to 0.
180 This deviant checksum can't work for LDAP connections with sign or seal, or
181 for any DCERPC connection, because those connections do not require the
182 negotiation of GSS-Wrap paraemters (signing or sealing of whole payloads).
183 Note: CIFS has an independent SMB signing mechanism, using the Kerberos key.
185 see heimdal/lib/gssapi/krb5/accept_sec_context.c, lines 390-450 or so.
187 This bug-compatibility is likely to be controversial in the kerberos community,
188 but a similar need for bug-compatibility arose around MIT's & Heimdal's both
189 failing to support TGS_SUBKEYs correctly, and there are numerous other cases.
190 see https://lists.anl.gov/pipermail/ietf-krb-wg/2009-May/007630.html
192 So MIT's krb5lib needs to also support old clients!
194 Principal Names, long and short names
195 -------------------------------------
197 As far as servicePrincipalNames are concerned, these are not
198 canonicalised by AD's KDC, except as regards the realm in the reply.
199 That is, the client gets back the principal it asked for, with
200 the realm portion 'fixed' to uppercase, long form.
201 Heimdal doesn't canonicalize names, but Samba4 does some canonicalization:
202 For hostnames and usernames, Samba4 canonicalizes the requested name only
203 for the LDAP principal-lookup, but then Samba4 returns the retrieved LDAP
204 record with the request's original, uncanonicalized hostname replacing the
205 canonicalized name that actually was retrieved.
206 AB says that for usernames, Samba4 used to return the canonicalized username,
207 as retrieved from LDAP. The reason for the different treatment was that
208 the user needs to present his own canonicalized username to servers, for
209 ACL-matching. For hostnames this isn't necessary.
210 So, for bug-compatibility, we may need to optionally disable any
211 namne-canonicalization that MIT's KDC does.
213 The short name of the realm seems to be accepted for at least AS_REQ
214 operations, but the AD KDC always performs realm-canonicalisation,
215 which converts the short realm-name to the canonical long form.
216 So, this causes pain for current krb client libraries.
218 The canonicalisation of names matters not only for the KDC, but also
219 for code that has to deal with keytabs.
220 With credential-caches, when canonicalization leads to cache-misses,
221 the client just asks for new credentials for the variant server-name.
222 This could happen, for example, if the user asks to access the server
223 twice, using different variants of the server-name.
225 We also need to handle type 10 names (NT-ENTERPRISE), which are a full
226 principal name in the principal field, unrelated to the realm.
227 The principal field contains both principal & realm names, while the
228 realm field contains a realm name, too, possibly different.
229 For example, an NT-ENTERPRISE principal name might look like:
230 joeblow@microsoft.com@NTDEV.MICROSOFT.COM ,
231 <--principal field-->|<----realm name--->|
233 Where joe@microsoft.com is the leading portion, and NTDEV.MICROSOFT.COM is
234 the realm. This is used for the 'email address-like login-name' feature of AD.
239 There is another post somewhere (ref lost for the moment) that details
240 where in active directory the list of stored aliases for HOST/ is.
241 This list is read & parsed by the AD KDC, so as to allow any of these
242 aliased ticket-requests to use the HOST/ key.
244 Samba4 currently has set:
245 sPNMappings: host=ldap,dns,cifs,http (but dns's presence is a bug, somehow)
247 AD actually has ~50 entries:
249 sPNMappings: host=alerter,appmgmt,cisvc,clipsrv,browser,dhcp,dnscache,replicat
250 or,eventlog,eventsystem,policyagent,oakley,dmserver,dns,mcsvc,fax,msiserver,i
251 as,messenger,netlogon,netman,netdde,netddedsm,nmagent,plugplay,protectedstora
252 ge,rasman,rpclocator,rpc,rpcss,remoteaccess,rsvp,samss,scardsvr,scesrv,seclog
253 on,scm,dcom,cifs,spooler,snmp,schedule,tapisrv,trksvr,trkwks,ups,time,wins,ww
254 w,http,w3svc,iisadmin,msdtc
256 Domain members that expect the longer list will break in damb4, as of 6/09.
257 AB says he'll try to fix this right away.
259 For example, this is how HTTP/, and CIFS/ can use HOST/ without
260 any explicit entry in the servicePrincipalName attribute
263 For example, the application-server might have (on its AD record):
264 servicePrincipalName: HOST/my.computer@MY.REALM
266 but the client asks for a ticket to cifs/my.computer@MY.REALM
267 AD looks in LDAP for both name-variants
268 AD then transposes cifs -> host after performing the lookup in the
269 directory (for the original name), then looks for host/my.computer@MY.REALM
271 for hostnames & usernames, alternate names appear as extra values in
272 the multivalued "principal name" attributes:
273 - For hostnames, the other names (other than it's short name, implied
274 from the CN), is stored in the servicePrincipalName
275 - For usernames, the other names are stored in the userPrincipalName
276 attribute, and can be full e-mail address like names, such as
277 joe@microsoft.com (see above).
279 Jean-Baptiste.Marchand@hsc.fr reminds me:
280 > This is the SPNMappings attribute in Active Directory:
281 > http://msdn.microsoft.com/library/en-us/adschema/adschema/a_spnmappings.asp
283 We implement this in hdb-ldb.
285 Implicit names for Win2000 Accounts
286 -----------------------------------
287 AD's records for servers are keyed by CN or by servicePrincipalName,
288 but for win2k boxes, these records don't include servicePrincipalName,
289 so, the CN attribute is used instead.
290 Despite not having a servicePrincipalName on accounts created
291 by computers running win2000, it appears we are expected
292 to have an implicit mapping from host/computer.full.name and
293 host/computer to the computer's entry in the AD LDAP database
294 (ie, be able to obtain tickets for that host name in the KDC).
296 Returned Salt for PreAuthentication
297 -----------------------------------
299 When the KDC replies for pre-authentication, it returns the Salt,
300 which may be in the form of a principalName that is in no way
301 connected with the current names. (ie, even if the userPrincipalName
302 and samAccountName are renamed, the old salt is returned).
304 This is the kerberos standard salt, kept in the 'Key'. The
305 AD generation rules are found in a Mail from Luke Howard dated
306 10 Nov 2004. The MIT glue layer doesn't really need to care about
307 these salt-handling details; the samba4 code & the LDAP backend
308 will conspire to make sure that MIT's KDC gets correct salts.
311 From: Luke Howard <lukeh@padl.com>
312 Organization: PADL Software Pty Ltd
314 Date: Wed, 10 Nov 2004 13:31:21 +1100
315 Cc: huaraz@moeller.plus.com, samba-technical@lists.samba.org
316 Subject: Re: Samba-3.0.7-1.3E Active Directory Issues
319 Did some more testing, it appears the behaviour has another
320 explanation. It appears that the standard Kerberos password salt
321 algorithm is applied in Windows 2003, just that the source principal
324 Here is what I've been able to deduce from creating a bunch of
326 [SAM name in this mail means the AD attribute samAccountName .
327 E.g., jbob for a user and jbcomputer$ for a computer.]
329 [UPN is the AD userPrincipalName attribute. For example, jbob@mydomain.com]
331 Type of account Principal for Salting
332 ========================================================================
333 Computer Account host/<SAM-Name-Without-$>.realm@REALM
334 User Account Without UPN <SAM-Name>@REALM
335 User Account With UPN <LHS-Of-UPN>@REALM
337 Note that if the computer account's SAM account name does not include
338 the trailing '$', then the entire SAM account name is used as input to
339 the salting principal. Setting a UPN for a computer account has no
342 It seems to me odd that the RHS of the UPN is not used in the salting
343 principal. For example, a user with UPN foo@mydomain.com in the realm
344 MYREALM.COM would have a salt of MYREALM.COMfoo. Perhaps this is to
345 allow a user's UPN suffix to be changed without changing the salt. And
346 perhaps using the UPN for salting signifies a move away SAM names and
347 their associated constraints.
349 For more information on how UPNs relate to the Kerberos protocol,
352 http://www.ietf.org/proceedings/01dec/I-D/draft-ietf-krb-wg-kerberos-referrals-02.txt
361 Heimdal is built such that it should be able to serve multiple realms
362 at the same time. This isn't relevant for Samba's use, but it shows
363 up in a lot of generalisations throughout the code.
365 Samba4's code originally tried internally to make it possible to use
366 Heimdal's multi-realms-per-KDC ability, but this was ill-conceived,
367 and AB has recently (6/09) ripped the last of that multi-realms
368 stuff out of samba4. AB says that in AD, it's not really possible
369 to make this work; several AD components structurally assume that
370 there's one realm per KDC. However, we do use this to support
371 canonicalization of realm-names: case variations, plus long-vs-short
372 variants of realm-names.
375 - Heimdal supports multiple passwords on a client account: Samba4
376 seems to call hdb_next_enctype2key() in the pre-authentication
377 routines to allow multiple passwords per account in krb5.
378 (I think this was intended to allow multiple salts).
379 AD doesn't support this, so the MIT port shouldn't bother with
382 State Machine safety when using Kerberos and GSSAPI libraries
383 -------------------------------------------------------------
385 Samba's client-side & app-server-side libraries are built on a giant
386 state machine, and as such have very different
387 requirements to those traditionally expressed for kerberos and GSSAPI
390 Samba requires all of the libraries it uses to be state machine safe in
391 their use of internal data. This does not mean thread safe, and an
392 application could be thread safe, but not state machine safe (if it
393 instead used thread-local variables).
395 So, what does it mean for a library to be state machine safe? This is
396 mostly a question of context, and how the library manages whatever
397 internal state machines it has. If the library uses a context
398 variable, passed in by the caller, which contains all the information
399 about the current state of the library, then it is safe. An example
400 of this state is the sequence number and session keys for an ongoing
403 The other issue affecting state machines is 'blocking' (waiting for a
404 read on a network socket). Samba's non-blocking I/O doesn't like
405 waiting for libkrb5 to go away for awhile to talk to the KDC.
407 Samba4 provides a hook 'send_to_kdc', that allows Samba4 to take over the
408 IO handling, and run other events in the meantime. This uses a
409 'nested event context' (which presents the challenges that the kerberos
410 library might be called again, while still in the send_to_kdc hook).
412 Heimdal has this 'state machine safety' in parts, and we have modified
413 the lorikeet branch to improve this behviour, when using a new,
414 non-standard API to tunnelling a ccache (containing a set of tickets)
415 through the gssapi, by temporarily casting the ccache pointer to a
416 gss credential pointer.
417 This new API is Heimdal's samba4-requested gss_krb5_import_cred() fcn;
418 this will have to be rewritten or ported in the MIT port.
420 This replaces an older scheme using the KRB5_CCACHE
421 environment variable to get the same job done. This tunnelling trick
422 enables a command-line app-client to run kinit tacitly, before running
423 GSSAPI for service-authentication. This tunnelling trick avoids the
424 more usual approach of keeping the ccache pointer in a global variable.
426 No longer true; the krb5_context global is gone now:
427 [Heimdal uses a per-context variable for the 'krb5_auth_context', which
428 controls the ongoing encrypted connection, but does use global
429 variables for the ubiquitous krb5_context parameter.]
431 The modification that has added most to 'state machine safety' of
432 GSSAPI is the addition of the gss_krb5_acquire_creds() function. This
433 allows the caller to specify a keytab and ccache, for use by the
434 GSSAPI code. Therefore there is no need to use global variables to
435 communicate this information about keytab & ccache.
437 At a more theoritical level (simply counting static and global
438 variables) Heimdal is not state machine safe for the GSSAPI layer.
439 (Heimdal is now (6/09) much more nearly free of globals.)
440 The Krb5 layer alone is much closer, as far as I can tell, blocking
444 As an alternate to fixing MIT Kerberos for better safety in this area,
445 a new design might be implemented in Samba, where blocking read/write
446 is made to the KDC in another (fork()ed) child process, and the results
447 passed back to the parent process for use in other non-blocking operations.
449 To deal with blocking, we could have a fork()ed child per context,
450 using the 'GSSAPI export context' function to transfer
451 the GSSAPI state back into the main code for the wrap()/unwrap() part
452 of the operation. This will still hit issues of static storage (one
453 gss_krb5_context per process, and multiple GSSAPI encrypted sessions
454 at a time) but these may not matter in practice.
456 This approach has long been controversial in the Samba team.
457 An alternate way would be to be implement E_AGAIN in libkrb5: similar
458 to the way to way read() works with incomplete operations. to do this
459 in libkrb5 would be difficult, but valuable.
461 In the short-term, we deal with blocking by taking over the network
462 send() and recv() functions, therefore making them 'semi-async'. This
463 doens't apply to DNS yet.These thread-safety context-variables will
464 probably present porting problems, during the MIT port. This will
465 probably be most of the work in the port to MIT.
469 GSSAPI and Kerberos extensions
470 ------------------------------
472 This is a general list of the other extensions we have made to / need from
473 the kerberos libraries
475 - DCE_STYLE : Microsoft's hard-coded 3-msg Challenge/Response handshake
476 emulates DCE's preference for C/R. Microsoft calls this DCE_STYLE.
477 MIT already has this nowadays (6/09).
479 - gsskrb5_get_initiator_subkey() (return the exact key that Samba3
480 has always asked for. gsskrb5_get_subkey() might do what we need
481 anyway). This is necessary, because in some spots, Microsoft uses
482 raw Kerberos keys, outside the Kerberos protocls, and not using Kerberos
483 wrappings etc. Ie, as a direct input to MD5 and ARCFOUR, without using
484 the make_priv() or make_safe() calls.
486 - gsskrb5_acquire_creds() (takes keytab and/or ccache as input
487 parameters, see keytab and state machine discussion in prev section)
489 Not needed anymore, because MIT's code now handles PACs fully:
490 - gss_krb5_copy_service_keyblock() (get the key used to actually
491 encrypt the ticket to the server, because the same key is used for
493 - gsskrb5_extract_authtime_from_sec_context (get authtime from
495 - gsskrb5_extract_authz_data_from_sec_context (get authdata from
496 ticket, ie the PAC. Must unwrap the data if in an AD-IFRELEVENT)]
497 The new function to handle the PAC fully
498 - gsskrb5_extract_authz_data_from_sec_context()
500 Samba still needs this one:
501 - gsskrb5_wrap_size (find out how big the wrapped packet will be,
507 Because windows machine account handling is very different to the
508 traditional 'MIT' keytab operation.
509 This starts when we look at the basics of the secrets handling:
511 Samba file-servers can have many server-name simultaneously (kindof
512 like web servers' software virtual hosting), but since these servers
513 are running in AD, these names are free to be set up to all share
514 the same secret key. In AD, host-sharing server names almost always
515 share a secret key like this. In samba3, this key-sharing was optional, so
516 some samba3 hosts' keytabs did hold multiple keys. samba4 abandons this
517 traditional "old MIT" style of keytab, and only supports one key per keytab,
518 and multiple server-names can use that keytab key in common.
519 Heimdal offered "in-memory keytabs" for servers that use passwords.
520 These server-side passwords were held in a Samba LDB database called secrets.ldb,
521 and the heimdal library would be supplied the password from the ldb file and
522 would construct an in-memory keytab struct containing the password,
523 just as if the library had read an MIT-style keytab file.
524 Unfortunately, only later, at recv_auth() time, would the heimdal library
525 convert the PW into a salted-&-hashed AES key, by hashing 10,000 times with
526 SHA-1. So, nowadays, this password-based in-memory keytab is seen as too
527 slow, and is falling into disuse.
529 Traditional 'MIT' behaviour is to use a keytab, containing salted key
530 data, extracted from the KDC. (In this modal, there is no 'service
531 password', instead the keys are often simply application of random
532 bytes). Heimdal also implements this behaviour.
534 The windows modal is very different - instead of sharing a keytab with
535 each member server, a random utf-16 pseudo-textual password is stored
536 for the whole machine.
537 The password is set with non-kerberos mechanisms (particularly SAMR,
538 a DCE-RPC service) and when interacting on a kerberos basis, the
539 password is salted by the member server (ie, an AD server-host).
540 (That is, no salt information appears to be conveyed from the AD KDC
541 to the member server. ie, the member server must use the rule's
542 described in Luke's mail above).
544 pre-win7 AD and samba3/4 both use SAMR, an older protocol, to jumpstart
545 the member server's PW-sharing with AD (the "windows domain-join process").
546 This PW-sharing transfers only the PW's utf-16 text, without any salting
547 or hashing, so that non-krb security mechanisms can use the same utf-16
548 text PW. for windows 7, this domain-joining uses LDAP for PW-setting.
550 In dealing with this model, we use both the traditional file
551 keytab and in-MEMORY keytabs.
553 When dealing with a windows KDC, the behaviour regarding case
554 sensitivity and canonacolisation must be accomidated. This means that
555 an incoming request to a member server may have a wide variety of
556 service principal names. These include:
558 machine$@REALM (samba clients)
559 HOST/foo.bar@realm (win2k clients)
560 HOST/foo@realm (win2k clients, using netbios)
561 cifs/foo.bar@realm (winxp clients)
562 cifs/foo@realm (winxp clients, using netbios)
564 as well as all case variations on the above.
566 Heimdal's GSSAPI expects to get a principal-name & a keytab, possibly containing
567 multiple principals' different keys. However, AD has a different problem to
568 solve, which is that the client may know the member-server by a non-canonicalized
569 principal name, yet AD knows the keytab contains exactly one key, indexed by
570 the canonical name. So, GSSAPI is unprepared to canonicalize the server-name
571 that the cliet requested, and is also overprepared to do an unnecessary search
572 through the keytab by principal-name. So samba's server-side GSSAPI calls game
573 the GSSAPI, by supplying the server's known canonical name, and the one-key keytab.
574 this doesn't really affect the port to mit-krb.
576 Because the number of U/L case combinations got 'too hard' to put into a keytab in the
577 traditional way (with the client to specify the name), we either
578 pre-compute the keys into a traditional keytab or make an in-MEMORY
579 keytab at run time. In both cases we specifiy the principal name to
580 GSSAPI, which avoids the need to store duplicate principals.
582 We use a 'private' keytab in our private dir, referenced from the
583 secrets.ldb by default.
585 Extra Heimdal functions used
586 ----------------------------
587 these fcns didn't exist in the MIT code, years ago, when samba started.
588 AB will try to build a final list of these fcns.
590 (an attempt to list some of the Heimdal-specific functions I know we use)
592 krb5_free_keyblock_contents()
594 also a raft of prinicpal manipulation functions:
596 Prncipal Manipulation
597 ---------------------
599 Samba makes extensive use of the principal manipulation functions in
600 Heimdal, including the known structure behind krb_principal and
601 krb5_realm (a char *). for example,
602 krb5_parse_name_flags(smb_krb5_context->krb5_context, name,
603 KRB5_PRINCIPAL_PARSE_MUST_REALM, &principal);
604 krb5_princ_realm(smb_krb5_context->krb5_context, principal);
605 krb5_unparse_name_flags(smb_krb5_context->krb5_context, principal,
606 KRB5_PRINCIPAL_UNPARSE_NO_REALM, &new_princ);
607 These are needed for juggling the AD variant-structures for server names.
609 Authz data extraction
610 ---------------------
612 We use krb5_ticket_get_authorization_data_type(), and expect it to
613 return the correct authz data, even if wrapped in an AD-IFRELEVENT container.
618 We have modified Heimdal's 'hdb' interface to specify the 'class' of
619 Principal being requested. This allows us to correctly behave with
620 the different 'classes' of Principal name. This is necessary because
621 of the AD structure, which uses very different record-structures
622 for user-principals, trust principals & server-principals.
624 We currently define 3 classes:
627 - krbtgt (kinit, tgt) the kdc's own ldap record
629 I also now specify the kerberos principal as an explict parameter to LDB_fetch(),
630 not an in/out value on the struct hdb_entry parameter itself.
632 Private Data pointer (and windc hooks) (see above):
633 In addition, I have added a new interface hdb_fetch_ex(), which
634 returns a structure including a private data-pointer, which may be used
635 by the windc plugin inferface functions. The windc plugin provides
636 the hook for the PAC, as well as a function for the main access control routines.
638 A new windc plugin function should be added to increment the bad password counter
641 libkdc (doesn't matter for IPA; Samba invokes the Heimdal kdc as a library call,
642 but this is just a convenience, and the MIT port can do otherwise w/o trouble.)
645 Samba4 needs to be built as a single binary (design requirement), and
646 this should include the KDC. Samba also (and perhaps more
647 importantly) needs to control the configuration environment of the
650 The interface we have defined for libkdc allow for packet injection
651 into the post-socket layer, with a defined krb5_context and
652 kdb5_kdc_configuration structure. These effectively redirect the
653 kerberos warnings, logging and database calls as we require.
655 Using our socket lib (para 3 does matter for the send_to_kdc() plugin).
656 See also the discussion about state machine safety above)
659 An important detail in the use of libkdc is that we use samba4's own socket
660 lib. This allows the KDC code to be as portable as the rest of samba
661 (this cuts both ways), but far more importantly it ensures a
662 consistancy in the handling of requests, binding to sockets etc.
664 To handle TCP, we use of our socket layer in much the same way as
665 we deal with TCP for CIFS. Tridge created a generic packet handling
668 For the client, samba4 likewise must take over the socket functions,
669 so that our single thread smbd will not lock up talking to itself.
670 (We allow processing while waiting for packets in our socket routines).
671 send_to_kdc() presents to its caller the samba-style socket interface,
672 but the MIT port will reimplement send_to_kdc(), and this routine will
673 use internally the same socket library that MIT-krb uses.
675 Kerberos logging support (this will require porting attention)
676 ------------------------
678 Samba4 now (optionally in the main code, required for the KDC) uses the
679 krb5_log_facility from Heimdal. This allows us to redirect the
680 warnings and status from the KDC (and client/server kerberos code) to
681 Samba's DEBUG() system.
683 Similarly important is the Heimdal-specific krb5_get_error_string()
684 function, which does a lot to reduce the 'administrator pain' level,
685 by providing specific, english text-string error messages instead of
686 just error code translations. (this isn't necessarty for the port,
687 but it's more useful than MIT's default err-handling; make sure
688 this works for MIT-krb)
694 Samba is highly likely to be misconfigured, in many weird and
695 interesting ways. As such, we have a patch for Heimdal that avoids
696 DNS lookups on names without a . in them. This should avoid some
697 delay and root server load. (this may need to be ported to MIT.)
702 We now put the PAC into the TGT, not just the service ticket.
707 We extract forwarded tickets from the GSSAPI layer, and put
708 them into the memory-based credentials cache.
709 We can then use them for proxy work.
715 (Feel free to contribute to any of these tasks, or ask
716 abartlet@samba.org about them).
718 Lockout Control (still undone in samba4 on heimdal)
721 We need to get (either if PADL publishes their patch, or write our
722 own) access control hooks in the Heimdal KDC. We need to lockout
723 accounts (eg, after 10 failed PW-attemps), and perform other controls.
724 This is standard AD behavior, that samba4 needs to get right, whether
725 heimdal or MIT-krb is doing the ticket work.
730 Microsoft has released a krb-specific testsuite called gssmonger,
731 which tests interop. We should compile it against lorikeet-heimdal,
732 MIT and see if we can build a 'Samba4' server for it.
733 GSSMonger wasn't intended to be Windows-specific.
735 Kpasswd server (kpasswd server is now finished, but not testsuite)
738 I have a partial kpasswd server which needs finishing, and a we need a
739 client testsuite written, either via the krb5 API or directly against
740 GENSEC and the ASN.1 routines.
741 Samba4 likes to test failure-modes, not just successful behavior.
743 Currently it only works for Heimdal, not MIT clients. This may be due
744 to call ordering constraints.
750 Samba4 socket-library's current TCP support does not send back 'too large'
751 error messages if the high bit is set. This is needed for a proposed extension
752 mechanism (SSL-armored kinit, by Leif Johansson <leifj@it.su.se>),
753 but is likewise unsupported in both current Heimdal and MIT.
755 =========================================================================
756 AB says MIT's 1.7 announcement about AD support covers Luke Howard's
757 changes. It all should be easy for IPA to exploit/use during the port
759 AB says Likewise software will likely give us their freeware NTLM/MIT-krb