315e7de53f7fe0f898a5baebc4491fe4a1d6e904
[samba.git] / docs / textdocs / ENCRYPTION.txt
1 !==
2 !== ENCRYPTION.txt for Samba release 1.9.18 08 Jan 1998
3 !==
4 Contributor:    Jeremy Allison <samba-bugs@samba.anu.edu.au>
5 Updated:        June 27, 1997
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).
211
212 Note : This file should be protected very carefully. Anyone with
213 access to this file can (with enough knowledge of the protocols) gain
214 access to your SMB server. The file is thus more sensitive than a
215 normal unix /etc/passwd file.
216
217 The smbpasswd Command.
218 ----------------------
219
220 The smbpasswd command maintains the two 32 byte password fields in
221 the smbpasswd file. If you wish to make it similar to the unix passwd
222 or yppasswd programs, install it in /usr/local/samba/bin (or your main
223 Samba binary directory) and make it setuid root.
224
225 Note that if you do not do this then the root user will have to set all
226 users passwords.
227
228 To set up smbpasswd as setuid root, change to the Samba binary install
229 directory and then type (as root) :
230
231 chown root smbpasswd
232 chmod 4555 smbpasswd
233
234 If smbpasswd is installed as setuid root then you would use it as
235 follows.
236
237 smbpasswd
238 Old SMB password: <type old alue here - just hit return if there is NO PASSWORD>
239 New SMB Password: < type new value >
240 Repeat New SMB Password: < re-type new value >
241
242 If the old value does not match the current value stored for that user,
243 or the two new values do not match each other, then the password will
244 not be changed.
245
246 If invoked by an ordinary user it will only allow the user to change
247 his or her own Samba password.
248
249 If run by the root user smbpasswd may take an optional argument,
250 specifying the user name whose SMB password you wish to change.  Note
251 that when run as root smbpasswd does not prompt for or check the old
252 password value, thus allowing root to set passwords for users who have
253 forgotten their passwords.
254
255 smbpasswd is designed to work in the same way and be familiar to UNIX
256 users who use the passwd or yppasswd commands.
257
258 NOTE. As smbpasswd is designed to be installed as setuid root I would
259 appreciate it if everyone examined the source code to look for
260 potential security flaws. A setuid program, if not written properly can
261 be an open door to a system cracker. Please help make this program
262 secure by reporting all problems to me (the author, Jeremy Allison).
263
264 My email address is :-
265
266 jallison@whistle.com
267
268 Setting up Samba to support LanManager Encryption.
269 --------------------------------------------------
270
271 This is a very brief description on how to setup samba to support
272 password encryption. More complete instructions will probably be added
273 later.
274
275 1) compile and install samba as usual
276
277 2) if your system can't compile the module getsmbpass.c then remove the
278 -DSMBGETPASS define from the Makefile.
279
280 3) enable encrypted passwords in smb.conf by adding the line 
281 "encrypt passwords = yes" in the [global] section
282
283 4) create the initial smbpasswd password file in the place you
284 specified in the Makefile. A simple way to do this based on your
285 existing Makefile (assuming it is in a reasonably standard format) is
286 like this:
287
288 cat /etc/passwd | mksmbpasswd.sh > /usr/local/samba/private/smbpasswd
289
290 Change ownership of private and smbpasswd to root.
291
292 chown -R root /usr/local/samba/private
293
294 Set the correct permissions on /usr/local/samba/private
295
296 chmod 500 /usr/local/samba/private
297
298 Set the correct permissions on /usr/local/samba/private/smbpasswd
299
300 chmod 600 /usr/local/samba/private/smbpasswd
301
302 note that the mksmbpasswd.sh script is in the samba source directory.
303
304 If this fails then you will find that you will need entries that look
305 like this:
306
307 # SMB password file.
308 tridge:148:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Andrew Tridgell:/home/tridge:/bin/tcsh
309
310 note that the uid and username fields must be right. Also, you must get
311 the number of X's right (there should be 32).
312
313 If you wish, install the smbpasswd program as suid root.
314
315 chown root /usr/local/samba/bin/smbpasswd
316 chmod 4555 /usr/local/samba/bin/smbpasswd
317
318 5) set the passwords for users using the smbpasswd command. For
319 example, as root you could do "smbpasswd tridge"
320
321 6) try it out!
322
323 Note that you can test things using smbclient, as it also now supports
324 encryption.
325
326 ==============================================================================
327 Footnote:       Please refer to WinNT.txt also