docs/devel/encryption.xml

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