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