43881a20d33d69aa1ea6166b8e8a86c35a7c3fdf
[samba.git] / source / auth / kerberos / kerberos-notes.txt
1 AllowedWorkstationNames and Krb5
2 --------------------------------
3
4 Microsoft uses the clientAddresses *multiple value* field in the krb5
5 protocol (particularly the AS_REQ) to communicate it's netbios name.
6 This is (my guess) to permit the userWorkstations field to work.
7
8 The KDC I imagine checks the netbios address against this value, in
9 the same way that the Samba server does this.
10
11 The checking of this implies a little of the next question:
12
13 Is a DAL the layer we need?
14 ---------------------------
15
16 Looking at what we need to pass around, I start to seriously wonder if
17 the DAL is even the right layer - we seem to want to create an account
18 authorization abstraction layer - is this account permitted to login to
19 this computer, at this time?
20
21 This information in AD is much richer than the Heimdal HDB, and it
22 seems to make sense to do AD-specific access control checks in an
23 AD-specific layer, not in the back-end agnostic server.
24
25 Because the DAL only reads in the principalName as the key, it has
26 trouble performing access control decisions on things other than the
27 name.
28
29 I'll be very interested if the DAL really works for eDirectory too.
30 Perhaps all we need to do is add in the same kludges as we have in
31 Samba 3.0 for eDirectory.  Hmm...
32
33 That said, the current layer provides us with a very good start, and
34 any redefinition would occour from that basis.
35
36
37 GSSAPI layer requirements
38 -------------------------
39
40 Welcome to the wonderful world of canonicalisation
41
42 The MIT GSSAPI libs do not support kinit returning a different
43 realm to what the client asked for, even just in case differences.
44
45 Heimdal has the same problem, and this applies to the krb5 layer, not
46 just gssapi.
47
48 We need to test if the canonicalisation is controlled by the KDCOption
49 flags, windows always sends the Canonicalize flags
50
51 Old Clients (samba3 and HPUX clients) uses 'selfmade' gssapi/krb5
52 for using it in the CIFS session setup. Because they use krb5_mk_req()
53 they get a chksum field depending on the encryption type, but that's wrong
54 for GSSAPI (see rfc 1964 section 1.1.1). The Cheksum type 8003
55 should be used in the Authenticator of the AP-REQ! That allows the channel bindings,
56 the GCC_C_* req_flags and optional delegation tickets to be passed from the client to the server.
57 Hower windows doesn't seems to care about if the checksum is of the wrong type,
58 for CIFS SessionSetups, it seems that the req_flags are just set to 0.
59 So this can't work for LDAP connections with sign or seal, or for any DCERPC
60 connection.
61
62 So we need to also support old clients!
63
64 Principal Names, long and short names
65 -------------------------------------
66
67 As far as servicePrincipalNames are concerned, these are not
68 canonicalised, except as regards the realm in the reply.  That is, the
69 client gets back the principal it asked for, with the realm portion
70 'fixed' to uppercase, long form.  
71
72 The short name of the realm seems to be accepted for at least AS_REQ
73 operations, but because the server performs canonicalisation, this
74 causes pain for current client libraries. 
75
76 The canonicalisation of names matters not only for the KDC, but also
77 for code that has to deal with keytabs.
78
79 We also need to handle type 10 names (NT-ENTERPRISE), which are a full
80 principal name in the principal field, unrelated to the realm.
81
82 HOST/ Aliases
83 -------------
84
85 There is another post somewhere (ref lost for the moment) that details
86 where in active directory the list of stored aliases for HOST/ is.
87 This should be read, parsed and used to allow any of these requests to
88 use the HOST/ key.
89
90 For example, this is how HTTP/, DNS/ and CIFS/ can use HOST/ without
91 any explicit entry.
92
93
94 Jean-Baptiste.Marchand@hsc.fr reminds me:
95
96 > This is the SPNMappings attribute in Active Directory:
97
98 > http://msdn.microsoft.com/library/en-us/adschema/adschema/a_spnmappings.asp
99
100 We implement this in hdb-ldb.
101
102 Implicit names for Win2000 Accounts
103 -----------------------------------
104
105 Despite not having a DNS name, nor a servicePrincipalName on accounts
106 created by computers running win2000, it appears we are expected to
107 have an implicit mapping from host/computer.full.name and
108 host/computer to it's entry.
109
110 Returned Salt for PreAuthentication
111 -----------------------------------
112
113 When the server replies for pre-authentication, it returns the Salt,
114 which may be in the form of a principalName that is in no way
115 connected with the current names.  (ie, even if the userPrincipalName
116 and samAccountName are renamed, the old salt is returned).
117
118 This is probably the kerberos standard salt, kept in the 'Key'.  The
119 standard generation rules are found in a Mail from Luke Howard dated
120 10 Nov 2004:
121
122
123 From: Luke Howard <lukeh@padl.com>
124 Message-Id: <200411100231.iAA2VLUW006101@au.padl.com>
125 MIME-Version: 1.0
126 Content-Type: text/plain; charset=US-ASCII
127 Organization: PADL Software Pty Ltd
128 To: lukeh@padl.com
129 Date: Wed, 10 Nov 2004 13:31:21 +1100
130 Versions: dmail (bsd44) 2.6d/makemail 2.10
131 Cc: huaraz@moeller.plus.com, samba-technical@lists.samba.org
132 Subject: Re: Samba-3.0.7-1.3E Active Directory Issues
133 X-BeenThere: samba-technical@lists.samba.org
134 X-Mailman-Version: 2.1.4
135 Precedence: list
136 Reply-To: lukeh@padl.com
137
138 Did some more testing, it appears the behaviour has another
139 explanation. It appears that the standard Kerberos password salt
140 algorithm is applied in Windows 2003, just that the source principal
141 name is different.
142
143 Here is what I've been able to deduce from creating a bunch of
144 different accounts:
145
146 Type of account         Principal for Salting
147 ========================================================================
148 Computer Account                host/<SAM-Name-Without-$>.realm@REALM
149 User Account Without UPN        <SAM-Name>@REALM
150 User Account With UPN           <LHS-Of-UPN>@REALM
151
152 Note that if the computer account's SAM account name does not include
153 the trailing '$', then the entire SAM account name is used as input to
154 the salting principal. Setting a UPN for a computer account has no
155 effect.
156
157 It seems to me odd that the RHS of the UPN is not used in the salting
158 principal. For example, a user with UPN foo@mydomain.com in the realm
159 MYREALM.COM would have a salt of MYREALM.COMfoo. Perhaps this is to
160 allow a user's UPN suffix to be changed without changing the salt. And
161 perhaps using the UPN for salting signifies a move away SAM names and
162 their associated constraints.
163
164 For more information on how UPNs relate to the Kerberos protocol,
165 see:
166
167 http://www.ietf.org/proceedings/01dec/I-D/draft-ietf-krb-wg-kerberos-referrals-02.txt
168
169 -- Luke
170
171 --
172
173
174
175
176 Heimdal oddities
177 ----------------
178
179 Heimdal is built such that it should be able to serve multiple realms
180 at the same time.  This isn't relevant for Samba's use, but it shows
181 up in a lot of generalisations throughout the code.
182
183 Other odd things:
184  - Support for multiple passwords on a client account:  we seem to
185    call hdb_next_enctype2key() in the pre-authentication routines to
186    allow multiple passwords per account in krb5.  (I think this was
187    intened to allow multiple salts)
188
189 State Machine safety
190 --------------------
191
192 Samba is a giant state machine, and as such have very different
193 requirements to those traditionally expressed for kerberos and GSSAPI
194 libraries. 
195
196 Samba requires all of the libraries it uses to be state machine safe in
197 their use of internal data.  This does not mean thread safe, and an
198 application could be thread safe, but not state machine safe (if it
199 instead used thread-local variables).
200
201 So, what does it mean for a library to be state machine safe?  This is
202 mostly a question of context, and how the library manages whatever
203 internal state machines it has.  If the library uses a context
204 variable, passed in by the caller, which contains all the information
205 about the current state of the library, then it is safe.  An example
206 of this state is the sequence number and session keys for an ongoing
207 encrypted session).
208
209 The other issue affecting state machines is 'blocking' (waiting for a
210 read on a network socket).  
211
212 Heimdal has this 'state machine safety' in parts, and we have modified
213 the lorikeet branch to improve this behviour, when using a new,
214 non-standard API.  
215
216 Heimdal uses a per-context variable for the 'krb5_auth_context', which
217 controls the ongoing encrypted connection, but does use global
218 variables for the ubiquitous krb5_context parameter.  
219
220 The modification that has added most to 'state machine safety' of
221 GSSAPI is the addition of the gsskrb5_acquire_creds function.  This
222 allows the caller to specify a keytab and ccache, for use by the
223 GSSAPI code.  Therefore there is no need to use global variables to
224 communicate this information. 
225
226 At a more theoritical level (simply counting static and global
227 variables) Heimdal is not state machine safe for the GSSAPI layer.
228 The Krb5 layer alone is much closer, as far as I can tell, blocking
229 excepted. .
230
231 To deal with blocking, we could have a fork()ed child per context,
232 using the 'GSSAPI export context' function to transfer
233 the GSSAPI state back into the main code for the wrap()/unwrap() part
234 of the operation.  This will still hit issues of static storage (one
235 gss_krb5_context per process, and multiple GSSAPI encrypted sessions
236 at a time) but these may not matter in practice.
237
238 In the short-term, we deal with blocking by taking over the network
239 send() and recv() functions, therefore making them 'semi-async'.  This
240 doens't apply to DNS yet.
241
242 GSSAPI and Kerberos extensions
243 ------------------------------
244
245 This is a general list of the other extensions we have made to / need from
246 the kerberos libraries
247
248  - DCE_STYLE
249
250  - gsskrb5_get_initiator_subkey() (return the exact key that Samba3
251    has always asked for.  gsskrb5_get_subkey() might do what we need
252    anyway)
253
254  - gsskrb5_acquire_creds() (takes keytab and/or ccache as input
255    parameters, see keytab and state machine discussion)
256
257  - gss_krb5_copy_service_keyblock() (get the key used to actually
258    encrypt the ticket to the server, because the same key is used for
259    the PAC validation).
260  - gsskrb5_extract_authtime_from_sec_context (get authtime from
261    kerberos ticket)
262  - gsskrb5_extract_authz_data_from_sec_context (get authdata from
263    ticket, ie the PAC.  Must unwrap the data if in an AD-IFRELEVENT)
264  - gsskrb5_wrap_size (find out how big the wrapped packet will be,
265    given input length).
266
267 Keytab requirements
268 -------------------
269
270 Because windows machine account handling is very different to the
271 tranditional 'MIT' keytab operation.  This starts when we look at the
272 basis of the secrets handling:
273
274 Traditional 'MIT' behaviour is to use a keytab, continaing salted key
275 data, extracted from the KDC.  (In this modal, there is no 'service
276 password', instead the keys are often simply application of random
277 bytes).  Heimdal also implements this behaviour.
278
279 The windows modal is very different - instead of sharing a keytab with
280 each member server, a password is stored for the whole machine.  The
281 password is set with non-kerberos mechanisms (particularly SAMR, a
282 DCE-RPC service) and when interacting on a kerberos basis, the
283 password is salted by the client.  (That is, no salt infromation
284 appears to be convayed from the KDC to the member).
285
286 In dealing with this modal, we leverage both the traditional file
287 keytab and in-MEMORY keytabs.  
288
289 When dealing with a windows KDC, the behaviour regarding case
290 sensitivity and canonacolisation must be accomidated.  This means that
291 an incoming request to a member server may have a wide variety of
292 service principal names.  These include:
293
294 machine$@REALM (samba clients)
295 HOST/foo.bar@realm (win2k clients)
296 HOST/foo@realm (win2k clients, using netbios)
297 cifs/foo.bar@realm (winxp clients)
298 cifs/foo@realm (winxp clients, using netbios)
299
300 as well as all case variations on the above.  
301
302 Because that all got 'too hard' to put into a keytab in the
303 traditional way (with the client to specify the name), we either
304 pre-compute the keys into a traditional keytab or make an in-MEMORY
305 keytab at run time.  In both cases we specifiy the principal name to
306 GSSAPI, which avoids the need to store duplicate principals.
307
308 We use a 'private' keytab in our private dir, referenced from the
309 secrets.ldb by default.
310
311 Extra Heimdal functions used
312 ----------------------------
313 (an attempt to list some of the Heimdal-specific functions I know we use)
314
315 krb5_free_keyblock_contents()
316
317 also a raft of prinicpal manipulation functions:
318
319 Prncipal Manipulation
320 ---------------------
321
322 Samba makes extensive use of the principal manipulation functions in
323 Heimdal, including the known structure behind krb_principal and
324 krb5_realm (a char *).
325
326 Authz data extraction
327 ---------------------
328
329 We use krb5_ticket_get_authorization_data_type(), and expect it to
330 return the correct authz data, even if wrapped in an AD-IFRELEVENT container.
331
332
333 KDC/hdb Extensions
334 --------------
335
336 We have modified Heimdal's 'hdb' interface to specify the 'type' of
337 Principal being requested.  This allows us to correctly behave with
338 the different 'classes' of Principal name. 
339
340 We currently define 2 classes:
341  - client (kinit)
342  - server (tgt)
343
344 I also now specify the kerberos principal as an explict parameter, not
345 an in/out value on the entry itself.
346
347 Inside hdb-ldb, we add krbtgt as a special class of principal, because
348 of particular special-case backend requirements.
349
350 Callbacks:
351  In addition, I have added a new interface hdb_fetch_ex(), which
352  returns a structure including callbacks, which provide the hook for
353  the PAC, as well as a callback into the main access control routines.
354
355  A new callback should be added to increment the bad password counter
356  on failure.
357
358  Another possability for a callback is to obtain the keys.  This would
359  allow the plaintext password to only be hashed into the encryption
360  types we need.  This idea from the eDirectory/MIT DAL work.
361
362  This probably should be combined with storing the hashed passwords in
363  the supplementalCredentials attribute. If combined with a kvno
364  parameter, this could also allow changing of the krbtgt password
365  (valuable for security).
366
367 libkdc
368 ------
369
370 Samba4 needs to be built as a single binary (design requirement), and
371 this should include the KDC.  Samba also (and perhaps more
372 importantly) needs to control the configuration environment of the
373 KDC.  
374
375 The interface we have defined for libkdc allow for packet injection
376 into the post-socket layer, with a defined krb5_context and
377 kdb5_kdc_configuration structure.  These effectively redirect the
378 kerberos warnings, logging and database calls as we require.
379
380 Using our socket lib
381 --------------------
382
383 An important detail in the use of libkdc is that we use our own socket
384 lib.  This allows the KDC code to be as portable as the rest of samba
385 (this cuts both ways), but far more importantly it ensures a
386 consistancy in the handling of requests, binding to sockets etc.
387
388 To handle TCP, we use of our socket layer in much the same way as
389 we deal with TCP for CIFS.  Tridge created a generic packet handling
390 layer for this.
391
392 For the client, we likewise must take over the socket functions, so
393 that our single thread smbd will not lock up talking to itself.  (We
394 allow processing while waiting for packets in our socket routines).
395
396 Kerberos logging support
397 ------------------------
398
399 Samba now (optionally in the main code, required for the KDC) uses the
400 krb5_log_facility from Heimdal.  This allows us to redirect the
401 warnings and status from the KDC (and client/server kerberos code) to
402 Samba's DEBUG() system.
403
404 Similarly important is the Heimdal-specific krb5_get_error_string()
405 function, which does a lot to reduce the 'administrator pain' level,
406 by providing specific, english text-string error messages instead of
407 just error code translations.
408
409
410 Short name rules
411 ----------------
412
413 Samba is highly likely to be misconfigured, in many weird and
414 interesting ways.  As such, we have a patch for Heimdal that avoids
415 DNS lookups on names without a . in them.  This should avoid some
416 delay and root server load.
417
418 PAC Correctness
419 ---------------
420
421 We now put the PAC into the TGT, not just the service ticket.  
422
423 Forwarded tickets
424 -----------------
425
426 We extract forwarded tickets from the GSSAPI layer, and put
427 them into the credentials.  We can then use them for proxy work.
428
429
430 Kerberos TODO
431 =============
432
433 (Feel free to contribute to any of these tasks, or ask
434 abartlet@samba.org about them).
435
436 Lockout Control
437 --------------
438
439 We need to get (either if PADL publishes their patch, or write our
440 own) access control hooks in the Heimdal KDC.  We need to lockout
441 accounts, and perform other controls.
442
443 Gssmonger
444 ---------
445
446 Microsoft has released a testsuite called gssmonger, which tests
447 interop.  We should compile it against lorikeet-heimdal, MIT and see
448 if we can build a 'Samba4' server for it.
449
450 Kpasswd server
451 --------------
452
453 I have a partial kpasswd server which needs finishing, and a we need a
454 client testsuite written, either via the krb5 API or directly against
455 GENSEC and the ASN.1 routines.
456
457 Currently it only works for Heimdal, not MIT clients.  This may be due
458 to call ordering constraints.
459
460
461 Correct TCP support
462 -------------------
463
464 Our current TCP support does not send back 'too large' error messages
465 if the high bit is set.  This is needed for a proposed extension
466 mechanism, but is likewise unsupported in both current Heimdal and MIT.