s4:dsdb_enum_group_mem - use "unsigned" counters
[Samba/ekacnet.git] / docs-xml / Samba3-Developers-Guide / encryption.xml
blobbe00beba5d70f5aecc2374498bc13b5113e9abf6
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <chapter id="pwencrypt">
6 <chapterinfo>
7         <author>
8                 <firstname>Jeremy</firstname><surname>Allison</surname>
9                 <affiliation>
10                         <orgname>Samba Team</orgname>
11                         <address>
12                                 <email>samba@samba.org</email>
13                         </address>
14                 </affiliation>
15         </author>
17         <pubdate>19 Apr 1999</pubdate>
18 </chapterinfo>
19         
20 <title>LanMan and NT Password Encryption</title>
22 <sect1>
23         <title>Introduction</title>
24         
25         <para>With the development of LanManager and Windows NT 
26         compatible password encryption for Samba, it is now able 
27         to validate user connections in exactly the same way as 
28         a LanManager or Windows NT server.</para>
30         <para>This document describes how the SMB password encryption 
31         algorithm works and what issues there are in choosing whether 
32         you want to use it. You should read it carefully, especially 
33         the part about security and the "PROS and CONS" section.</para>
34         
35 </sect1>
37 <sect1>
38         <title>How does it work?</title>
40         <para>LanManager encryption is somewhat similar to UNIX 
41         password encryption. The server uses a file containing a 
42         hashed value of a user's password.  This is created by taking 
43         the user's plaintext password, capitalising it, and either 
44         truncating to 14 bytes or padding to 14 bytes with null bytes. 
45         This 14 byte value is used as two 56 bit DES keys to encrypt 
46         a 'magic' eight byte value, forming a 16 byte value which is 
47         stored by the server and client. Let this value be known as 
48         the "hashed password".</para>
49         
50         <para>Windows NT encryption is a higher quality mechanism, 
51         consisting of doing an MD4 hash on a Unicode version of the user's 
52         password. This also produces a 16 byte hash value that is 
53         non-reversible.</para>
55         <para>When a client (LanManager, Windows for WorkGroups, Windows 
56         95 or Windows NT) wishes to mount a Samba drive (or use a Samba 
57         resource), it first requests a connection and negotiates the 
58         protocol that the client and server will use. In the reply to this 
59         request the Samba server generates and appends an 8 byte, random 
60         value - this is stored in the Samba server after the reply is sent 
61         and is known as the "challenge".  The challenge is different for 
62         every client connection.</para>
64         <para>The client then uses the hashed password (16 byte values 
65         described above), appended with 5 null bytes, as three 56 bit 
66         DES keys, each of which is used to encrypt the challenge 8 byte 
67         value, forming a 24 byte value known as the "response".</para>
69         <para>In the SMB call SMBsessionsetupX (when user level security 
70         is selected) or the call SMBtconX (when share level security is 
71         selected), the 24 byte response is returned by the client to the 
72         Samba server.  For Windows NT protocol levels the above calculation 
73         is done on both hashes of the user's password and both responses are 
74         returned in the SMB call, giving two 24 byte values.</para>
76         <para>The Samba server then reproduces the above calculation, using 
77         its own stored value of the 16 byte hashed password (read from the 
78         <filename>smbpasswd</filename> file - described later) and the challenge 
79         value that it kept from the negotiate protocol reply. It then checks 
80         to see if the 24 byte value it calculates matches the 24 byte value 
81         returned to it from the client.</para>
83         <para>If these values match exactly, then the client knew the 
84         correct password (or the 16 byte hashed value - see security note 
85         below) and is thus allowed access. If not, then the client did not 
86         know the correct password and is denied access.</para>
88         <para>Note that the Samba server never knows or stores the cleartext 
89         of the user's password - just the 16 byte hashed values derived from 
90         it. Also note that the cleartext password or 16 byte hashed values 
91         are never transmitted over the network - thus increasing security.</para>
92 </sect1>
94 <sect1>
95         <title>The smbpasswd file</title>
96         <anchor id="SMBPASSWDFILEFORMAT"/>
97         <para>In order for Samba to participate in the above protocol 
98         it must be able to look up the 16 byte hashed values given a user name.
99         Unfortunately, as the UNIX password value is also a one way hash
100         function (ie. it is impossible to retrieve the cleartext of the user's
101         password given the UNIX hash of it), a separate password file
102         containing this 16 byte value must be kept. To minimise problems with
103         these two password files, getting out of sync, the UNIX <filename>
104         /etc/passwd</filename> and the <filename>smbpasswd</filename> file, 
105         a utility, <command>mksmbpasswd.sh</command>, is provided to generate
106         a smbpasswd file from a UNIX <filename>/etc/passwd</filename> file.
107         </para>
110         <para>To generate the smbpasswd file from your <filename>/etc/passwd
111         </filename> file use the following command:</para>
112         
113         <para><prompt>$ </prompt><userinput>cat /etc/passwd | mksmbpasswd.sh
114         &gt; /usr/local/samba/private/smbpasswd</userinput></para>
115         
116         <para>If you are running on a system that uses NIS, use</para>
118         <para><prompt>$ </prompt><userinput>ypcat passwd | mksmbpasswd.sh
119         &gt; /usr/local/samba/private/smbpasswd</userinput></para>
120         
121         <para>The <command>mksmbpasswd.sh</command> program is found in 
122         the Samba source directory. By default, the smbpasswd file is 
123         stored in :</para>
125         <para><filename>/usr/local/samba/private/smbpasswd</filename></para>
127         <para>The owner of the <filename>/usr/local/samba/private/</filename> 
128         directory should be set to root, and the permissions on it should 
129         be set to 0500 (<command>chmod 500 /usr/local/samba/private</command>).
130         </para>
132         <para>Likewise, the smbpasswd file inside the private directory should 
133         be owned by root and the permissions on is should be set to 0600
134         (<command>chmod 600 smbpasswd</command>).</para>
137         <para>The format of the smbpasswd file is (The line has been 
138         wrapped here. It should appear as one entry per line in 
139         your smbpasswd file.)</para>
140         
141         <para><programlisting>
142 username:uid:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:
143         [Account type]:LCT-&lt;last-change-time&gt;:Long name
144         </programlisting></para>
145         
146         <para>Although only the <replaceable>username</replaceable>, 
147         <replaceable>uid</replaceable>, <replaceable>
148         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</replaceable>,
149         [<replaceable>Account type</replaceable>] and <replaceable>
150         last-change-time</replaceable> sections are significant 
151         and are looked at in the Samba code.</para>
153         <para>It is <emphasis>VITALLY</emphasis> important that there by 32 
154         'X' characters between the two ':' characters in the XXX sections - 
155         the smbpasswd and Samba code will fail to validate any entries that 
156         do not have 32 characters  between ':' characters. The first XXX 
157         section is for the Lanman password hash, the second is for the 
158         Windows NT version.</para>
160         <para>When the password file is created all users have password entries
161         consisting of 32 'X' characters. By default this disallows any access
162         as this user. When a user has a password set, the 'X' characters change
163         to 32 ascii hexadecimal digits (0-9, A-F). These are an ascii
164         representation of the 16 byte hashed value of a user's password.</para>
166         <para>To set a user to have no password (not recommended), edit the file
167         using vi, and replace the first 11 characters with the ascii text
168         <constant>"NO PASSWORD"</constant> (minus the quotes).</para>
170         <para>For example, to clear the password for user bob, his smbpasswd file 
171         entry would look like :</para>
173         <para><programlisting>
174 bob:100:NO PASSWORDXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:
175         [U          ]:LCT-00000000:Bob's full name:/bobhome:/bobshell
176         </programlisting></para>
177         
178         <para>If you are allowing users to use the smbpasswd command to set 
179         their own passwords, you may want to give users NO PASSWORD initially 
180         so they do not have to enter a previous password when changing to their 
181         new password (not recommended). In order for you to allow this the
182         <command>smbpasswd</command> program must be able to connect to the 
183         <command>smbd</command> daemon as that user with no password. Enable this 
184         by adding the line :</para>
186         <para><command>null passwords = yes</command></para>
187         
188         <para>to the [global] section of the smb.conf file (this is why 
189         the above scenario is not recommended). Preferably, allocate your
190         users a default password to begin with, so you do not have
191         to enable this on your server.</para>
193         <para><emphasis>Note : </emphasis>This file should be protected very 
194         carefully. Anyone with access to this file can (with enough knowledge of 
195         the protocols) gain access to your SMB server. The file is thus more 
196         sensitive than a normal unix <filename>/etc/passwd</filename> file.</para>
197 </sect1>
199 </chapter>