Beesnest/DcLoginManager.h

Go to the documentation of this file.

/*
Copyright 2007 Erez Bibi (erezbibi@users.sourceforge.net)
This file is part of Beesnest.

Beesnest is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Beesnest is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Beesnest; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

/* DcLoginManager.h: interface for the CdcLoginManager class. */

#ifndef __CDC_LOGIN_MANAGER
#define __CDC_LOGIN_MANAGER

#include "DcGlobals.h"
#include "DcRequest.h"
#include "DcResponse.h"
#include "DcHttpTime.h"
#include "DcUserStatus.h"
#include _GET_INCLUDE_PATH (DcCrypto.h)
#include _GET_INCLUDE_PATH (DcMutex.h)
#include _GET_INCLUDE_PATH (DcSemaphore.h)
#include _GET_INCLUDE_PATH (DcThread.h)

typedef CdcString t_code_type;  /* The one-time random code type. */

/* Names... */
/* For built-in after first login. */
#define DC_USER_ID      "BN_UserID"         /* User ID. */
#define DC_USER_CODE    "BN_RndCode"        /* User one-time random code. */
#define DC_LOGIN_MSG    "BN_LoginMsg"       /* Friendly login message. */

/* For challenge response - built-in or DAA. */
#define DC_USER_NAME    "BN_Username"       /* User Name. */
#define DC_URL          "BN_OrigURL"        /* Original requested URL. */
#define DC_REALM        "BN_Realm"          /* Group of protection. */
#define DC_NONCE        "BN_Nonce"          /* Server nonce. */
#define DC_OPAQUE       "BN_Opaque"         /* Server other random code. */
#define DC_CNONCE       "BN_Cnonce"         /* Client nonce. */
#define DC_NC           "BN_NC"             /* Nonce Counter. */
#define DC_RESPONSE     "BN_Response"       /* Client Response. */

#define DC_LOGOUT       "BN_Logout" /* user set it to "yes" in order to logout. */

/* Return valuse from the login manager. */
#define DC_LM_NONE      0   /* no access restriction. */
#define DC_LM_OK        1   /* access is granted. */
#define DC_LM_SEND      2   /* need to send other (login/deny) page to user. */

#define DC_CHL_STL_ADD  2   /* Wait a few more sec before delete stale challenge. */

/**
 * The Log-in Manager class is a <b>static</b> class that deals with the login of
 * users to the system. The logging process can be done in two ways. One is the
 * RFC 2617 Digest Access Authentication (DAA) login process, and the other is
 * a server built-in login system. In addition both ways can be combined. <br>
 * A note should be made that the built-in login system is secure just if it is
 * working with SSL (or some other) encryption of the communication between the
 * server and the client. For full discussion of the login system see the
 * Login System document.
 * <p>
 * The server has a list of protected folders or files, in the Login-Manager
 * configuration part of the configuration files. Every file or folder that has
 * been set to be protected, belongs to some group of users. <br>
 * The groups list and their users are also listed in this section of the
 * configuration files (as a tree). Each group is an entry in the configuration
 * file, and under this entry you should write the users that belong to the
 * group or other groups names. <br>
 * The names of the login page, access-denied page and the name of the file
 * of user-names and passwords, are also set in this configuration section.
 * <p>
 * The Digest Access Authentication (DAA): In every request (or include) of a
 * protected file, the server will look for the "Authorization" header in the
 * request. If it finds this header it will test it against the user password.
 * If the server does not find this header it will send 401 response with a
 * WWW-Authenticate header that includes all the needed data for the client to
 * log in (the challenge). If the server did find the Authorization header, but
 * the challenge for this response was too old (stale) it will add a
 * "stale=true" to the challenge, so the user agent does not need to ask for
 * the password again. See RFC 2617 for full details.
 * <p>
 * The built-in login process starts in a similar way. The server send the exact
 * same challenge to the client, not in a header of 401 response, but embedded
 * in a special login HTML web page. the user enter his user-name and password
 * to an HTML form, then a (Javascript) calculation of the response should be
 * made on the client side, and the the same response of a DAA process should be
 * sent back as HTML request variables. <br>
 * After the first log-in the server will maintain one-time random code for this
 * user. This code will go back and forth between the server and the client
 * (different code each time), and as long as the client knows the correct code,
 * this user stays logged in. This process is what needs SSL for full security,
 * as the random code is passed in the open. (With the random code the server
 * sends the user an ID as well, so it can keep track of more then one user at
 * one time.<br>
 * Note that this login process require the use of some scripting language to
 * embed the challenge parameters in the HTML page.
 * <p>
 * There is an option to combine the two methods, and use the DAA process in the
 * beginning (so the user get the nice message box from the browser), but then
 * use the one-time code method. This will save the need of a login page with
 * complected Javascript, but will be more efficient than the full DAA process.
 * <p>
 * The way to tell the server which login method to use is by setting the name
 * (and path) of the login page in the Login-Manager configuration section. if
 * this file is missing the server will use DAA. <br>
 * Some other configuration options are: <br>
 * The Auto-Cookie parameter, if sets to "yes" will tell the server to insert
 * the one-time code and user ID to a cookie response header, every time they
 * exists, without the use of some scripting language. The Stale parameter will
 * set the time in seconds for a challenge to be valid and the Expire parameter
 * will set the time for a deletion of a challenge if it is not get any recent
 * response. In addition there should be a name (and path) of a deny page, if a
 * user is logged in but cannot see a certain page because he is not belong to
 * the correct group. If an access to a page is denied, the class will change
 * the page to the "Access Denied" page, You can still transfer the User Code
 * and User ID in this page so the user will not be logged out.
 * <p>
 * This class starts a lower priority thread to keep the challenges list clean
 * of old challenges. It signals this thread to scan the list after marking any
 * challenge for deletion, and after logging out a user (see somewhat long
 * explanation in the DcClean function).
 *
 * <p>
 * @author Erez Bibi
 * @version 2.0
 */
class CdcLoginManager
{
private:
    /**
     * This is basically a struct to hold the challenges this class sends to
     * users. The challenge is standard Digest Access Authentication challenge.
     * See RFC 2617.
     */
    class CdcDaaChallenge
    {
    public:
        CdcString sRealm;       /* Identify the group this challenge is for. */
        CdcString sNonce;       /* Nonce For this challenge. */
        CdcString sOpaque;      /* This string just goes to the client and back as is. */
        int nNC;                /* Counter for the response (prevent replay attack). */
        CdcHttpTime oBuildTime; /* The time when this challenge was created. */
        bool isForDelete;       /* Flag to mark this challenge for deletion
                                    (but we can still use it for a while). */
        bool isCanceld;         /* This is another flag to mark challenge as void. */
    };

    /**
     * This is a struct to hold the response we got from the user.
     * The response is standard Digest Access Authentication response.
     * See RFC 2617.
     */
    class CdcDaaResponse
    {
    public:
        CdcString sUsername;    /* The username. */
        CdcString sRealm;       /* Identify the group this response is for. */
        CdcString sNonce;       /* Nonce Form the challenge. */
        CdcString sOpaque;      /* This string that get back as is. */
        CdcString sURL;         /* The requested URL. */
        CdcString sMethod;      /* The request method. */
        CdcString sQOP;         /* Quality of Protection. */
        CdcString sCnonce;      /* Client nonce. */
        CdcString sResponse;    /* The response. */
        CdcString sNC;          /* Response counter as string */
    };

    /**
     * CdcUser holds information of one user in the system. Its holds the
     * user-name, password, random code and a pointer to the user status object.
     * The class can write itself to a binary file, and create itself from a file.
     */
    class CdcUser
    {
    private:
        /** The user name. */
        CdcString sUsername;
        /** The user password. */
        CdcString sPassword;
        /** One time random code (for the built in login system). */
        t_code_type nCode;
        /** The last used code (for multithread requests) . */
        t_code_type nLastCode;
        /** Pointer to the user status object. */
        CdcUserStatus oStatus;
        /** True when the user is logged in. */
        bool isLogedin;
        /** Mutex for this user. */
        CdcMutex oMutex;
        /** The IP this user logged in from. */
        CdcString sLoginIP;
        /** The time of last good (random code) login. */
        CdcHttpTime tLastLogin;

    public:
        /** Direct constructor and default constructor. */
        CdcUser (const CdcString& name = EMPTY_STR,
            const CdcString& pass = EMPTY_STR)
            : sUsername (name), sPassword (pass), nCode (EMPTY_STR),
            isLogedin (false) {}

        /** Constructor from a file. */
        CdcUser (ifstream& inf);

        /** Write object to a file. */
        bool WriteToFile (ofstream& outf);

        /* Sets and gets functions. */
        CdcString GetUsername ()
        { oMutex.Lock (); CdcString temp = sUsername; oMutex.Unlock (); return temp;}

        void SetUsername (const CdcString& name)
        { oMutex.Lock (); sUsername = name; oMutex.Unlock (); }

        CdcString GetPassword ()
        { oMutex.Lock (); CdcString temp = sPassword; oMutex.Unlock (); return temp;}

        void SetPassword (const CdcString& pass)
        { oMutex.Lock (); sPassword = pass; oMutex.Unlock (); }

        CdcUserStatus* GetStatusObject ()
        { oMutex.Lock (); CdcUserStatus* temp = &oStatus; oMutex.Unlock (); return temp;}

        //void SetStatusObject (CdcUserStatus* pointer)
        //{ oMutex.Lock (); if (pStatus) delete pStatus; pStatus = pointer; oMutex.Unlock (); }

        t_code_type GetCode ()
        { oMutex.Lock (); t_code_type temp = nCode; oMutex.Unlock (); return temp;}

        t_code_type GetLastCode ()
        { oMutex.Lock (); t_code_type temp = nLastCode; oMutex.Unlock (); return temp;}

        void SetCode (t_code_type code)
        { oMutex.Lock (); nLastCode = nCode; nCode = code;
            tLastLogin = CdcHttpTime::GetCurrentTime (); oMutex.Unlock (); }

        CdcHttpTime GetLastLoginTime ()
        { oMutex.Lock (); CdcHttpTime temp = tLastLogin; oMutex.Unlock (); return temp;}

        bool IsLogedin ()
        { oMutex.Lock (); bool temp = isLogedin; oMutex.Unlock (); return temp;}

        void Logedin (bool yes)
        { oMutex.Lock (); isLogedin = yes; oMutex.Unlock (); }

        void SetIP (const CdcString& ip)
        { oMutex.Lock (); sLoginIP = ip; oMutex.Unlock (); }

        CdcString GetIP ()
        { oMutex.Lock (); CdcString temp = sLoginIP; oMutex.Unlock (); return temp;}
    };


    typedef vector <CdcUser*> t_users_vector;
    typedef map <CdcString, CdcDaaChallenge*> t_challenges_map;


    /** The vector of users. */
    static  t_users_vector vUsers;

    /** The map of sent challenges. */
    static t_challenges_map mChallenges;

    /** The Mutex for this map. */
    static CdcMutex oMapMutex;

    /** The name of the login HTML file (const). */
    static CdcString sLoginFileName;

    /** The name of the deny access HTML file (const).*/
    static CdcString sDenyFileName;

    /** True if the login page is empty - using DAA (const). */
    static bool bBuiltInLogin;

    /** True if need to insert ID and Random Code cookie automatically (const). */
    static bool bAutoCookie;

    /** Time limit for a nonce to become stale (const). */
    static int nStaleNonce;

    /** Time limit for a used nonce to expire (const). */
    static int nExpireNonce;

    /** Time that an old one-time-code is still good, for multithread request of
        protected resources (from the same page). */
    static int nOldCodeValid;

    /** This object holds the cleaning thread. */
    static CdcThread oCleanThread;
    /** Semaphore to trigger the cleaning thread. */
    static CdcSemaphore oStartThread;
    /** Flag for the thread to exit. */
    static bool isCleanThreadGo;
    /** Counter of taken challenges. */
    static volatile int nSomeChalTaken;
    /* See explanation for these 4 vars in DcClean function. */

    /** There is no constructor (static class). */
    CdcLoginManager () {}

    /**
     * Clean stale, void and old challenges. It is been called from DcClean that
     * runs in a separate thread. See DcClean for full explanation.
     */
    static void Clean ();

    /**
     * Make the operation to set a user as logged in. It inserts the random code
     * and user ID as variables in the request object if using the built-in
     * method. It inserts these variables as cookies if the Auto Cookies is set
     * (even if we are using DAA).
     * <p>
     * @param id The ID of the user to log in (index in the vector).
     * @param req Reference to the request object.
     * @param res Reference to the response object.
     */
    static void LoginUser (int id, CdcRequest& req, CdcResponse& res);

    /**
     * Insert a new random code to a cookie or request variable, if we are using
     * random codes. In addition this sets the user ID as a cookie or request
     * variable. Note that in some cases setting the user ID is redundant.
     * <p>
     * @param id The ID of the user to log in (index in the vector).
     * @param req Reference to the request object.
     * @param res Reference to the response object.
     */
    static void SetRandCode (int id, CdcRequest& req, CdcResponse& res);

    /**
     * Log out a user, cleans its object and erases login variables from the
     * request. If Auto Cookies is set, it erases the login cookies as well.
     * <p>
     * @param req Reference to the request object.
     * @param res Reference to the response object.
     */
    static void LogoutUser (CdcRequest& req, CdcResponse& res);

    /**
     * This function checks the response arrived from the client.
     * This is the function that implements the Digest Access Authentication
     * algorithm. I use it in both login methods. For the built-in just once,
     * when the user logs in, for DAA I call this function before sending any
     * protected page. See RFC 2617.
     * <p>
     * @param id The ID of this user.
     * @param DaaRes Reference to a Digest access authentication response.
     * @param stale Reference to bool, set to True if DAA response is stale.
     * @param wrong Reference to bool, set to True if Username/Password is wrong.
     * @return (bool) True if the response is correct.
     */
    static bool CheckResponse (int id, const CdcDaaResponse& DaaRes,
        bool& stale, bool& wrong);

    /**
     * This function checks the one time random code from the client (built-in
     * method)
     * <p>
     * @param id The ID of this user.
     * @param req Reference to the request object.
     * @param res Reference to the response object.
     * @return (bool) True if the code is correct.
     */
    static bool CheckCode (int id, CdcRequest& req, CdcResponse& res);

    /**
     * This function checks if a user is under a group. It checks it by asking
     * the parameters class.
     * <p>
     * @param The ID of the user (place in the vector).
     * @param The name of the group the user should be in.
     * @return (bool) True if the user is in this group.
     */
    static bool CheckGroupAccess (int id, const CdcString& group);

    /**
     * This function prepares a login page. First it generates a new challenge.
     * Then it either just inserts the challenge variables to the request
     * object variables map, and from there they will go to the login page
     * using a script. Or if we are using DAA, it adds an WWW-Authenticate
     * header to the response, and changes the response value to 401. In any way,
     * the ConncetionThread class will clear the previous buffer to send to the
     * client, and either send an empty buffer (DAA) or send the login page.
     * <p>
     * @param req Reference to the request object.
     * @param res Reference to the response object.
     * @param stale True if DAA nonce was stale.
     */
    static void BuildLoginPage (CdcRequest& req, CdcResponse& res, bool stale);

    /**
     * Find the ID (index in a vector) of the user that sent this request.
     * If the ID cannot be found, or if it is wrong - the function returns -1.
     * In addition, the function tries to find if a DAA request was made.
     * Note: This function returns 3 variables and an object.
     * <p>
     * @param req Reference to the request object.
     * @param DaaRes [output] This is a reference to an empty DAA Response
     *  object. The function will fill this object if some kind of response
     *  exists (DAA or built-in).
     * @param isRes [output] The function will set this reference to True if it
     *  finds a response to a challenge.
     * @param isVar [output] The function will set this reference to True if it
     *  finds the user ID in a request variable.
     * @return (int) The ID of the user or -1.
     */
    static int GetUserID (const CdcRequest& req, CdcDaaResponse& DaaRes,
                          bool& isRes, bool& isVar);

    /**
     * This function will try to fill a DAA response object from the HTTP
     * request variables. This is the response that came from a built-in login
     * page.
     * <p>
     * @param req Reference to the request object.
     * @param DaaRes Reference to the DAA response object to fill.
     * @return True if it finds the response nonce field (and then probably the
     *  entire DAA response is there).
     */
    static bool BuildResFromVar (const CdcRequest& req, CdcDaaResponse& DaaRes);

    /**
     * This function will try to fill DAA response object from the HTTP request
     * Authorization header. This is the response that came from a Digest Access
     * Authentication system.
     * <p>
     * @param req Reference to the request object.
     * @param DaaRes Reference to the DAA response object to fill.
     * @return True if it found the response Authorization header.
     */
    static bool BuildResFromHeader (const CdcRequest& req, CdcDaaResponse& DaaRes);


    /**
     * Find an ID of a user by searching the database for the username.
     * <p>
     * @param username The username to search for.
     * @return (int) The ID of the user or -1.
     */
    static int FindUser (const CdcString& username);

    /**
     * Find a property value in a request header field, by a property name.
     * <p>
     * @param name The property name.
     * @param head The header to check as CdcString.
     * @return (CdcString) the property value or empty string if not
     * found.
     */
    static CdcString GetProp (const CdcString& name, const CdcString& head);

public:
    /**
     * This function loads the users database to memory, and initialize some
     * cryptographic features, and configuration variables.
     * <p>
     * @param file_name The name of the users database file.
     * @throw (CdcException) If cannot open database file, or cannot allocate
     * memory.
     */
    static void Load (const char* file_name);

    /**
     * This function saves the users database to a file.
     * <p>
     * @param file_name The name of the users database file.
     * @throw (CdcException) If cannot open database file.
     */
    static void Save (const char* file_name);

    /**
     * This is the main function of this class. it checks if the user is under
     * a certain group, and knows the correct password. (see the description in
     * the class description).
     * <p>
     * @param group The group name this page is protected by.
     * @param req Reference to the request object.
     * @param res Reference to the response object.
     * @param ret_code [output] A return code that can be:
     *  DC_LM_OK    if access is granted
     *  DC_LM_NONE  if the group name was empty.
     *  DC_LM_SEND  if need to send to user other (login/deny/DAA 401) page.
     * @param new_page If ret_code is DC_LM_SEND, new_page will get the relative
     *  path to the new page to send (or will be empty in DAA method), otherwise
     * it remains untouched.
     * @return (CdcUserStatus*) Pointer to the user status object or NULL.
     */
    static CdcUserStatus* CheckAccess (const CdcString& group, CdcRequest& req,
                                         CdcResponse& res, int& ret_code,
                                         CdcString& new_page);

    /**
     * This function should be called by CdcConnectionThread before starting
     * to create any response page. It checks if the user asked to be logged out,
     * and if so logged him out.
     * <p>
     * @param req Reference to the request object.
     * @param res Reference to the response object.
     * @return (bool) True if user logged out.
     */
    static bool CheckLogout (CdcRequest& req, CdcResponse& res);

    /**
     * Function to add a user to the class users database.
     * <p>
     * @param username The new username.
     * @param password The new password.
     * @return (bool) True if the new user added successfully.
     * @throw (CdcException) Out of memory exception.
     */
    static bool AddUser (const CdcString& username,
        const CdcString& password);

    /**
     * Function to change a user password.
     * <p>
     * @param username The username of the user.
     * @param old_password The old password (for identification).
     * @param new_password The new password.
     * @return (bool) True if the password has been changed successfully.
     */
    static bool ChangePassword (const CdcString& username,
        const CdcString& old_password, const CdcString new_password);

    /**
     * Function to remove users from the class database.
     * <p>
     * @param username The username of the user to remove.
     * @param password The password of the user to remove.
     * @return (bool) True if the user was removed successfully.
     */
    static bool RemoveUser (const CdcString& username,
        const CdcString& password);

    /**
     * Global function for the cleaning thread (runs in infinite loop).
     * <p>
     * The problem with the cleaning system is that the function CheckResponse
     * can be called many times from many different threads, as if using DAA,
     * this is the function that check access before sending any protected page.
     * In addition the running time of this function is some what long as this
     * is the function that do the response digest calculation on the server
     * side. <br>
     * If the cleaning thread will delete a taken challenge, the system will
     * crush. On the other hand, I don't want to lock the Mutex for the entire
     * running time of this function, because then it will mutilate other
     * CheckResponse functions that needs to run in other threads. There is no
     * reason way these functions cannot run in the same time. <br>
     * To solve this problem I use "Taken Challenges" global counter. When
     * CheckResponse is called it increases this counter by one, and waits on
     * the Mutex. After getting the Mutex it releases it immediately and start
     * working. When it is done, it decreases the counter by one. Every time a
     * challenge needs to be deleted, a semaphore is signaled (just before
     * CheckResponse returns). <br>
     * The cleaning thread waits on this semaphore. After getting a signal, it
     * sleeps for few seconds (from other reasons - the invalid challenge can
     * still be used by the browser, if it is a multi-frame page). After the
     * delay the thread calls the cleaning function. The cleaning function
     * checks first if the counter value is zero, if not it exits immediately.
     * If the counter is zero, it iterates through the challenges list and clean
     * every challenge that is marked for deletion, and old unused challenges.
     * in the beginning of every iteration cycle, it checks the counter again,
     * if it is not zero, it exits immediately, so CheckResponse can start
     * working. The uncleared challenges will have to wait for the next signal
     * on the semaphore.
     * <p>
     * @param pParam Pointer to bool (isCleanThreadGo) that tell the function to
     *  exit (close the thread).
     * @return (int) The return code from the thread.
     */
    friend int DcClean (void* pParam);
};

#endif /* __CDC_LOGIN_MANAGER */