22 April 1999. Daniel Hellerstein (danielh@crosslink.net)

                DYNPWD: The SRE-http DYNamic PassWorD facility

1) Abstract:

SREF_DYNAMIC_PWD, which is part of SRE-http version 1.3d,
is a procedure designed to be used by SRE-http addons.
It is purpose is to provide "digest" style authentication to http/1.0 browsers 
(i.e.; Netscape 4.0 and below). As opposed to "basic" authentication, 
DYNPWD (as well as "digest" authentication) never sends a user's password 
in the clear.  Instead, a strongly encrypted version of the password is
sent, an encryption that changes from seesion to session (that is,
from day to day and from IP-address to IP-address).

This encryption does NOT extend to the contents of the request, hence
DYNPWD (as well as "digest" authentication") is not as powerful as 
SSL. Nevertheless, by keeping the password secret from prying eyes,
most "man in the middle" attacks can be prevented.

  If you are interested in encryption of responses, please see
  ENCRYPT.DOC for a description of SRE-http's encryption facility.
        
        

2) Usage:

To use SREF_DYNAMIC_PWD, you must 
 a) have version 1.3d (or above) of SRE-http
You should also have
 b) a copy of DYNPWD.RSP in the (possibly host-specific) "data directory" for
   this server  (the root of your web tree). 
   This is not strictly required -- you can specify a different "response" file.

Using DYNPWD requires two steps:
  a) grant "application specific, secret privileges" to the lucky clients.
     For example, since the MANAGER addon can use SREF_DYNAMIC_PWD,
     you might have:
        user = DAN
        password= THEMAN
     and a privset= PRIV1 ?MANAGER:doxfiles
     
    Note the use of the ?MANAGER:xxxx syntax: the ? signals that this is
    a "secret privilege", and the MANAGER: means "this privilege is
    for use by the MANAGER addon.

    The substring fallowing the ?appname: (for example, "doxfiles")
    is the "shared secret" for the appname addon.


  b) Write an appication that requires dynamic passwords. This is 
     actually quite easy, it just requires one call to SREF_DYNAMIC_PWD.


  c) Optional -- customize DYNPWD.RSP. This is strictly optional -- the
                 generic version of DYNPWD.RSP should work without
                 any modification.

2) Syntax of SREF_DYNAMIC_PWD

To enable dynamic passwords, you must write an "sre-http" addon that
calls the SREF_DYNAMIC_PWD procedure (SREF_DYNAMIC_PWD is loaded 
into macrospace when needed).  

The calling syntax for SREF_DYNAMIC_PWD is:
  res=sref_dynamic_pwd(appname,newlocation,privset2,duration,respfile,clientaddr)
where
  appname: recommended. the "application" calling this. Used to identify 
           a "shared secret". If not specified, a value DYNPWD is used.
           Note that APPNAME is also used in responses.
  newlocation: recommended. The uri to invoke when client hits the submit
               button. Default value is "/"
  privset2 : REQUIRED. the space delimited list of "secret" privileges. 
             It should contain an entry of the form APPNAME:shared_secret
  duration: optional. duration of a timestamp, in days (and fractions of day)
             (default value is 1 day)
  respfile: optional.the "response file" containing the md5 procedure. If not
            specified, DYNPWD.RSP, in the datadir(), is used.
  clientaddr: client's numeric ip address. Optional, if missing, will get if
            with a GOSERVE extract 
and
  resp='' 
         if a valid password is found
or 
  resp='200 '||length(response) 
        if no valid password is found, 
        sref_dynamic_pwd asks the client to supply one -- this is the
        response code for this "response"


Thus, if SREF_DYNAMIC_PWD returns a '', the client is legit. If
it returns anything else, then SREF_DYNAMIC_PWD has sent a "please
enter password" response, and has closed the connection.

3) Notes

  * For an example of SREF_DYNAMIC_PWD, see the SRE-http "MANAGER" addon.

  * For further discussion of "secret privileges", see the SRE-http manual,
    or the USERS.IN file that comes with SRE-http.

  * The "privset" argument (to SRE-http addons) is divided into
    two sections: the "public" privileges (that may be reported
    by the STATUS, and other, addons), and the "secret" privileges
    (that should NEVER be reported by any SRE-http addon).
    To obtain them, use:
      parse var privset privset_public ',' privset_secret