root/trunk/doc/authentication.txt

====================
Using Authentication
====================

----------------
Module: mod_auth
----------------

:Author: Jan Kneschke
:Date: $Date$
:Revision: $Revision$

:abstract:
  The auth module provides ...
  
.. meta::
  :keywords: lighttpd, authentication
  
.. contents:: Table of Contents

Description
===========

Supported Methods
-----------------

lighttpd supportes both authentication method described by 
RFC 2617: 

basic
`````

The Basic method transfers the username and the password in 
cleartext over the network (base64 encoded) and might result 
in security problems if not used in conjunction with a crypted 
channel between client and server.

digest
``````

The Digest method only transfers a hashed value over the 
network which performs a lot of work to harden the 
authentication process in insecure networks.

Backends
--------

Depending on the method lighttpd provides various way to store 
the credentials used for the authentication.

for basic auth:

- plain_
- htpasswd_ 
- htdigest_
- ldap_
  
for digest auth:

- plain_
- htdigest_
  

plain
`````

A file which contains username and the cleartext password 
seperated by a colon. Each entry is terminated by a single 
newline.::

  e.g.:
  agent007:secret
  

htpasswd
````````

A file which contains username and the crypt()'ed password 
seperated by a colon. Each entry is terminated by a single 
newline. ::

  e.g.:
  agent007:XWY5JwrAVBXsQ

You can use htpasswd from the apache distribution to manage 
those files. ::
  
  $ htpasswd lighttpd.user.htpasswd agent007
  
  
htdigest
````````

A file which contains username, realm and the md5()'ed 
password seperated by a colon. Each entry is terminated 
by a single newline. ::
  
  e.g.:
  agent007:download area:8364d0044ef57b3defcfa141e8f77b65
  
You can use htdigest from the apache distribution to manage 
those files. ::

  $ htdigest lighttpd.user.htdigest 'download area' agent007
  
Using md5sum can also generate the password-hash: ::

  #!/bin/sh
  user=$1
  realm=$2
  pass=$3

  hash=`echo -n "$user:$realm:$pass" | md5sum | cut -b -32`

  echo "$user:$realm:$hash"

To use it:

  $ htdigest.sh 'agent007' 'download area' 'secret'
  agent007:download area:8364d0044ef57b3defcfa141e8f77b65
  
  
  
ldap
````

the ldap backend is basically performing the following steps 
to authenticate a user
  
1. connect anonymously  (at plugin init)
2. get DN for filter = username
3. auth against ldap server
4. disconnect
   
if all 4 steps are performed without any error the user is 
authenticated

Configuration
=============

::

  ## debugging
  # 0 for off, 1 for 'auth-ok' messages, 2 for verbose debugging
  auth.debug                 = 0
  
  ## type of backend 
  # plain, htpasswd, ldap or htdigest
  auth.backend               = "htpasswd"

  # filename of the password storage for 
  # plain
  auth.backend.plain.userfile = "lighttpd-plain.user"
  
  ## for htpasswd
  auth.backend.htpasswd.userfile = "lighttpd-htpasswd.user"
  
  ## for htdigest
  auth.backend.htdigest.userfile = "lighttpd-htdigest.user"

  ## for ldap
  # the $ in auth.backend.ldap.filter is replaced by the 
  # 'username' from the login dialog
  auth.backend.ldap.hostname = "localhost"
  auth.backend.ldap.base-dn  = "dc=my-domain,dc=com"
  auth.backend.ldap.filter   = "(uid=$)"
  # if enabled, startTLS needs a valid (base64-encoded) CA 
  # certificate
  auth.backend.ldap.starttls   = "enable"
  auth.backend.ldap.ca-file   = "/etc/CAcertificate.pem"
  # if server performs client certificates validation we can 
  # connect using user defined client certificates
  auth.backend.ldap.cert      = "/etc/cert.pem"
  auth.backend.ldap.key       = "/etc/req.pem"

  ## restrictions
  # set restrictions:
  #
  # ( <left-part-of-the-url> =>
  #   ( "method" => "digest"/"basic",
  #     "realm" => <realm>,
  #     "require" => "user=<username>" )
  # )
  #
  # <realm> is a string to display in the dialog 
  #         presented to the user and is also used for the 
  #         digest-algorithm and has to match the realm in the 
  #         htdigest file (if used)
  #

  auth.require = ( "/download/" => 
                   ( 
                     "method"  => "digest",
                     "realm"   => "download archiv",
                     "require" => "user=agent007|user=agent008"
                   ),
                   "/server-info" => 
                   ( 
                     "method"  => "digest",
                     "realm"   => "download archiv",
                     "require" => "valid-user"
                   )
                 )

Limitations
============

- The implementation of digest method is currently not 
  completely compliant with the standard as it still allows
  a replay attack.