NOTES These are the release notes for the kernel token distribution, 0.1. Please read the license in license/ktokens.license. Contents -------- 1. Limitations 2. Building ktokens 3. Test Programs 4. Good Things to Try 5. Files and Directories 6. Contact Information 1. Limitations -------------- Many: proc hooks: Because there is no auth_data hook in proc, I had to maintain my own pointers in a cheapo-hash table (procmap.[hc]). This would be remedied if there was such a field in proc available. For expediency in development, the hash table supports at most 1024 processes in a particular run of the module! My test environments have never gotten that high, as I tend to reload the module a lot. It won't crash or anything, but new processes forked off won't be able to join a PAG if their hash table spot is full (no chaining, etc). vmstat: Because kernel MALLOC does not allow the unregistering of malloc_type records, make unload results in an unreadable vmstat -m. Maybe I should fix MALLOC? Or maybe I should not use specific malloc_types. It is useful for monitoring memory though. (This is not an issue under 2.2 as malloc types are not used in the 2.2 build of the module) unload leak: When the module is unloaded, it does not gargbage collect (GC) all of its structures. This should and will be fixed. At some point. Rebooting frees up the memory. no transfer: It doesn't look like lkm's can hook the behavior for opaque transfering of kernel structures via sockets (like file descriptors). Therefore, either hooks need to be added, or this needs to be in the real kernel. I vote for hooks. But they are not yet there. setdebug: Due to syslog using fsync() on log files when messages come from the kernel, setting any reasonable debug level results in the disk churning. Workaround: don't use high debug levels, or disable syslog on kernel messages. 2. Building ktokens ------------------- This software was developed under FreeBSD 3.0-CURRENT, but should also work in 2.2-STABLE. It builds with one warning under -STABLE due to a prototype change for syscalls. This should not affect functionality. However, tokens have not been tested under 2.2, and were not developed there, so no guarantees are made (not that they were for 3.0 either). To build: % cd impl % make To load the module: % cd module % make load To unload the module: % cd module % make unload To run test programs: % cd userland % ./program [args] 3. Test Programs ---------------- setdebug [level] Sets the ktoken debug level to level. This may only be called by the superuser. Due to the use of fsync() by syslogd, performance becomes very slow at high debug levels. Only the superuser may set the debug level. This is implemented via t_setdebug(). % ./setdebug 100 newpag [command] Execs 'command' in a new PAG. This is achieved by calling t_newpag(), fork(), and exec(). A useful invocation is "newpag csh". If a parent pag exists, then any tokens in it marked with the INHERIT right will exist also in the new PAG. % ./newpag tcsh listtokens Lists all tokens in the current PAG using the t_printpretty() function. This is implemented via repeated calls to t_findtoken() and t_readtoken() until no more tokens are found. % ./listtokens createtoken Creates a token of major type 1, minor type 2, and minorminor type 3. Additionally, its name is "robert", and realm "WATSON.ORG". The public portion of the token is 5 \0's, the private portion 10 \0's. The rights are set to INHERIT + READ + DELETE + MODIFY. This is implemented via the t_createtoken() call. % ./createtoken deletetoken [tokenid|-a] Deletes the specified token from the current PAG. With the -a argument, all tokens in the current PAG are deleted. This is implemented via the t_deletetoken() call. For all tokens, repeated calls to t_findtoken() are made to discover tokens to delete. % ./deletetoken 1 reflecttoken [tokenid] Generate a reflection of the specified token. This is implemented via t_reflecttoken(). % ./reflecttoken 2 testsyscall Do a bunch of things in one program, along with a sleep(10). Forks, newpags, creates tokens, fails at deleting a bad token, etc. % ./testsyscall 4. Good Things to Try --------------------- Here are some things to try: % ./newpag csh % ./listtokens % ./createtoken % ./listtokens % ./reflecttoken 1 % ./listtokens % ./newpag csh % ./listtokens % exit % ./listtokens % ./deletetoken -a % ./listtokens % exit 5. Files and Directories ------------------------ Directory structure: docs/ Documentation impl/ Implementation common/ Code common to the kernel and userland (syscall arguments, structures, constants, etc) module/ Kernel-only code, structures,etc userland/ User-land only code, structures (library, testprograms) Source files: common/ktoken_const.h Common constants (rights, etc) common/ktoken_structs.h Common structs (utoken structure) common/ktoken_types.h Common types (tokenid_t, etc) common/ktoken_syscall.h Syscall argument structures module/ktokenloader.c Module loading/unloading code module/ktoken_kconst.h Constants specific to the kernel module/ktoken.c Syscall code, at_* hooks module/ktoken.h Supporting prototypes, macros module/ktoken_support.c Token/PAG manipulation routines module/ktoken_support.h Supporting prototypes, macros module/ktoken_kstructs.h Kernel-specific structures (PAGS, etc) module/procmap.c Cheapo-hash from pid to PAGs module/procmap.h Supporting prototypes, structs userland/testsyscall.c Variety of test stuff userland/libktoken.h Supporting code prototypes userland/libktoken.c Supporting code userland/setdebug.c Sets debug level userland/newpag.c Creates new pag userland/listtokens.c Lists current pag tokens userland/createtoken.c Creates new token userland/deletetoken.c Deletes a token userland/reflecttoken.c Reflects a token 6. Contact Information ---------------------- FreeBSD Tokens Page: http://www.watson.org/fbsd-hardening/tokens/ FreeBSD related questions: robert+freebsd@cyrus.watson.org General ktokens questions: robert+sec.ktokens@cyrus.watson.org Personal email: robert@fledge.watson.org $Id: NOTES,v 1.6 1998/06/26 18:15:39 robert Exp $