http_authenticate.pl -- Authenticate HTTP connections using 401 headers

This module provides the basics to validate an HTTP Authorization header. User and password information are read from a Unix/Apache compatible password file.

This library provides, in addition to the HTTP authentication, predicates to read and write password files.

 http_authenticate(+Type, +Request, -Fields)

True if Request contains the information to continue according to Type. Type identifies the required authentication technique:

basic(+PasswordFile)

Use HTTP Basic authetication and verify the password from PasswordFile. PasswordFile is a file holding usernames and passwords in a format compatible to Unix and Apache. Each line is record with : separated fields. The first field is the username and the second the password hash. Password hashes are validated using crypt/2.

Successful authorization is cached for 60 seconds to avoid overhead of decoding and lookup of the user and password data.

http_authenticate/3 just validates the header. If authorization is not provided the browser must be challenged, in response to which it normally opens a user-password dialogue. Example code realising this is below. The exception causes the HTTP wrapper code to generate an HTTP 401 reply.

(   http_authenticate(basic(passwd), Request, Fields)
->  true
;   throw(http_reply(authorise(basic, Realm)))
).

Arguments:

Fields

- is a list of fields from the password-file entry. The first element is the user. The hash is skipped.

To be done

- Should we also cache failures to reduce the risc of DoS attacks?

 http_authorization_data(+AuthorizeText, ?Data) is semidet

Decode the HTTP Authorization header. Data is a term

Method(User, Password)

where Method is the (downcased) authorization method (typically basic), User is an atom holding the user name and Password is a list of codes holding the password

 cached_authenticated(+Authorization, +File, -User, -RestFields)[private]

Validate using the cache. If the entry is not in the cache, we also remove all outdated entries from the cache.

 validate(+File, +User, +Passwd, -Fields)[private]

True if User and Passwd combination appears in File. File uses the same format as .htaccess files from Apache or Unix password files. I.e. it consists of one line per entry with fields separated by :. The first field is the User field, The second contains the Passwd in DES or MD5 encrypted format. See crypt/2 for details.

 http_current_user(+File, ?User, ?Fields) is nondet

True when User is present in the htpasswd file File and Fields provides the additional fields.

Arguments:

Fields

- are the fields from the password file File, converted using name/2, which means that numeric values are passed as numbers and other fields as atoms. The password hash is the first element of Fields and is a string.

 update_passwd(+File, -Path) is det[private]

Update passwd/3 to reflect the correct passwords for File. Path is the absolute path for File.

 http_read_passwd_file(+Path, -Data) is det

Read a password file. Data is a list of terms of the format below, where User is an atom identifying the user, Hash is a string containing the salted password hash and Fields contain additional fields. The string value of each field is converted using name/2 to either a number or an atom.

passwd(User, Hash, Fields)

 http_write_passwd_file(+File, +Data:list) is det

Write password data Data to File. Data is a list of entries as below. See http_read_passwd_file/2 for details.

passwd(User, Hash, Fields)

To be done

- Write to a new file and atomically replace the old one.

 http:authenticate(+AuthData, +Request, -Fields)[multifile]

Plugin for library(http_dispatch) to perform basic HTTP authentication.

This predicate throws http_reply(authorise(basic, Realm)).

Arguments:

AuthData	- must be a term basic(File, Realm)
Request	- is the HTTP request
Fields	- describes the authenticated user with the option user(User) and with the option user_details(Fields) if the password file contains additional fields after the user and password.