Encode UNIX Password
====================

Readme for Release 1.2 - 13th February 2001
===========================================

Encode UNIX Password is a simple Windows 95/98/NT/W2K application that
allows user names and passwords to be encoded into a format suitable for
use with UNIX systems, in particular for the Apache web server running
on UNIX to restrict access to your web site to authorised users.  This
allows new users to be added to the .htpasswd file locally on the PC,
without needing to run a script while online to encode the passwords.
Once updated, the file will still need to be FTP'd to your web site.
Release 1.1 adds the ability to update the password file directly rather
than copying via the clipboard, to encode lists of users names and
passwords, and to be run with command line arguments from other
applications.


Using Encode UNIX Password Interactively
----------------------------------------

Encode UNIX Password provides two different means of encoding passwords,
Single Password or List of Passwords, and in both cases the encoded
password may either be saved to the password file or copied to the windows
clipboard from where they may be pasted into another application.

Encode Single Password requires a user name and password to be entered,
each must be a minimum of two characters, but there is no check on the
content of the information otherwise.  The user name should not however
contain a colon.  Clicking 'Encode Only' causes the user name and password
to be encoded, displayed in the Encoded Data field, and copied to the
windows clipboard.  Clicking 'Encode and Save' does the same, but also
adds the encoded data to the specified Password File.  The file names of
the last 20 files used may be selected from the drop down list, or a new
name selected or created by clicking Browse.  If a user of the same name
already exists in the Password File, a dialog is displayed to confirm the
earlier name should be replaced.

Encode List of Passwords works with combined user names and passwords,
separated by a forward slash, for example "fred/bloggs", one per line
in a file.  The user name must start at the beginning of the line, any
lines starting with space or * are ignored.  The user name may not contain
a slash and the password may not contain a space.  The password terminates
at the first space or control character (such as tab) after the slash, and
anything further on the line is ignored.  So an acceptable User List File
format would be:

-------------------------------------------------------------
* annual membership expires end July 2000

fred/bloggs      fred@hotmail.com
percy/johns      percy@hotmail
anne/bloggs      anne@hotmail.com
jane/doe         jane@hotmail
-------------------------------------------------------------

So as can be seen, more information can be kept in the User List File
about those with access to the web site.  A previously specified User
List File may be loaded by clicking 'Load User File', a file may be
selected by clicking Browse, or user names and passwords may be typed
or pasted directly into the User List box.   Clicking 'Encode Only'
causes the entire list of user names and passwords to be encoded,
displayed in the Encoded Data list and copied to the windows clipboard.
Clicking 'Encode and Save' does the same, but also adds the encoded data
to the specified Password File and saves the User List File to the
specified (if not blank).  If a user of the same name already exists in
the Password File, it is replaced automatically.


Using Encode UNIX Password With Command Arguments
-------------------------------------------------

Encode UNIX Password may also be driven by other windows applications,
from command line batch files, to automate creation of passwords using
command arguments.  A typical command to encode a user name and password
might be:

passwd /user=fred /pass=bloggs /file=c:\web\.htpasswd

where user and pass are required arguments, but file is optional.
Specifying any arguments will cause mom-interactive mode.   The encoded
data is always copied to the windows clipboard, and optionally added to
the specified file, replacing any existing user of the same name.   The
application will give an exit code of 1 if the user name and password are
successfully encoded, and an exit code of 2 for any error.  There is
currently no provision for display of messages while running with command
arguments.


Protecting Web Directories with Apache
--------------------------------------

Provided that the facility is enabled in the Apache web server, it is
possible to protect parts of your web site from unauthorised visitors so
that a logon and password is needed for access.  This is done by creating
a file called .htaccess in the directory to protect (as detailed later)
and that directory and any below it are then protected.  The actual list
of people allowed to access the directory are contained in a second file
usually named .htpasswd (but this can be different) which may be in the
same directory, or ideally in the web site root to make it harder (but not
impossible) for site visitors to access.


Does Your Web Server Support Protection?
----------------------------------------

Ideally, just ask your ISP!  But support is not always what you would
expect, so you can check whether password protection is available by
copying the .htaccess file supplied into a sub directory on your web site
(not the root), perhaps /private/.  Your browser should then come up with
an error when accessing files in that directory, probably 500 something
which means server error because the password file will not be found.


.htaccess file
--------------

This file is a simple text file that contains the file path for the
.htpasswd file and the greeting that visitors will see when the logon
dialog appears.  Two examples are:

-------------------------------------------------------------
AuthUserFile /usr/local/cixnet/users/m/a/magsoft/.htpasswd
AuthName Paid Member
AuthType Basic

<Limit GET POST>
require valid-user
</Limit>
--------------------------------------------------------------

and

--------------------------------------------------------------
AuthUserFile /usr/var/www/htdocs/wug/members/.htpasswd
AuthName Private User
AuthType Basic

<Limit GET POST>
require valid-user
</Limit>
--------------------------------------------------------------

In the first example, the web sites are down numerous levels of
directories, where m and a are the first two letters of the site alias
magsoft. In a lower level directory, it could be:

AuthUserFile /usr/local/cixnet/users/m/a/magsoft/www/members/.htpasswd.

The AuthName argument is the message that appears in the logon dialog,
the other information should not be changed.

The second example is for an ISP that has a simpler UNIX file layout,
and iwug/members/ is also where the web pages are located.

Unless your ISP has provided the full UNIX file path to your web site, you
will probably need their assistance in getting the correct AuthUserFile.
However you may be able to use a server side include (SSI) page, assuming
that the web server has that feature enabled.  So copy the file
ssitest.shtml to your web server and access it from your web browser.
It must have the extension SHTML (not SHTM) otherwise the SSIs will not be
processed. The SSI command:

<!--#echo var="DOCUMENT_ROOT"-->

should be replaced by the full path name to your root, while
SCRIPT_FILENAME will show the full path and file name to the SSI document
you are viewing.  So the AuthUserFile will be similar but with the file
name replaced by .htpasswd.


.htpasswd file
--------------

This file is much simpler, containing  one line per registered user,
nothing else, make sure there are no trailing spaces after the text:

----------------------------
greg:gr7mvaz6JGI6o
ycey:ycbo1tp38aET3Tk
budgie:bu/QrbVBz11Z2
----------------------------

These passwords are created using the Encode UNIX Password Windows
program, so in the first line the user name is 'greg' with password
'airplane' and it encodes to that shown.  The Windows program copies the
encoded password to the clipboard, so it may be easily pasted into the
.htpasswd file using a text editor.

Note that there's a random element to the encryption, so the same name and
password may encrypt to a different result using different programs.

For larger web sites, you may want to restrict different directories to
different users.  This is done by putting an .htaccess file in each
directory to be protected, and then having two or more password files, for
instance .htpaswd1 and .htpaswd2.  Be sure to edit the .htaccess file so
the AuthUserFile matches the correct password file.  Apache also allows
others ways of permitting groups of users to access different directories,
but that is beyond this readme.


Uploading the file to your web site
-----------------------------------

It's important that these files do not have extensions and have the correct
name.  Windows does not like files starting with . and without extensions,
so you may need to rename them on the web server after FTP'ing them, and
then FTP them back to the PC with the correct names.  It you copy the files
enclosed with this archive as templates, this should not be a problem.


Distribution
------------

Encode UNIX Password is copyrighted software, but is available without cost
and may be freely distributed via web pages, FTP sites, BBS and
conferencing systems or on CD-ROM in unaltered zip format, but no charge may
be made other than reasonable media or bandwidth cost.   Please email
Magenta Systems Ltd if you distribute Encode UNIX Password in some way, so
you can be notified of upgrades or other important changes.


Release History
---------------

Release 1.2 - corrected a problem with long user names causing word
wrapping in the encoded data window and a corrupted password list.



Other Magenta Applications
--------------------------

Magenta Systems offers various applications for Windows 95, 98 and NT 4:

'CamCollect' is designed to download, display and save images from the
many web cams available on the internet.

'DUN Manager' is designed to simplify and enhance Dial Up Networking and
Remote Access Services.

Delphi developers information and components for developers using Borland
Delphi

and Comparison Publications:

'UK Telecom Tariff Comparisons' of the residential and business telephone
tariffs charged by various operators in the United Kingdom.

'Intel Motherboard Comparisons' of the features and capabilities of the
different Pentium, Pentium II, Celeron, Pentium Pro and 486 Motherboards
sold by Intel Corporation.

Please visit the Magenta Systems web site for more information:
http://www.magsys.co.uk/


Copyright Information
---------------------

Copyright Magenta Systems Ltd, England, 2001.

Magenta Systems Ltd
9 Vincent Road
Croydon
CR0 6ED
United Kingdom

Phone 020 8656 3636, International Phone +44 20 8656 3636
Fax 020 8656 8127, International Fax +44 20 8656 8127

Email: apps@magsys.co.uk
Web: http://www.magsys.co.uk/apps/
Download: http://www.magsys.co.uk/apps/passwd12.zip

