preparing for release of 2.0.0 alpha

[Samba.git] / docs / textdocs / ENCRYPTION.txt

!==
!== ENCRYPTION.txt for Samba release 2.0.0-alpha 31 Aug 1998
!==
Contributor:    Jeremy Allison <samba-bugs@samba.anu.edu.au>
Updated:        March 19, 1998
Note:           Please refer to WinNT.txt also

Subject:        LanManager / Samba Password Encryption.
============================================================================

With the development of LanManager and Windows NT compatible password 
encryption for Samba, it is now able to validate user connections in 
exactly the same way as a LanManager or Windows NT server.

This document describes how the SMB password encryption algorithm
works and what issues there are in choosing whether you want to use
it. You should read it carefully, especially the part about security
and the "PROS and CONS" section.

How does it work ?
------------------

LanManager encryption is somewhat similar to UNIX password
encryption. The server uses a file containing a hashed value of a
users password.  This is created by taking the users plaintext
password, capitalising it, and either truncating to 14 bytes (or
padding to 14 bytes with null bytes). This 14 byte value is used as
two 56 bit DES keys to encrypt a 'magic' eight byte value, forming a
16 byte value which is stored by the server and client. Let this value
be known as the *hashed password*.

Windows NT encryption is a higher quality mechanism, consisting
of doing an MD4 hash on a Unicode version of the users password. This
also produces a 16 byte hash value that is non-reversible.

When a client (LanManager, Windows for WorkGroups, Windows 95 or
Windows NT) wishes to mount a Samba drive (or use a Samba resource) it
first requests a connection and negotiates the protocol that the client
and server will use. In the reply to this request the Samba server
generates and appends an 8 byte, random value - this is stored in the
Samba server after the reply is sent and is known as the *challenge*.

The challenge is different for every client connection.

The client then uses the hashed password (16 byte values described
above), appended with 5 null bytes, as three 56 bit DES keys, each of
which is used to encrypt the challenge 8 byte value, forming a 24 byte
value known as the *response*.

In the SMB call SMBsessionsetupX (when user level security is
selected) or the call SMBtconX (when share level security is selected)
the 24 byte response is returned by the client to the Samba server.
For Windows NT protocol levels the above calculation is done on
both hashes of the users password and both responses are returned
in the SMB call, giving two 24 byte values.

The Samba server then reproduces the above calculation, using it's own
stored value of the 16 byte hashed password (read from the smbpasswd
file - described later) and the challenge value that it kept from the
negotiate protocol reply. It then checks to see if the 24 byte value it
calculates matches the 24 byte value returned to it from the client.

If these values match exactly, then the client knew the correct
password (or the 16 byte hashed value - see security note below) and
is this allowed access. If not then the client did not know the
correct password and is denied access.

Note that the Samba server never knows or stores the cleartext of the
users password - just the 16 byte hashed values derived from it. Also
note that the cleartext password or 16 byte hashed values are never
transmitted over the network - thus increasing security.

IMPORTANT NOTE ABOUT SECURITY
-----------------------------

The unix and SMB password encryption techniques seem similar on the
surface. This similarity is, however, only skin deep. The unix scheme
typically sends clear text passwords over the nextwork when logging
in. This is bad. The SMB encryption scheme never sends the cleartext
password over the network but it does store the 16 byte hashed values
on disk. This is also bad. Why? Because the 16 byte hashed values are a
"password equivalent". You cannot derive the users password from them,
but they could potentially be used in a modified client to gain access
to a server. This would require considerable technical knowledge on
behalf of the attacker but is perfectly possible. You should thus
treat the smbpasswd file as though it contained the cleartext
passwords of all your users. Its contents must be kept secret, and the
file should be protected accordingly.

Ideally we would like a password scheme which neither requires plain
text passwords on the net or on disk. Unfortunately this is not
available as Samba is stuck with being compatible with other SMB
systems (WinNT, WfWg, Win95 etc). 


PROS AND CONS
-------------

There are advantages and disadvantages to both schemes. 

Advantages of SMB Encryption:
-----------------------------

- plain text passwords are not passed across the network. Someone using
a network sniffer cannot just record passwords going to the SMB server.

- WinNT doesn't like talking to a server that isn't using SMB
encrypted passwords. It will refuse to browse the server if the server
is also in user level security mode. It will insist on promting the
user for the password on each connection, which is very annoying. The
only things you can do to stop this is to use SMB encryption.

Advantages of non-encrypted passwords:
--------------------------------------

- plain text passwords are not kept on disk. 

- uses same password file as other unix services such as login and
ftp

- you are probably already using other services (such as telnet and
ftp) which send plain text passwords over the net, so not sending them
for SMB isn't such a big deal.

Note that Windows NT 4.0 Service pack 3 changed the default for
permissible authentication so that plaintext passwords are *never*
sent over the wire. The solution to this is either to switch to
encrypted passwords with Samba or edit the Windows NT registry to
re-enable plaintext passwords. See the document WinNT.txt for
details on how to do this.

The smbpasswd file.
-------------------

In order for Samba to participate in the above protocol it must
be able to look up the 16 byte hashed values given a user name.
Unfortunately, as the UNIX password value is also a one way hash
function (ie. it is impossible to retrieve the cleartext of the users
password given the UNIX hash of it) then a separate password file
containing this 16 byte value must be kept. To minimise problems with
these two password files, getting out of sync, the UNIX /etc/passwd and
the smbpasswd file, a utility, mksmbpasswd.sh, is provided to generate
a smbpasswd file from a UNIX /etc/passwd file.

To generate the smbpasswd file from your /etc/passwd file use the
following command :-

cat /etc/passwd | mksmbpasswd.sh >/usr/local/samba/private/smbpasswd

If you are running on a system that uses NIS, use

ypcat passwd | mksmbpasswd.sh >/usr/local/samba/private/smbpasswd

The mksmbpasswd.sh program is found in the Samba source directory. By
default, the smbpasswd file is stored in :-

/usr/local/samba/private/smbpasswd

The owner of the /usr/local/samba/private directory should be set to
root, and the permissions on it should be set to :-

r-x------

The command 

chmod 500 /usr/local/samba/private

will do the trick. Likewise, the smbpasswd file inside the private
directory should be owned by root and the permissions on is should be
set to

rw-------

by the command :-

chmod 600 smbpasswd.

The format of the smbpasswd file is

username:uid:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Long name:user home dir:user shell

Although only the username, uid, and XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
sections are significant and are looked at in the Samba code.

It is *VITALLY* important that there by 32 'X' characters between the
two ':' characters in the XXX sections - the smbpasswd and Samba code 
will fail to validate any entries that do not have 32 characters 
between ':' characters. The first XXX section is for the Lanman password
hash, the second is for the Windows NT version.

When the password file is created all users have password entries
consisting of 32 'X' characters. By default this disallows any access
as this user. When a user has a password set, the 'X' characters change
to 32 ascii hexadecimal digits (0-9, A-F). These are an ascii
representation of the 16 byte hashed value of a users password.

To set a user to have no password (not recommended), edit the file
using vi, and replace the first 11 characters with the asci text

NO PASSWORD

Eg. To clear the password for user bob, his smbpasswd file entry would
look like :

bob:100:NO PASSWORDXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Bob's full name:/bobhome:/bobshell

If you are allowing users to use the smbpasswd command to set their own
passwords, you may want to give users NO PASSWORD initially so they do
not have to enter a previous password when changing to their new
password (not recommended). In order for you to allow this the
smbpasswd program must be able to connect to the smbd daemon as
that user with no password. Enable this by adding the line :

null passwords = true

to the [global] section of the smb.conf file (this is why the
above scenario is not recommended). Preferebly, allocate your
users a default password to begin with, so you do not have
to enable this on your server.

Note : This file should be protected very carefully. Anyone with
access to this file can (with enough knowledge of the protocols) gain
access to your SMB server. The file is thus more sensitive than a
normal unix /etc/passwd file.

The smbpasswd Command.
----------------------

The smbpasswd command maintains the two 32 byte password fields in
the smbpasswd file. If you wish to make it similar to the unix passwd
or yppasswd programs, install it in /usr/local/samba/bin (or your main
Samba binary directory).

Note that as of Samba 1.9.18p4 this program MUST NOT BE INSTALLED
setuid root (the new smbpasswd code enforces this restriction so
it cannot be run this way by accident).

smbpasswd now works in a client-server mode where it contacts
the local smbd to change the users password on its behalf. This
has enormous benefits - as follows.

1). smbpasswd no longer has to be setuid root - an enourmous
range of potential security problems is eliminated.

2). smbpasswd now has the capability to change passwords
on Windows NT servers (this only works when the request is
sent to the NT Primary Domain Controller if you are changing 
an NT Domain users password).

To run smbpasswd as a normal user just type :

smbpasswd
Old SMB password: <type old value here - or hit return if there was no old password >
New SMB Password: < type new value >
Repeat New SMB Password: < re-type new value >

If the old value does not match the current value stored for that user,
or the two new values do not match each other, then the password will
not be changed.

If invoked by an ordinary user it will only allow the user to change
his or her own Samba password.

If run by the root user smbpasswd may take an optional argument,
specifying the user name whose SMB password you wish to change.  Note
that when run as root smbpasswd does not prompt for or check the old
password value, thus allowing root to set passwords for users who have
forgotten their passwords.

smbpasswd is designed to work in the same way and be familiar to UNIX
users who use the passwd or yppasswd commands.

For more details on using smbpasswd refer to the man page which
will always be the definitive reference.

Setting up Samba to support LanManager Encryption.
--------------------------------------------------

This is a very brief description on how to setup samba to support
password encryption. More complete instructions will probably be added
later.

1) compile and install samba as usual

2) if your system can't compile the module getsmbpass.c then remove the
-DSMBGETPASS define from the Makefile.

3) enable encrypted passwords in smb.conf by adding the line 
"encrypt passwords = yes" in the [global] section

4) create the initial smbpasswd password file in the place you
specified in the Makefile. A simple way to do this based on your
existing Makefile (assuming it is in a reasonably standard format) is
like this:

cat /etc/passwd | mksmbpasswd.sh > /usr/local/samba/private/smbpasswd

Change ownership of private and smbpasswd to root.

chown -R root /usr/local/samba/private

Set the correct permissions on /usr/local/samba/private

chmod 500 /usr/local/samba/private

Set the correct permissions on /usr/local/samba/private/smbpasswd

chmod 600 /usr/local/samba/private/smbpasswd

note that the mksmbpasswd.sh script is in the samba source directory.

If this fails then you will find that you will need entries that look
like this:

# SMB password file.
tridge:148:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:Andrew Tridgell:/home/tridge:/bin/tcsh

note that the uid and username fields must be right. Also, you must get
the number of X's right (there should be 32).

5) set the passwords for users using the smbpasswd command. For
example, as root you could do "smbpasswd tridge"

6) try it out!

Note that you can test things using smbclient, as it also now supports
encryption.

==============================================================================
Footnote:       Please refer to WinNT.txt also