Merge from vendor branch FILE:
[dragonfly.git] / crypto / heimdal-0.6.3 / doc / win2k.texi
1 @c $Id: win2k.texi,v 1.15 2001/07/19 16:44:41 assar Exp $
2
3 @node Windows 2000 compatability, Programming with Kerberos, Kerberos 4 issues, Top
4 @comment  node-name,  next,  previous,  up
5 @chapter Windows 2000 compatability
6
7 Windows 2000 (formerly known as Windows NT 5) from Microsoft implements
8 Kerberos 5.  Their implementation, however, has some quirks,
9 peculiarities, and bugs.  This chapter is a short summary of the things
10 that we have found out while trying to test Heimdal against Windows
11 2000.  Another big problem with the Kerberos implementation in Windows
12 2000 is that the available documentation is more focused on getting
13 things to work rather than how they work and not that useful in figuring
14 out how things really work.
15
16 This information should apply to Heimdal @value{VERSION} and Windows
17 2000 Professional.  It's of course subject all the time and mostly consists of
18 our not so inspired guesses.  Hopefully it's still somewhat useful.
19
20 @menu
21 * Configuring Windows 2000 to use a Heimdal KDC::  
22 * Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC::  
23 * Create account mappings::     
24 * Encryption types::            
25 * Authorization data::          
26 * Quirks of Windows 2000 KDC::  
27 * Useful links when reading about the Windows 2000::  
28 @end menu
29
30 @node Configuring Windows 2000 to use a Heimdal KDC, Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Windows 2000 compatability, Windows 2000 compatability
31 @comment node-name, next, precious, up
32 @section Configuring Windows 2000 to use a Heimdal KDC
33
34 You need the command line program called @code{ksetup.exe} which is available
35 in the file @code{SUPPORT/TOOLS/SUPPORT.CAB} on the Windows 2000 Professional
36 CD-ROM. This program is used to configure the Kerberos settings on a
37 Workstation.
38
39 @code{Ksetup} store the domain information under the registry key:
40 @code{HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\LSA\Kerberos\Domains}.
41
42 Use the kadmin program in Heimdal to create a host principal in the
43 Kerberos realm.
44
45 @example
46 unix% kadmin
47 kadmin> ank -pw password host/datan.my.domain
48 @end example
49
50 You must configure the Workstation as a member of a workgroup, as opposed
51 to a member in an NT domain, and specify the KDC server of the realm
52 as follows:
53 @example
54 C:> ksetup /setdomain MY.REALM
55 C:> ksetup /addkdc MY.REALM kdc.my.domain
56 @end example
57
58 Set the machine password, i.e. create the local keytab:
59 @example
60 C:> ksetup /setmachpassword password
61 @end example
62
63 The workstation must now be rebooted.
64
65 A mapping between local NT users and Kerberos principals must be specified,
66 you have two choices:
67
68 @example
69 C:> ksetup /mapuser user@@MY.REALM nt_user
70 @end example
71
72 This will map a user to a specific principal, this allows you to have
73 other usernames in the realm than in your NT user database. (Don't ask
74 me why on earth you would want that...)
75
76 You can also say:
77 @example
78 C:> ksetup /mapuser * *
79 @end example
80 The Windows machine will now map any user to the corresponding principal,
81 for example @samp{nisse} to the principal @samp{nisse@@MY.REALM}.
82 (This is most likely what you want.)
83
84 @node Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Create account mappings, Configuring Windows 2000 to use a Heimdal KDC, Windows 2000 compatability
85 @comment node-name, next, precious, up
86 @section Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC
87
88 See also the Step-by-Step guide from Microsoft, referenced below.
89
90 Install Windows 2000, and create a new controller (Active Directory
91 Server) for the domain.
92
93 By default the trust will be non-transitive. This means that only users
94 directly from the trusted domain may authenticate. This can be changed
95 to transitive by using the @code{netdom.exe} tool.
96
97 You need to tell Windows 2000 on what hosts to find the KDCs for the
98 non-Windows realm with @code{ksetup}, see @xref{Configuring Windows 2000
99 to use a Heimdal KDC}.
100
101 This need to be done on all computers that want enable cross-realm
102 login with @code{Mapped Names}.
103
104 Then you need to add the inter-realm keys on the Windows kdc. Start the
105 Domain Tree Management tool. (Found in Programs, Administrative tools,
106 Active Directory Domains and Trusts).
107
108 Right click on Properties of your domain, select the Trust tab.  Press
109 Add on the appropriate trust windows and enter domain name and
110 password. When prompted if this is a non-Windows Kerberos realm, press
111 OK.
112
113 Do not forget to add trusts in both directions.
114
115 You also need to add the inter-realm keys to the Heimdal KDC. There are
116 some tweaks that you need to do to @file{krb5.conf} beforehand.
117
118 @example
119 [libdefaults]
120         default_etypes = des-cbc-crc
121         default_etypes_des = des-cbc-crc
122 @end example
123
124 since otherwise checksum types that are not understood by Windows 2000
125 will be generated (@xref{Quirks of Windows 2000 KDC}.).
126
127 Another issue is salting.  Since Windows 2000 does not seem to
128 understand Kerberos 4 salted hashes you might need to turn off anything
129 similar to the following if you have it, at least while adding the
130 principals that are going to share keys with Windows 2000.
131
132 @example
133         [kadmin]default_keys = v5 v4
134 @end example
135
136 You must also set:
137
138 Once that is also done, you can add the required inter-realm keys:
139
140 @example
141 kadmin add krbtgt/NT.REALM.EXAMPLE.COM@@EXAMPLE.COM
142 kadmin add krbtgt/REALM.EXAMPLE.COM@@NT.EXAMPLE.COM
143 @end example
144
145 Use the same passwords for both keys.
146
147 Do not forget to reboot before trying the new realm-trust (after running
148 @code{ksetup}). It looks like it might work, but packets are never sent to the
149 non-Windows KDC.
150
151 @node Create account mappings, Encryption types, Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Windows 2000 compatability
152 @comment node-name, next, precious, up
153 @section Create account mappings
154
155 Start the @code{Active Directory Users and Computers} tool. Select the
156 View menu, that is in the left corner just below the real menu (or press
157 Alt-V), and select Advanced Features. Right click on the user that you
158 are going to do a name mapping for and choose Name mapping.
159
160 Click on the Kerberos Names tab and add a new principal from the
161 non-Windows domain.
162
163 @node Encryption types, Authorization data, Create account mappings, Windows 2000 compatability
164 @comment  node-name,  next,  previous,  up
165 @section Encryption types
166
167 Windows 2000 supports both the standard DES encryptions (des-cbc-crc and
168 des-cbc-md5) and its own proprietary encryption that is based on MD4 and
169 rc4 that is documented in and is supposed to be described in
170 @file{draft-brezak-win2k-krb-rc4-hmac-03.txt}.  New users will get both
171 MD4 and DES keys.  Users that are converted from a NT4 database, will
172 only have MD4 passwords and will need a password change to get a DES
173 key.
174
175 Heimdal implements both of these encryption types, but since DES is the
176 standard and the hmac-code is somewhat newer, it is likely to work better.
177
178 @node Authorization data, Quirks of Windows 2000 KDC, Encryption types, Windows 2000 compatability
179 @comment  node-name,  next,  previous,  up
180 @section Authorization data
181
182 The Windows 2000 KDC also adds extra authorization data in tickets.
183 It is at this point unclear what triggers it to do this.  The format of
184 this data is only available under a ``secret'' license from Microsoft,
185 which prohibits you implementing it.
186
187 A simple way of getting hold of the data to be able to understand it
188 better is described here.
189
190 @enumerate
191 @item Find the client example on using the SSPI in the SDK documentation.
192 @item Change ``AuthSamp'' in the source code to lowercase.
193 @item Build the program.
194 @item Add the ``authsamp'' principal with a known password to the
195 database.  Make sure it has a DES key.
196 @item Run @kbd{ktutil add} to add the key for that principal to a
197 keytab.
198 @item Run @kbd{appl/test/nt_gss_server -p 2000 -s authsamp
199 --dump-auth=file} where file is an appropriate file.
200 @item It should authenticate and dump for you the authorization data in
201 the file.
202 @item The tool @kbd{lib/asn1/asn1_print} is somewhat useful for
203 analyzing the data.
204 @end enumerate
205
206 @node Quirks of Windows 2000 KDC, Useful links when reading about the Windows 2000, Authorization data, Windows 2000 compatability
207 @comment  node-name,  next,  previous,  up
208 @section Quirks of Windows 2000 KDC
209
210 There are some issues with salts and Windows 2000.  Using an empty salt,
211 which is the only one that Kerberos 4 supported and is therefore known
212 as a Kerberos 4 compatible salt does not work, as far as we can tell
213 from out experiments and users reports.  Therefore, you have to make
214 sure you keep around keys with all the different types of salts that are
215 required.
216
217 Microsoft seems also to have forgotten to implement the checksum
218 algorithms @samp{rsa-md4-des} and @samp{rsa-md5-des}. This can make Name
219 mapping (@pxref{Create account mappings}) fail if a @code{des-cbc-md5} key
220 is used. To make the KDC return only @code{des-cbc-crc} you must delete
221 the @code{des-cbc-md5} key from the kdc using the @code{kadmin
222 del_enctype} command.
223
224 @example
225 kadmin del_enctype lha des-cbc-md5
226 @end example
227
228 You should also add the following entries to the @file{krb5.conf} file:
229
230 @example
231 [libdefaults]
232         default_etypes = des-cbc-crc
233         default_etypes_des = des-cbc-crc
234 @end example
235
236 These configuration options will make sure that no checksums of the
237 unsupported types are generated.
238
239 @node Useful links when reading about the Windows 2000,  , Quirks of Windows 2000 KDC, Windows 2000 compatability
240 @comment  node-name,  next,  previous,  up
241 @section Useful links when reading about the Windows 2000
242
243 See also our paper presented at the 2001 usenix Annual Technical
244 Conference, available in the proceedings or at
245 @url{http://www.usenix.org/publications/library/proceedings/usenix01/freenix01/westerlund.html}.
246
247 There are lots of text about Kerberos on Microsoft's web site, here is a
248 short list of the interesting documents that we have managed to find.
249
250 @itemize @bullet
251
252 @item Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability -
253 @url{http://www.microsoft.com/windows2000/library/planning/security/kerbsteps.asp}
254 Kerberos GSS-API (in Windows-ize SSPI), Windows as a client in a
255 non-Windows KDC realm, adding unix clients to a Windows 2000 KDC, and
256 adding cross-realm trust (@xref{Inter-Realm keys (trust) between Windows 2000
257 and a Heimdal KDC}.).
258
259 @item Windows 2000 Kerberos Authentication - 
260 @url{http://www.microsoft.com/TechNet/win2000/win2ksrv/technote/kerberos.asp}
261 White paper that describes how Kerberos is used in Windows 2000.
262
263 @item Overview of kerberos -
264 @url{http://support.microsoft.com/support/kb/articles/Q248/7/58.ASP}
265 Links to useful other links.
266
267 @item Klist for windows - 
268 @url{http://msdn.microsoft.com/library/periodic/period00/security0500.htm}
269 Describes where to get a klist for Windows 2000.
270
271 @item Event logging for kerberos -
272 @url{http://support.microsoft.com/support/kb/articles/Q262/1/77.ASP}.
273 Basicly it say that you can add a registry key
274 @code{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters\LogLevel}
275 with value DWORD equal to 1, and then you'll get logging in the Event
276 Logger.
277
278 @item Access to the active directory through LDAP
279 @url{http://msdn.microsoft.com/library/techart/kerberossamp.htm}
280
281 @end itemize
282
283 Other useful programs include these:
284
285 @itemize @bullet
286 @item pwdump2
287 @url{http://www.webspan.net/~tas/pwdump2/}
288 @end itemize