Documentation for data/passwd and UserInfo
AweMUD Next Generation
Copyright (C) 2003  AwesomePlay Productions, Inc.
Sean Middleditch <elanthis@awemud.net>
-------------------------------------------------

1. Introduction
   ============

   AweMUD stores information on users in a special database.  The information
   in this database includes username, password, the user's real-life name,
   the user's e-mail address, and special "flags" on the user (such as
   privileges).

2. File Format
   ===========

   The file format of the user database is, by default, a flat text file.
   The syntax/structure of this file resembles the /etc/passwd file found on
   most UNIX systems.

   Each line corresponds to one user.  The line is comprised of fields, each
   field separate by a : (colon).  The data in the fields themselves cannot,
   thus, contain a colon.

   The first field is the user's name.  The second is the encrypted (MD5)
   passphrase.  Following that is the real-life name.  Then the e-mail
   address.  Finally, the flags follow.

   Ex:
     tester:$1$34lkjafas4:John Doe:john@test.er:BG

   The fields are as follows:
     1- username: tester
     2- passphrase: $1$34lkjafas4
     3- realname: John Doe
     4- email: john@test.er
     5- flags: BG

   The flags are simply one-letter indicators for a given state.  The flags
   may be empty.  Example flags are A (administrator), B (builder), and G
   (gamemaster).

3. UserInfo API
   ============

   The API for reading and manipulating the passwd database is very simple.
   Operations will require a UserInfo object to work on.  The UserInfo class
   contains the data members for each entry in the passwd database, along with
   corresponding accessor and manipulation methods.  There is also one static
   method you will be interested in: UserInfo::lookup().

   int UserInfo::lookup(const string& name, UserInfo& ui);

     name: Name of the entry to lookup.
     ui: Object to store result in.

     return: 0 on success, -1 on error.  (may indicate a system error, or that
       the requested entry does not exist in the database.)

   In order to lookup an entry, you would use code as the following:

     UserInfo ui;

     if (UserInfo::lookup("username", ui) != 0) {
        error(...);
     }

   Manipulating a UserInfo object is easy.  There are both getter and setter
   methods for username, realname, and email.  (ex: get_username(),
   set_realname().)

   Flags make use of the methods:
   
     bool UserInfo::has_flag(char flag);
     void UserInfo::add_flag(char flag);
     void userInfo::rem_flag(char flag);

   In all cases, flag is the ASCII character representation of the flag you
   wish to set.  If you try to add a flag that is already set, the flag will
   not be added twice.

   Passwords cannot be accessed using simple accessor methods.  You must use
   the check_passphrase() and set_passphrase() methods.

     bool UserInfo::check_passphrase(const string& checkpass);
     void UserInfo::set_passphrase(const string& newpass);

   check_passphrase() will return true if the supplied argument, checkpass,
   is equal to the password.  You should pass in the argument plaintext; the
   method will deal with the encryption.

   set_passphrase(), likewise, will deal with the encryption on its own.  Do
   not encrypt the new passphrase on your own; pass in the plain-text
   passphrase.

   Once you are finished modifying a UserInfo object to your liking (either
   on an object initialized using lookup(), or by creating your own from
   scratch), you must save the object back into the passwd database.

     int UserInfo::save(void);

   Non-zero will be returned on failure, which should only occur from a sytem
   error.

4. Backends
   ========

   The UserInfo API wholly abstracts the backend.  It is possible to modify
   the core code of the UserInfo class to utilize a different backend, such
   as the Berkeley DB, SQL, or other database system.

   The UserInfo class provides the static methods initdb() and closedb().
   These methods are noops for the text passwd DB, as no initialization or
   shutdown are needed.  These can be used by other backends if needed.

   By utilizing the UserInfo API for other backends, you will never need to
   rewrite any other code in AweMUD - you can merely drop in a new
   src/userdb.cc to utilize a new backend for the passwd db.
