docs/docbook/projdoc/ENCRYPTION.sgml

   1 <chapter>
   2
   3
   4 <chapterinfo>
   5         <author>
   6                 <firstname>Jeremy</firstname><surname>Allison</surname>
   7                 <affiliation>
   8                         <orgname>Samba Team</orgname>
   9                         <address>
  10                                 <email>samba@samba.org</email>
  11                         </address>
  12                 </affiliation>
  13         </author>
  14
  15
  16         <pubdate>19 Apr 1999</pubdate>
  17 </chapterinfo>
  18
  19 <title>LanMan and NT Password Encryption in Samba 2.x</title>
  20
  21
  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>
  29
  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>
  36
  37 <sect1>
  38         <title>How does it work?</title>
  39
  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>
  54
  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>
  63
  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>
  68
  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>
  75
  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>
  82
  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>
  87
  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>
  93
  94 <sect1>
  95         <title>Important Notes About Security</title>
  96
  97         <para>The unix and SMB password encryption techniques seem similar
  98         on the surface. This similarity is, however, only skin deep. The unix
  99         scheme typically sends clear text passwords over the nextwork when
 100         logging in. This is bad. The SMB encryption scheme never sends the
 101         cleartext password over the network but it does store the 16 byte
 102         hashed values on disk. This is also bad. Why? Because the 16 byte hashed
 103         values are a "password equivalent". You cannot derive the user's
 104         password from them, but they could potentially be used in a modified
 105         client to gain access to a server. This would require considerable
 106         technical knowledge on behalf of the attacker but is perfectly possible.
 107         You should thus treat the smbpasswd file as though it contained the
 108         cleartext passwords of all your users. Its contents must be kept
 109         secret, and the file should be protected accordingly.</para>
 110
 111         <para>Ideally we would like a password scheme which neither requires
 112         plain text passwords on the net or on disk. Unfortunately this
 113         is not available as Samba is stuck with being compatible with
 114         other SMB systems (WinNT, WfWg, Win95 etc). </para>
 115
 116         <warning>
 117                 <para>Note that Windows NT 4.0 Service pack 3 changed the
 118                 default for permissible authentication so that plaintext
 119                 passwords are <emphasis>never</emphasis> sent over the wire.
 120                 The solution to this is either to switch to encrypted passwords
 121                 with Samba or edit the Windows NT registry to re-enable plaintext
 122                 passwords. See the document WinNT.txt for details on how to do
 123                 this.</para>
 124
 125                 <para>Other Microsoft operating systems which also exhibit
 126                 this behavior includes</para>
 127
 128                 <itemizedlist>
 129                         <listitem><para>MS DOS Network client 3.0 with
 130                         the basic network redirector installed</para></listitem>
 131
 132                         <listitem><para>Windows 95 with the network redirector
 133                         update installed</para></listitem>
 134
 135                         <listitem><para>Windows 98 [se]</para></listitem>
 136
 137                         <listitem><para>Windows 2000</para></listitem>
 138                 </itemizedlist>
 139
 140                 <para><emphasis>Note :</emphasis>All current release of
 141                 Microsoft SMB/CIFS clients support authentication via the
 142                 SMB Challenge/Response mechanism described here.  Enabling
 143                 clear text authentication does not disable the ability
 144                 of the client to particpate in encrypted authentication.</para>
 145         </warning>
 146
 147         <sect2>
 148                 <title>Advantages of SMB Encryption</title>
 149
 150                 <itemizedlist>
 151                         <listitem><para>plain text passwords are not passed across
 152                         the network. Someone using a network sniffer cannot just
 153                         record passwords going to the SMB server.</para>
 154                         </listitem>
 155
 156                         <listitem><para>WinNT doesn't like talking to a server
 157                         that isn't using SMB encrypted passwords. It will refuse
 158                         to browse the server if the server is also in user level
 159                         security mode. It will insist on prompting the user for the
 160                         password on each connection, which is very annoying. The
 161                         only things you can do to stop this is to use SMB encryption.
 162                         </para></listitem>
 163                 </itemizedlist>
 164         </sect2>
 165
 166
 167         <sect2>
 168                 <title>Advantages of non-encrypted passwords</title>
 169
 170                 <itemizedlist>
 171                         <listitem><para>plain text passwords are not kept
 172                         on disk. </para></listitem>
 173
 174                         <listitem><para>uses same password file as other unix
 175                         services such as login and ftp</para></listitem>
 176
 177                         <listitem><para>you are probably already using other
 178                         services (such as telnet and ftp) which send plain text
 179                         passwords over the net, so sending them for SMB isn't
 180                         such a big deal.</para></listitem>
 181                 </itemizedlist>
 182         </sect2>
 183 </sect1>
 184
 185
 186 <sect1>
 187         <title><anchor id="SMBPASSWDFILEFORMAT">The smbpasswd file</title>
 188
 189         <para>In order for Samba to participate in the above protocol
 190         it must be able to look up the 16 byte hashed values given a user name.
 191         Unfortunately, as the UNIX password value is also a one way hash
 192         function (ie. it is impossible to retrieve the cleartext of the user's
 193         password given the UNIX hash of it), a separate password file
 194         containing this 16 byte value must be kept. To minimise problems with
 195         these two password files, getting out of sync, the UNIX <filename>
 196         /etc/passwd</filename> and the <filename>smbpasswd</filename> file,
 197         a utility, <command>mksmbpasswd.sh</command>, is provided to generate
 198         a smbpasswd file from a UNIX <filename>/etc/passwd</filename> file.
 199         </para
 200
 201
 202         <para>To generate the smbpasswd file from your <filename>/etc/passwd
 203         </filename> file use the following command :</para>
 204
 205         <para><prompt>$ </prompt><userinput>cat /etc/passwd | mksmbpasswd.sh
 206         &gt; /usr/local/samba/private/smbpasswd</userinput></para>
 207
 208         <para>If you are running on a system that uses NIS, use</para>
 209
 210         <para><prompt>$ </prompt><userinput>ypcat passwd | mksmbpasswd.sh
 211         &gt; /usr/local/samba/private/smbpasswd</userinput></para>
 212
 213         <para>The <command>mksmbpasswd.sh</command> program is found in
 214         the Samba source directory. By default, the smbpasswd file is
 215         stored in :</para>
 216
 217         <para><filename>/usr/local/samba/private/smbpasswd</filename></para>
 218
 219         <para>The owner of the <filename>/usr/local/samba/private/</filename>
 220         directory should be set to root, and the permissions on it should
 221         be set to 0500 (<command>chmod 500 /usr/local/samba/private</command>).
 222         </para>
 223
 224         <para>Likewise, the smbpasswd file inside the private directory should
 225         be owned by root and the permissions on is should be set to 0600
 226         (<command>chmod 600 smbpasswd</command>).</para>
 227
 228
 229         <para>The format of the smbpasswd file is (The line has been
 230         wrapped here. It should appear as one entry per line in
 231         your smbpasswd file.)</para>
 232
 233         <para><programlisting>
 234 username:uid:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:
 235         [Account type]:LCT-&lt;last-change-time&gt;:Long name
 236         </programlisting></para>
 237
 238         <para>Although only the <replaceable>username</replaceable>,
 239         <replaceable>uid</replaceable>, <replaceable>
 240         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</replaceable>,
 241         [<replaceable>Account type</replaceable>] and <replaceable>
 242         last-change-time</replaceable> sections are significant
 243         and are looked at in the Samba code.</para>
 244
 245         <para>It is <emphasis>VITALLY</emphasis> important that there by 32
 246         'X' characters between the two ':' characters in the XXX sections -
 247         the smbpasswd and Samba code will fail to validate any entries that
 248         do not have 32 characters  between ':' characters. The first XXX
 249         section is for the Lanman password hash, the second is for the
 250         Windows NT version.</para>
 251
 252         <para>When the password file is created all users have password entries
 253         consisting of 32 'X' characters. By default this disallows any access
 254         as this user. When a user has a password set, the 'X' characters change
 255         to 32 ascii hexadecimal digits (0-9, A-F). These are an ascii
 256         representation of the 16 byte hashed value of a user's password.</para>
 257
 258         <para>To set a user to have no password (not recommended), edit the file
 259         using vi, and replace the first 11 characters with the ascii text
 260         <constant>"NO PASSWORD"</constant> (minus the quotes).</para>
 261
 262         <para>For example, to clear the password for user bob, his smbpasswd file
 263         entry would look like :</para>
 264
 265         <para><programlisting>
 266         bob:100:NO PASSWORDXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:[U          ]:LCT-00000000:Bob's full name:/bobhome:/bobshell
 267         </programlisting></para>
 268
 269         <para>If you are allowing users to use the smbpasswd command to set
 270         their own passwords, you may want to give users NO PASSWORD initially
 271         so they do not have to enter a previous password when changing to their
 272         new password (not recommended). In order for you to allow this the
 273         <command>smbpasswd</command> program must be able to connect to the
 274         <command>smbd</command> daemon as that user with no password. Enable this
 275         by adding the line :</para>
 276
 277         <para><command>null passwords = yes</command></para>
 278
 279         <para>to the [global] section of the smb.conf file (this is why
 280         the above scenario is not recommended). Preferably, allocate your
 281         users a default password to begin with, so you do not have
 282         to enable this on your server.</para>
 283
 284         <para><emphasis>Note : </emphasis>This file should be protected very
 285         carefully. Anyone with access to this file can (with enough knowledge of
 286         the protocols) gain access to your SMB server. The file is thus more
 287         sensitive than a normal unix <filename>/etc/passwd</filename> file.</para>
 288 </sect1>
 289
 290
 291 <sect1>
 292         <title>The smbpasswd Command</title>
 293
 294         <para>The smbpasswd command maintains the two 32 byte password fields
 295         in the smbpasswd file. If you wish to make it similar to the unix
 296         <command>passwd</command> or <command>yppasswd</command> programs,
 297         install it in <filename>/usr/local/samba/bin/</filename> (or your
 298         main Samba binary directory).</para>
 299
 300         <para>Note that as of Samba 1.9.18p4 this program <emphasis>MUST NOT
 301         BE INSTALLED</emphasis> setuid root (the new <command>smbpasswd</command>
 302         code enforces this restriction so it cannot be run this way by
 303         accident).</para>
 304
 305         <para><command>smbpasswd</command> now works in a client-server mode
 306         where it contacts the local smbd to change the user's password on its
 307         behalf. This has enormous benefits - as follows.</para>
 308
 309         <itemizedlist>
 310                 <listitem><para>smbpasswd no longer has to be setuid root -
 311                 an enormous range of potential security problems is
 312                 eliminated.</para></listitem>
 313
 314                 <listitem><para><command>smbpasswd</command> now has the capability
 315                 to change passwords on Windows NT servers (this only works when
 316                 the request is sent to the NT Primary Domain Controller if you
 317                 are changing an NT Domain user's password).</para></listitem>
 318         </itemizedlist>
 319
 320         <para>To run smbpasswd as a normal user just type :</para>
 321
 322         <para><prompt>$ </prompt><userinput>smbpasswd</userinput></para>
 323         <para><prompt>Old SMB password: </prompt><userinput>&lt;type old value here -
 324         or hit return if there was no old password&gt;</userinput></para>
 325         <para><prompt>New SMB Password: </prompt><userinput>&lt;type new value&gt;
 326         </userinput></para>
 327         <para><prompt>Repeat New SMB Password: </prompt><userinput>&lt;re-type new value
 328         </userinput></para>
 329
 330         <para>If the old value does not match the current value stored for
 331         that user, or the two new values do not match each other, then the
 332         password will not be changed.</para>
 333
 334         <para>If invoked by an ordinary user it will only allow the user
 335         to change his or her own Samba password.</para>
 336
 337         <para>If run by the root user smbpasswd may take an optional
 338         argument, specifying the user name whose SMB password you wish to
 339         change.  Note that when run as root smbpasswd does not prompt for
 340         or check the old password value, thus allowing root to set passwords
 341         for users who have forgotten their passwords.</para>
 342
 343         <para><command>smbpasswd</command> is designed to work in the same way
 344         and be familiar to UNIX users who use the <command>passwd</command> or
 345         <command>yppasswd</command> commands.</para>
 346
 347         <para>For more details on using <command>smbpasswd</command> refer
 348         to the man page which will always be the definitive reference.</para>
 349 </sect1>
 350
 351
 352 <sect1>
 353         <title>Setting up Samba to support LanManager Encryption</title>
 354
 355         <para>This is a very brief description on how to setup samba to
 356         support password encryption. </para>
 357
 358         <orderedlist numeration="Arabic">
 359                 <listitem><para>compile and install samba as usual</para>
 360                 </listitem>
 361
 362                 <listitem><para>enable encrypted passwords in <filename>
 363                 smb.conf</filename> by adding the line <command>encrypt
 364                 passwords = yes</command> in the [global] section</para>
 365                 </listitem>
 366
 367                 <listitem><para>create the initial <filename>smbpasswd</filename>
 368                 password file in the place you specified in the Makefile
 369                 (--prefix=&lt;dir&gt;). See the notes under the <link
 370                 linkend="SMBPASSWDFILEFORMAT">The smbpasswd File</link>
 371                 section earlier in the document for details.</para>
 372                 </listitem>
 373         </orderedlist>
 374
 375         <para>Note that you can test things using smbclient.</para>
 376 </sect1>
 377
 378 </chapter>