Correct "specifiy" typos.
[samba.git] / source4 / auth / kerberos / kerberos-notes.txt
1 Copyright Andrew Bartlett <abartlet@samba.org> 2005-2009
2 Copyright Donald T. Davis <don@mit.edu>  
3
4 Released under the GPLv3
5
6 Important context for porting to MIT
7 ------------------------------------
8
9 This document should be read in conjunction 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.
15
16 PAC requirements are implemeneted in source4/kdc/pac-glue.c
17
18 The plugins (both of the above are Heimdal plugins) for the above are loaded 
19 in source4/kdc/kdc.c
20
21 For GSSAPI requirements, see auth/gensec/gensec_gssapi.c (the consumer of 
22 GSSAPI in Samba4)
23
24 For Kerberos requirements, see auth/kerberos/krb5_init_context.c .
25
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 .
29
30 AllowedWorkstationNames and Krb5
31 --------------------------------
32
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)
36
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).
41
42 The checking of this field implies a little of the next question:
43
44 Is a DAL the layer we need?
45 ---------------------------
46
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,
51 at this time?).  
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 {
55          void *ctx;
56          hdb_entry entry;
57          void (*free_entry)(krb5_context, struct hdb_entry_ex *);
58       } hdb_entry_ex;
59
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. 
65
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,
71                                            const krb5_principal,
72                                            struct hdb_entry_ex *,
73                                            struct hdb_entry_ex *,
74                                            krb5_pac *);
75        typedef krb5_error_code
76             (*krb5plugin_windc_client_access)(void *, 
77                                               krb5_context, 
78                                               struct hdb_entry_ex *, 
79                                               KDC_REQ *, krb5_data *);
80                                               
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 
85     is not enough)
86
87        typedef struct krb5plugin_windc_ftable {
88             int                 minor_version;
89             krb5_error_code     (*init)(krb5_context, void **);
90             void                (*fini)(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).
110
111  
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.
116
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).
120
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 
124 bind etc)
125
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. 
130
131 GSSAPI layer requirements
132 -------------------------
133
134 Welcome to the wonderful world of canonicalisation
135
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.
138
139 Heimdal has the same problem, and this too applies to the krb5 layer, not
140 just gssapi.
141
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.
148
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.
152
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 separate 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 
164 require.  
165
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.
171
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.
184
185 see heimdal/lib/gssapi/krb5/accept_sec_context.c, lines 390-450 or so.
186
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
191
192 So MIT's krb5lib needs to also support old clients!
193
194 Principal Names, long and short names
195 -------------------------------------
196
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.
212
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. 
217
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.
224
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--->|
232
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.
235
236 HOST/ Aliases
237 -------------
238
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.
243
244 Samba4 currently has set:
245 sPNMappings: host=ldap,dns,cifs,http  (but dns's presence is a bug, somehow)
246
247 AD actually has ~50 entries:
248
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
255  
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.
258
259 For example, this is how HTTP/, and CIFS/ can use HOST/ without
260 any explicit entry in the servicePrincipalName attribute
261
262
263 For example, the application-server might have (on its AD record):
264 servicePrincipalName: HOST/my.computer@MY.REALM
265
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
270
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).
278    
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
282
283 We implement this in hdb-ldb.
284
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).
295
296 Returned Salt for PreAuthentication
297 -----------------------------------
298
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).
303
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.
309
310
311 From: Luke Howard <lukeh@padl.com>
312 Organization: PADL Software Pty Ltd
313 To: lukeh@padl.com
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
317 -------
318
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
322 name is different.
323
324 Here is what I've been able to deduce from creating a bunch of
325 different accounts:  
326 [SAM name in this mail means the AD attribute samAccountName .
327  E.g., jbob for a user and jbcomputer$ for a computer.]
328
329 [UPN is the AD userPrincipalName attribute.  For example, jbob@mydomain.com]
330
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
336
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
340 effect.
341
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.
348
349 For more information on how UPNs relate to the Kerberos protocol,
350 see:
351
352 http://www.ietf.org/proceedings/01dec/I-D/draft-ietf-krb-wg-kerberos-referrals-02.txt
353
354 -- Luke
355
356
357
358 Heimdal oddities
359 ----------------
360
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.
364
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.
373
374 Other odd things:
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 
380    this.
381
382 State Machine safety when using Kerberos and GSSAPI libraries
383 -------------------------------------------------------------
384
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
388 libraries. 
389
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).
394
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
401 encrypted session).
402
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.
406
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).
411
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.
419
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.
425
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.] 
430
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. 
436
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
441 excepted. .
442
443
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. 
448
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.
455
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.
460
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.
466
467
468
469 GSSAPI and Kerberos extensions
470 ------------------------------
471
472 This is a general list of the other extensions we have made to / need from
473 the kerberos libraries
474
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).
478
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.
485
486  - gsskrb5_acquire_creds() (takes keytab and/or ccache as input
487    parameters, see keytab and state machine discussion in prev section)
488
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
492    the PAC validation).
493  - gsskrb5_extract_authtime_from_sec_context (get authtime from
494    kerberos ticket)
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()
499
500 Samba still needs this one:
501  - gsskrb5_wrap_size (find out how big the wrapped packet will be,
502    given input length).
503
504 Keytab requirements
505 -------------------
506
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:
510
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.
528
529 Traditional 'MIT' behaviour is to use a keytab, containing salted key
530 data, extracted from the KDC.  (In this model, there is no 'service
531 password', instead the keys are often simply application of random
532 bytes).  Heimdal also implements this behaviour.
533
534 The windows model 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).
543
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.
549
550 In dealing with this model, we use both the traditional file
551 keytab and in-MEMORY keytabs.  
552
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:
557
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)
563
564 as well as all case variations on the above.  
565
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.
575
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 specify the principal name to
580 GSSAPI, which avoids the need to store duplicate principals.
581
582 We use a 'private' keytab in our private dir, referenced from the
583 secrets.ldb by default.
584
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.
589
590 (an attempt to list some of the Heimdal-specific functions I know we use)
591
592 krb5_free_keyblock_contents()
593
594 also a raft of prinicpal manipulation functions:
595
596 Prncipal Manipulation
597 ---------------------
598
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.
608
609 Authz data extraction
610 ---------------------
611
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.
614
615 KDC/hdb Extensions
616 --------------
617
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.
623
624 We currently define 3 classes:
625  - client (kinit)
626  - server (tgt)
627  - krbtgt (kinit, tgt) the kdc's own ldap record
628
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.
631
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.
637
638  A new windc plugin function should be added to increment the bad password counter
639  on failure.
640
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.)
643 ------
644
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
648 KDC.  
649
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.
654
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)
657 --------------------
658
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.
663
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
666 layer for this.
667
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.
674
675 Kerberos logging support  (this will require porting attention)
676 ------------------------
677
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.
682
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)
689
690
691 Short name rules
692 ----------------
693
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.)
698
699 PAC Correctness
700 ---------------
701
702 We now put the PAC into the TGT, not just the service ticket.  
703
704 Forwarded tickets
705 -----------------
706
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.
710
711
712 Kerberos TODO
713 =============
714
715 (Feel free to contribute to any of these tasks, or ask
716 abartlet@samba.org about them).
717
718 Lockout Control  (still undone in samba4 on heimdal)
719 --------------
720
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.
726
727 Gssmonger
728 ---------
729
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.
734
735 Kpasswd server (kpasswd server is now finished, but not testsuite)
736 --------------
737
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.
742
743 Currently it only works for Heimdal, not MIT clients.  This may be due
744 to call ordering constraints.
745
746
747 Correct TCP support
748 -------------------
749
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.
754
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
758 of Samba4 to MIT.
759 AB says Likewise software will likely give us their freeware NTLM/MIT-krb
760 implementation.