1 files changed, 333 insertions, 0 deletions
diff --git a/docs/textdocs/ENCRYPTION.txt b/docs/textdocs/ENCRYPTION.txt
new file mode 100644
index 00000000000..046b473e9a1
--- /dev/null
+++ b/docs/textdocs/ENCRYPTION.txt
@@ -0,0 +1,333 @@
+		LanManager / Samba Password Encryption.
+		---------------------------------------
+
+With the development of LanManager 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 paintext
+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*.
+
+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 value 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.
+
+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 function derived from it. Also
+note that the cleartext password or 16 byte hashed value 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 value
+on disk. This is also bad. Why? Because the 16 byte hashed value is a
+"password equivalent". You cannot derive the users password from it,
+but it 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.
+
+- the SMB encryption code in Samba is new and has only had limited
+testing. We have tried hard to make it secure but in any new
+implementation of a password scheme there is the possability of an
+error. 
+
+
+The smbpasswd file.
+-------------------
+
+	In order for Samba to participate in the above protocol it must
+be able to look up the 16 byte hashed value 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: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 - the smbpasswd and Samba code will fail to validate
+any entries that do not have 32 characters between ':' characters.
+
+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: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).
+
+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 32 byte password field 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) and make it setuid root.
+
+Note that if you do not do this then the root user will have to set all
+users passwords.
+
+To set up smbpasswd as setuid root, change to the Samba binary install
+directory and then type (as root) :
+
+chown root smbpasswd
+chmod 4555 smbpasswd
+
+If smbpasswd is installed as setuid root then you would use it as
+follows.
+
+smbpasswd
+Old SMB password: <type old alue here - just hit return if there is NO 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.
+
+NOTE. As smbpasswd is designed to be installed as setuid root I would
+appreciate it if everyone examined the source code to look for
+potential security flaws. A setuid program, if not written properly can
+be an open door to a system cracker. Please help make this program
+secure by reporting all problems to me (the author, Jeremy Allison).
+
+My email address is :-
+
+jra@vantive.com
+
+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) get and compile the libdes libraries. the source is available from
+nimbus.anu.edu.au in pub/tridge/libdes/libdes.tar.92-10-13.gz
+
+2) enable the encryption stuff in the Samba makefile, making sure you
+point it to the libdes library and include file (it needs des.h)
+The entries you need to uncomment are the four lines after the comment :-
+
+# This is for SMB encrypted (lanman) passwords.
+
+Note that you may have to change the variable DES_BASE to
+point at the place where you installed the DES library.
+
+3) compile and install samba as usual
+
+4) f your system can't compile the module getsmbpass.c then remove the
+-DSMBGETPASS define from the Makefile.
+
+5) enable encrypted passwords in smb.conf by adding the line 
+"encrypt passwords = yes" in the [global] section
+
+6) 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: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).
+
+If you wish, install the smbpasswd program as suid root.
+
+chown root /usr/local/samba/bin/smbpasswd
+chmod 4555 /usr/local/samba/bin/smbpasswd
+
+7) set the passwords for users using the smbpasswd command. For
+example, as root you could do "smbpasswd tridge"
+
+8) try it out!
+
+Note that you can test things using smbclient, as it also now supports
+encryption.
+
+NOTE TO USA Sites that Mirror Samba
+-----------------------------------
+
+The DES library is considered a munition in the USA. Under US Law it is
+illegal to export this software, or to put it in a freely available ftp
+site.
+
+Please do not mirror the DES directory from the site on nimbus.anu.edu.au
+
+Thank you,
+
+Jeremy Allison.
+