04822eed3291fcf7fc2d38372412c1cc0c527a0f
[samba.git] / docs / textdocs / ENCRYPTION.txt
1 Contributor:    Jeremy Allison <samba-bugs@samba.anu.edu.au>
2 Updated:        June 27, 1997
3 Note:           Please refer to WinNT.txt also
4
5 Subject:        LanManager / Samba Password Encryption.
6 ============================================================================
7
8 With the development of LanManager and Windows NT compatible password 
9 encryption for Samba, it is now able to validate user connections in 
10 exactly the same way as a LanManager or Windows NT server.
11
12 This document describes how the SMB password encryption algorithm
13 works and what issues there are in choosing whether you want to use
14 it. You should read it carefully, especially the part about security
15 and the "PROS and CONS" section.
16
17 How does it work ?
18 ------------------
19
20         LanManager encryption is somewhat similar to UNIX password
21 encryption. The server uses a file containing a hashed value of a
22 users password.  This is created by taking the users paintext
23 password, capitalising it, and either truncating to 14 bytes (or
24 padding to 14 bytes with null bytes). This 14 byte value is used as
25 two 56 bit DES keys to encrypt a 'magic' eight byte value, forming a
26 16 byte value which is stored by the server and client. Let this value
27 be known as the *hashed password*.
28
29         Windows NT encryption is a higher quality mechanism, consisting
30 of doing an MD4 hash on a Unicode version of the users password. This
31 also produces a 16 byte hash value that is non-reversible.
32
33 When a client (LanManager, Windows for WorkGroups, Windows 95 or
34 Windows NT) wishes to mount a Samba drive (or use a Samba resource) it
35 first requests a connection and negotiates the protocol that the client
36 and server will use. In the reply to this request the Samba server
37 generates and appends an 8 byte, random value - this is stored in the
38 Samba server after the reply is sent and is known as the *challenge*.
39
40 The challenge is different for every client connection.
41
42 The client then uses the hashed password (16 byte values described
43 above), appended with 5 null bytes, as three 56 bit DES keys, each of
44 which is used to encrypt the challenge 8 byte value, forming a 24 byte
45 value known as the *response*.
46
47 In the SMB call SMBsessionsetupX (when user level security is
48 selected) or the call SMBtconX (when share level security is selected)
49 the 24 byte response is returned by the client to the Samba server.
50 For Windows NT protocol levels the above calculation is done on
51 both hashes of the users password and both responses are returned
52 in the SMB call, giving two 24 byte values.
53
54 The Samba server then reproduces the above calculation, using it's own
55 stored value of the 16 byte hashed password (read from the smbpasswd
56 file - described later) and the challenge value that it kept from the
57 negotiate protocol reply. It then checks to see if the 24 byte value it
58 calculates matches the 24 byte value returned to it from the client.
59
60 If these values match exactly, then the client knew the correct
61 password (or the 16 byte hashed value - see security note below) and
62 is this allowed access. If not then the client did not know the
63 correct password and is denied access.
64
65 Note that the Samba server never knows or stores the cleartext of the
66 users password - just the 16 byte hashed values derived from it. Also
67 note that the cleartext password or 16 byte hashed values are never
68 transmitted over the network - thus increasing security.
69
70 IMPORTANT NOTE ABOUT SECURITY
71 -----------------------------
72
73 The unix and SMB password encryption techniques seem similar on the
74 surface. This similarity is, however, only skin deep. The unix scheme
75 typically sends clear text passwords over the nextwork when logging
76 in. This is bad. The SMB encryption scheme never sends the cleartext
77 password over the network but it does store the 16 byte hashed values
78 on disk. This is also bad. Why? Because the 16 byte hashed values are a
79 "password equivalent". You cannot derive the users password from them,
80 but they could potentially be used in a modified client to gain access
81 to a server. This would require considerable technical knowledge on
82 behalf of the attacker but is perfectly possible. You should thus
83 treat the smbpasswd file as though it contained the cleartext
84 passwords of all your users. Its contents must be kept secret, and the
85 file should be protected accordingly.
86
87 Ideally we would like a password scheme which neither requires plain
88 text passwords on the net or on disk. Unfortunately this is not
89 available as Samba is stuck with being compatible with other SMB
90 systems (WinNT, WfWg, Win95 etc). 
91
92
93 PROS AND CONS
94 -------------
95
96 There are advantages and disadvantages to both schemes. 
97
98 Advantages of SMB Encryption:
99 -----------------------------
100
101 - plain text passwords are not passed across the network. Someone using
102 a network sniffer cannot just record passwords going to the SMB server.
103
104 - WinNT doesn't like talking to a server that isn't using SMB
105 encrypted passwords. It will refuse to browse the server if the server
106 is also in user level security mode. It will insist on promting the
107 user for the password on each connection, which is very annoying. The
108 only things you can do to stop this is to use SMB encryption.
109
110 Advantages of non-encrypted passwords:
111 --------------------------------------
112
113 - plain text passwords are not kept on disk. 
114
115 - uses same password file as other unix services such as login and
116 ftp
117
118 - you are probably already using other services (such as telnet and
119 ftp) which send plain text passwords over the net, so not sending them
120 for SMB isn't such a big deal.
121
122 Note that Windows NT 4.0 Service pack 3 changed the default for
123 permissible authentication so that plaintext passwords are *never*
124 sent over the wire. The solution to this is either to switch to
125 encrypted passwords with Samba or edit the Windows NT registry to
126 re-enable plaintext passwords. See the document WinNT.txt for
127 details on how to do this.
128
129 The smbpasswd file.
130 -------------------
131
132         In order for Samba to participate in the above protocol it must
133 be able to look up the 16 byte hashed values given a user name.
134 Unfortunately, as the UNIX password value is also a one way hash
135 function (ie. it is impossible to retrieve the cleartext of the users
136 password given the UNIX hash of it) then a separate password file
137 containing this 16 byte value must be kept. To minimise problems with
138 these two password files, getting out of sync, the UNIX /etc/passwd and
139 the smbpasswd file, a utility, mksmbpasswd.sh, is provided to generate
140 a smbpasswd file from a UNIX /etc/passwd file.
141
142 To generate the smbpasswd file from your /etc/passwd file use the
143 following command :-
144
145 cat /etc/passwd | mksmbpasswd.sh >/usr/local/samba/private/smbpasswd
146
147 If you are running on a system that uses NIS, use
148
149 ypcat passwd | mksmbpasswd.sh >/usr/local/samba/private/smbpasswd
150
151 The mksmbpasswd.sh program is found in the Samba source directory. By
152 default, the smbpasswd file is stored in :-
153
154 /usr/local/samba/private/smbpasswd
155
156 The owner of the /usr/local/samba/private directory should be set to
157 root, and the permissions on it should be set to :-
158
159 r-x------
160
161 The command 
162
163 chmod 500 /usr/local/samba/private
164
165 will do the trick. Likewise, the smbpasswd file inside the private
166 directory should be owned by root and the permissions on is should be
167 set to
168
169 rw-------
170
171 by the command :-
172
173 chmod 600 smbpasswd.
174
175 The format of the smbpasswd file is
176
177 username:uid:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Long name:user home dir:user shell
178
179 Although only the username, uid, and XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
180 sections are significant and are looked at in the Samba code.
181
182 It is *VITALLY* important that there by 32 'X' characters between the
183 two ':' characters in the XXX sections - the smbpasswd and Samba code 
184 will fail to validate any entries that do not have 32 characters 
185 between ':' characters. The first XXX section is for the Lanman password
186 hash, the second is for the Windows NT version.
187
188 When the password file is created all users have password entries
189 consisting of 32 'X' characters. By default this disallows any access
190 as this user. When a user has a password set, the 'X' characters change
191 to 32 ascii hexadecimal digits (0-9, A-F). These are an ascii
192 representation of the 16 byte hashed value of a users password.
193
194 To set a user to have no password (not recommended), edit the file
195 using vi, and replace the first 11 characters with the asci text
196
197 NO PASSWORD
198
199 Eg. To clear the password for user bob, his smbpasswd file entry would
200 look like :
201
202 bob:100:NO PASSWORDXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Bob's full name:/bobhome:/bobshell
203
204 If you are allowing users to use the smbpasswd command to set their own
205 passwords, you may want to give users NO PASSWORD initially so they do
206 not have to enter a previous password when changing to their new
207 password (not recommended).
208
209 Note : This file should be protected very carefully. Anyone with
210 access to this file can (with enough knowledge of the protocols) gain
211 access to your SMB server. The file is thus more sensitive than a
212 normal unix /etc/passwd file.
213
214 The smbpasswd Command.
215 ----------------------
216
217         The smbpasswd command maintains the two 32 byte password fields in
218 the smbpasswd file. If you wish to make it similar to the unix passwd
219 or yppasswd programs, install it in /usr/local/samba/bin (or your main
220 Samba binary directory) and make it setuid root.
221
222 Note that if you do not do this then the root user will have to set all
223 users passwords.
224
225 To set up smbpasswd as setuid root, change to the Samba binary install
226 directory and then type (as root) :
227
228 chown root smbpasswd
229 chmod 4555 smbpasswd
230
231 If smbpasswd is installed as setuid root then you would use it as
232 follows.
233
234 smbpasswd
235 Old SMB password: <type old alue here - just hit return if there is NO PASSWORD>
236 New SMB Password: < type new value >
237 Repeat New SMB Password: < re-type new value >
238
239 If the old value does not match the current value stored for that user,
240 or the two new values do not match each other, then the password will
241 not be changed.
242
243 If invoked by an ordinary user it will only allow the user to change
244 his or her own Samba password.
245
246 If run by the root user smbpasswd may take an optional argument,
247 specifying the user name whose SMB password you wish to change.  Note
248 that when run as root smbpasswd does not prompt for or check the old
249 password value, thus allowing root to set passwords for users who have
250 forgotten their passwords.
251
252 smbpasswd is designed to work in the same way and be familiar to UNIX
253 users who use the passwd or yppasswd commands.
254
255 NOTE. As smbpasswd is designed to be installed as setuid root I would
256 appreciate it if everyone examined the source code to look for
257 potential security flaws. A setuid program, if not written properly can
258 be an open door to a system cracker. Please help make this program
259 secure by reporting all problems to me (the author, Jeremy Allison).
260
261 My email address is :-
262
263 jallison@whistle.com
264
265 Setting up Samba to support LanManager Encryption.
266 --------------------------------------------------
267
268 This is a very brief description on how to setup samba to support
269 password encryption. More complete instructions will probably be added
270 later.
271
272 1) get and compile the libdes libraries. the source is available from
273 ftp://samba.anu.edu.au/pub/libdes/
274
275 2) enable the encryption stuff in the Samba makefile, making sure you
276 point it to the libdes library and include file (it needs des.h)
277 The entries you need to uncomment are the four lines after the comment :-
278
279 # This is for SMB encrypted (lanman) passwords.
280
281 Note that you may have to change the variable DES_BASE to
282 point at the place where you installed the DES library.
283
284 3) compile and install samba as usual
285
286 4) f your system can't compile the module getsmbpass.c then remove the
287 -DSMBGETPASS define from the Makefile.
288
289 5) enable encrypted passwords in smb.conf by adding the line 
290 "encrypt passwords = yes" in the [global] section
291
292 6) create the initial smbpasswd password file in the place you
293 specified in the Makefile. A simple way to do this based on your
294 existing Makefile (assuming it is in a reasonably standard format) is
295 like this:
296
297 cat /etc/passwd | mksmbpasswd.sh > /usr/local/samba/private/smbpasswd
298
299 Change ownership of private and smbpasswd to root.
300
301 chown -R root /usr/local/samba/private
302
303 Set the correct permissions on /usr/local/samba/private
304
305 chmod 500 /usr/local/samba/private
306
307 Set the correct permissions on /usr/local/samba/private/smbpasswd
308
309 chmod 600 /usr/local/samba/private/smbpasswd
310
311 note that the mksmbpasswd.sh script is in the samba source directory.
312
313 If this fails then you will find that you will need entries that look
314 like this:
315
316 # SMB password file.
317 tridge:148:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Andrew Tridgell:/home/tridge:/bin/tcsh
318
319 note that the uid and username fields must be right. Also, you must get
320 the number of X's right (there should be 32).
321
322 If you wish, install the smbpasswd program as suid root.
323
324 chown root /usr/local/samba/bin/smbpasswd
325 chmod 4555 /usr/local/samba/bin/smbpasswd
326
327 7) set the passwords for users using the smbpasswd command. For
328 example, as root you could do "smbpasswd tridge"
329
330 8) try it out!
331
332 Note that you can test things using smbclient, as it also now supports
333 encryption.
334
335 NOTE TO USA Sites that Mirror Samba
336 -----------------------------------
337
338 The DES library is considered a munition in the USA. Under US Law it is
339 illegal to export this software, or to put it in a freely available ftp
340 site.
341
342 Please do not mirror the libdes directory from the site on
343 samba.anu.edu.au
344
345 Thank you,
346
347 Jeremy Allison.
348
349 ==============================================================================
350 Footnote:       Please refer to WinNT.txt also