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