1 /* 2 ** Copyright 1998 - 2001 Double Precision, Inc. See COPYING for 3 ** distribution information. 4 */ 5 6 7 8 /* 9 10 The login cache is used to try to eliminate a call to getpw for each and 11 every http request, which can be quite expensive on systems with large number 12 of users and heave web traffic. The following information is saved in the 13 cache: 14 15 userid 16 groupid 17 directory (presumably of a maildir) 18 certain environment variables 19 20 21 The interface is abstracted into these functions: 22 23 maildir_cache_init(seconds, cachedir, cacheowner, authvars) 24 25 maildir_cache_start() 26 maildir_cache_save(userid, login_time, homedir, uid, gid) 27 maildir_cache_cancel() 28 29 maildir_cache_search(userid, login_time, callback_func, callback_func_arg) 30 31 The prepare, save, and cancel functions are used to cache the login 32 information. 33 maildir_cache_start should be called before we attempt to log in, when we're 34 running as root. We're about to drop root privileges after a successful 35 login, but we need to be root in order to update the cache directory, so 36 maildir_cache_start forks a child process, which will wait patiently in 37 the background. 38 39 maildir_cache_save will sends the cacheable information to the child process, 40 over a secured pipe. maildir_cache_save will be called after a successful 41 login. 42 43 maildir_cache_cancel shall be called if the login failed. It will kill the 44 child process. 45 46 The search function is called to query the cache file. If it succeeds, it 47 calls the callback function with the userid, groupid, and homedir. 48 49 There is no need to manually remove an expired cache entry upon logout. 50 It will be cleaned up by a separate cron job. 51 52 53 init_login_cache should be called before any other function. It's argument 54 specifies: that hard timeout interval - the fixed amount of time after which 55 any login becomes invalid; the login cache directory; userid that owns the 56 login cache directory; the environment variables to save in the login cache 57 directory. 58 59 The login cache functions receive the saved original login time. The login 60 cache information is saved in a directory that should be writable by cache 61 owner only. The cache directory contains subdirectories whose name is derived 62 by dividing the login time by the hard timeout interval. For example, when 63 logging on in the afternoon of November 27, 1999, the current time, in seconds, 64 is 943725152. With the login interval being the default of 2 hours, 7200 65 seconds, the top level directory would be 943725152 / 7200 or 131072. 66 67 What this allows us to do is to quickly remove expired login entries, simply 68 by reading the top level cache directory, and recursively deleting subdirs 69 whose names are too old to contain any logins that are still active. 70 71 If the login name is 'john', the cached login will be saved in the file 72 131072/jo/john, creating the subdirectories if necessary. 73 74 Because the login name can contain special characters, the special characters 75 will be escaped. See the code for more info. 76 77 */ 78 79 #ifndef logincache_h 80 #define logincache_h 81 82 #include <sys/types.h> 83 #include <time.h> 84 #include <pwd.h> 85 86 87 extern int maildir_cache_init(time_t, const char *, const char *, 88 const char * const *); 89 extern void maildir_cache_start(void); 90 extern void maildir_cache_save(const char *, time_t, const char *, uid_t, 91 gid_t); 92 extern void maildir_cache_cancel(void); 93 94 extern int maildir_cache_search(const char *, time_t, 95 int (*)(uid_t, gid_t, const char *, void *), 96 void *); 97 98 extern void maildir_cache_purge(); 99 100 #endif 101