srv-users.h

Go to the documentation of this file.
00001 /*
00002  * srv-users.h
00003  *
00004  * Copyright (C) 2008,2009  Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  * Server-side user management. 
00031  */
00032 
00033 #ifndef AESOP_SRV_USERS_H__
00034 #define AESOP_SRV_USERS_H__
00035 
00036 // includes --------------------------------------------------------------------
00037 #include "aesop-proto/protocol.h"
00038 
00039 
00040 // forward declarations
00041 class Datahash;
00042 
00043 
00044 namespace aesop {
00045 
00046 
00047 /// \ingroup aesop_srv
00048 /*@{*/
00049 
00050 
00051 /// \defgroup aesop_users Users and User Management
00052 ///
00053 /// See the aesop::UserManager class for documentation.
00054 /*@{*/
00055 
00056 
00057 /// This class is threadsafe!  In general, these methods are unsafe to call from
00058 /// the main server execution thread, because they can take a long time (disk
00059 /// read/writes and other operations).  So it is recommended to only use this
00060 /// object from worker threads!
00061 ///
00062 /// Particular APIs may be suitable for use by the main thread, and if so, they
00063 /// will note that.
00064 ///
00065 /// All APIs end in TS to denote threadsafe.
00066 ///
00067 /// All APIs are also idempotent.
00068 ///
00069 /// At the moment, a User is not a rich type, but is really just a username with
00070 /// a few properties (password, isAdmin).  If user data expands, User may be
00071 /// pulled out into a real class.
00072 ///
00073 /// A note on terminology:
00074 ///  - \b user: A user is an account registered in the local aesop user
00075 ///             directory.
00076 ///  - \b player: A player is a person actually playing the game.  Typically
00077 ///             a player logs into a user account (or creates one and then
00078 ///             logs into it).  In general, there can be \b multiple players
00079 ///             all sharing the same user account.
00080 ///
00081 /// See also \ref rules_players
00082 ///
00083 ///
00084 /// \n
00085 /// \b Database
00086 /// \n
00087 /// The User database is very simple: it is a directory on the server!  The
00088 /// server admin can pick whatever directory they'd like.  It should be read and
00089 /// write-able by the account that is running the aesop server.  The user
00090 /// directory can be used for all games hosted on the server, or the admin can
00091 /// create different user directories for each game, it is up to them.
00092 ///
00093 /// Every user has their own file in the directory, of the form
00094 /// "[username].user".  So it is easy to see who all the users are just by
00095 /// performing a directory listing.
00096 ///
00097 /// At the moment, usernames must be 3-15 characters in length, all lowercase.
00098 /// Only characters in the range 'a' - 'z' are allowed.
00099 /// Numbers or spaces are not legal, for example.  User files not meeting
00100 /// this restriction will be ignored.
00101 ///
00102 /// There is a special file in the directory named "user-db.config".  This is
00103 /// the configuration file for the user database, and it contains important
00104 /// policy settings.  Two in particular are:
00105 ///  - \b canCreateNewUsers If true, anyone can connect to the server and
00106 ///        create new user accounts at will.  This is probably okay in a small
00107 ///        LAN (home network) but may not be wise in a larger LAN.
00108 ///  - \b passwordRequired If true, anyone connecting must provide a password
00109 ///        to join as a user account.  For some games, you may not care as
00110 ///        much about users, and so giving people the ability to create new
00111 ///        users at will, and log in without passwords, may be fine.  For
00112 ///        other games, you may want more control.
00113 ///
00114 /// If \b canCreateNewUsers is false, then there is no way for people to
00115 /// create new user accounts.  As an admin, you can create new user accounts
00116 /// just by creating new [username].user files in the user directory.  You can
00117 /// create empty files, and that is enough.  If a user file does not contain a
00118 /// password, the player can set the user password on their first login.
00119 ///
00120 /// If you need to reset a password, just edit the .user file for that username,
00121 /// and delete the password line.  Passwords are one-way encrypted (using a
00122 /// cryptographic hash) so even a aesop admin cannot see players' passwords.
00123 /// The user will then have to provide a new password on next login.  [This
00124 /// leads to obvious race conditions, which we can fix later if necessary]
00125 ///
00126 /// If you would like to make someone an admin, add a "isAdmin true" line to
00127 /// their [username].user file.  This will give them admin privileges on the
00128 /// server.  Only admins can start/save/end games, for instance.
00129 /// 
00130 class UserManager {
00131 public:
00132         // virtual destructor --------------------------------------------------
00133         virtual ~UserManager(void) throw();
00134 
00135         // aesop::UserManager class interface methods -------------------------
00136         virtual bool canCreateNewUsersTS(void) const throw() = 0;
00137         virtual bool passwordRequiredTS(void) const throw() = 0;
00138         virtual void getUsernamesTS(OUT SetString& names) = 0;
00139         virtual bool logInAsUserTS(IN const char * username,
00140                                 IN const char * password,
00141                                 OUT std::string& playerGuid,
00142                                 OUT std::string& diagnostic) = 0;
00143         virtual bool createUserTS(IN const char * username,
00144                                 OUT std::string& diagnostic) = 0;
00145         virtual bool isAdminTS(IN const char * username) = 0;
00146 
00147         // static factory methods ----------------------------------------------
00148         static smart_ptr<UserManager> create(IN const Datahash * params);
00149 };
00150 
00151 
00152 /// is this a valid username?
00153 bool isValidUsername(IN const char * username);
00154 
00155 
00156 /// what is the format of a valid username?
00157 std::string getUsernameRestrictions(void);
00158 
00159 
00160 };      // aesop namespace
00161 
00162 #endif  // AESOP_SRV_USERS_H__
00163