Auth system v2 for CAMAS
------------------------

 $Id: auth_system_v2.txt,v 1.4 2003/03/19 11:59:39 kiwi Exp $

Introduction
------------

 The purpose of this document is to describe the API needed for 
Auth system v2 of CAMAS.

 This new system will be in charge of :

 (these functionalities allready exist in the v1 API)

  o give the default domain name
  o give the email address from an imap login
  o give the full names from an imap login
  o give the imap login from an email address
  o inform camas if login screen use imap login or email
    address
  o give the max quota from an imap login
  o give an interface to error messages
 
 (new functionalities)
  
  o give the imapserver hostname/ip from an imap login
  o give the imap folder defaultmailpath from an imap login
  o give the method to store preferences from an imap login (imap/ldap/sql...)
  o give the imap folder name to store preferences if method is imap
  o give the imap port used to connect to
  o give a list of folder to make uppon login

 The new required functionalities is that now the new auth subsystem
 must handle more than one module at time.


 API Implementation
 ------------------

 Required calls v1 API
 ---------------------

 * method: int version(void)

 This call return the version supported by this auth module.
 There is a the time of writting of this documentation 2 possible returns :
 1 or 2.

 coding example :

 int version() {
  return 2;	// This module support v2 api
 }

 
 * method: string|int getlogin(string login)

 This call return the imap login to be used to connect into IMAP server. 
 Or a int where there is an error.
 Note that "login" variable is what is given on CAMAS's login screen in the
 input box given 'asis'.

 The following error codes can be used :
  0 : Standard error code that can be used for unknown error type
  1 : Bad password or login
  2 : Access denied (for example when people are not allowed to acces the
                     the webmail from a location or date/time)
  3 : Account is locked (eg suspended account is a good example)
  4 : Change your password (The user cannot login until he haven't changed
                            his password on another interface...) 
 
 If you use Caudium caching system you MUST not cache any entries if you
 return an error.

 coding example :
 
 string|int getlogin(string login) {
  if (login == "john.doe") return "jdoe";
  else return 1;
 }

 * method: string|int getdnsname(void)

 This call return the dns name used in login page. This allow people
 that want to login into CAMAS webmail using their email adress without
 typing "@domain.com".

 If this function return an int, then consider that is an error.

 Following error codes can be used :
  0 : Standard error code that can be used for unknown error type
  1 : There is no domain name set, use imap login or complete email to login

 coding example :
 
 string|int getdnsname() {
   return "domain.com";
 }

 TODO: Add multiple domain choice...

 * method: int getemaillogin(void)

 This call inform CAMAS module that you need to specify email as login
 instead of IMAP login.

 Must return 1 when true, otherwise 0

 coding example :

 int getemaillogin(void) {
  return 1;	// We use email login
 }

 * method: array|int getfullnames(string login)

 This call return in a array the surname, name and email address from
 the given IMAP login (NOT the email address).

 Array format is the following :
 ({ "surname",
    "name",
    "email@domain.com" })

 Note that if this call return an int consider using the following 
 error codes :
  0 : Error (standart)
  1 : Empty set (Not used yet)

 coding example :

 array|int getfullnames(string login) {
  if (login == "jdoe" )
    return ({ "John",
              "Doe",
              "john.doe@domain.com" });
  else return 0;
 }

 * method: int getquota(string login)

 This return the diskquota of the user in bytes. If it returns 0 then quota
 is illimited. The login given is the IMAP login (not the email address).

 coding example :
 
 int getquota(string login) {
   if (login == "jdoe") 
     return 0;	// John has unlimited quota
   else
     return 5 * 1024 * 1024; // others have 5M
 }



  

 
