                                                                         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 $
