NOTES

These are the release notes for the kernel token distribution, 0.2.
Please read the license in license/ktokens.license.

Contents
--------

0. New Features since 0.1
1. Limitations
2. Building ktokens
3. Test Programs
4. Good Things to Try
5. Files and Directories
6. Contact Information

0. New Features since 0.1
-------------------------

 - Mod unload garbage collection now works
 - Bug fixes
 - Rudimentary TOKEND behavior implemented
 - KerberosIV patches to use Tokens/PAGs
 - Setuidtoken implemented as sample syscall access control behavior
 - More extensive user test utilities
 - Makefiles improved -- make install added

1. Limitations
--------------

Many:

proc hooks: 

There is current no extended authentication hook in the kernel proc
structure.  To work around this,  the ktoken kernel module uses a hash
table to map use processes to PAG structures.  The real solution is just
to add a new pointer in the proc structure (see kernel/p_authext.diff).
As this is not yet available in the main FreeBSD tree, this is not used.
The hash table implementation is a hack, and does not behave well on
a collision.  The code works perfectly until at least 2048 processes have
joined a PAG.  At that point, collisions result in a failure of new
processes to join a PAG in a fork.  This is not fatal, and will not result
in any crashes or corruption of data.  However, this is not correct
behavior for PAGs.

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)

no transfer: 

Loadable kernel modules cannot currently hook the socket-based transfer
of rights/kernel structures.  For this to be implemented, hooks must be
added to the FreeBSD kernel.  Patches to allow this will be added shortly.

setdebug: 

Due to syslogd 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 install binaries, libraries, and includes (if desirable):

  # make install

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
----------------

tokcontrol [command] [commandargs]

Interface to the token module.  Sample uses:

  # tokcontrol debug 100

Sets debug level to 100.  (root only)

  # tokcontrol createtokend

Creates a TOKEND localpriv token to allow the creation of privileged tokens.
(root only)

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
  Listing tokens in PAG 7
  TokenID: 36       Name: setuid1.@local
   Rights: RMDIet      Type: localpriv (1,2,0)
   Pub length: 0       Priv length: 0
   Createtime: 899609951       Expiretime: 0
   Creator: process (2)

createtoken

Creates a token for the sake of experimentation.

  % ./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


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

An interesting example of kernel authorization tokens:
% indicates a normal user prompt
# indicates a root prompt

  % newpag tcsh
  % id
  uid=1000(test) gid=1000(test) groups=0(wheel), 1000(test) 
  % su
  Password:
  # createtokend
  createtokend: preparing to generate a token
  createtokend: ok
  # listtokens
  Listing tokens in PAG 2
  TokenID: 2       Name: tokend.@localpriv
   Rights: rmDiet      Type: localpriv (1,1,0)
   Pub length: 0       Priv length: 0
   Createtime: 0       Expiretime: 0
   Creator: kernel (1)
  # exit
  % listtokens
  Listing tokens in PAG 2
  TokenID: 2       Name: tokend.@localpriv
   Rights: rmDiet      Type: localpriv (1,1,0)
   Pub length: 0       Priv length: 0
   Createtime: 0       Expiretime: 0
   Creator: kernel (1)
  % createuidtoken 1001
  createuidtoken: preparing to generate a token for 1001
  createtoken: received tokenid 3
  % listtokens
  TokenID: 2       Name: tokend.@localpriv
   Rights: rmDiet      Type: localpriv (1,1,0)
   Pub length: 0       Priv length: 0
   Createtime: 0       Expiretime: 0
   Creator: kernel (1)
  TokenID: 3       Name: setuid1.@localpriv
   Rights: rmDIet      Type: localpriv (1,2,1001)
   Pub length: 0       Priv length: 0
   Createtime: 900296539       Expiretime: 0
   Creator: tokend (3)
  % setuid 3 id
  uid=1001(test2) gid=1000(test) groups=0(wheel), 1000(test)

The user creates a normal PAG.  They then su to root, and create a tokend
token via the debugging interface.  On returning to their previous shell
in the same PAG, they still have the tokend token.  Using that token, they
may create local authorization tokens that the kernel will observe.  The
createuidtoken command creates a setuid token with uid 1001, and with
the tokend creator.  The setuid command makes use of this token to run the
id command as uid 1001, which the kernel knows the user is authorized to
make use of.  This could be extended to arbitrary kernel privileges using
a token manager possessing the tokend token, and the ability to transfer
tokens to other PAGs.  Users permitted to switch UIDs would be able to
acquire setuid tokens as needed for those IDs.

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)
     kerberosIV/   KTH KerberosIV modifications to use tokens (under-tested)
     kernel/       Kernel patches to improve kernel interaction (not yet used)

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

kerberosIV/kdestroy.c          Token-based kdestroy
kerberosIV/tf_util_token.c     Token-based krb4 support code
                               (requires rebuilding krb4 libraries + programs)

kernel/p_authext.diff          Kernel (3.0) diffs to add pag refs in proc
                               (not used)

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/libktoken.h           Supporting code prototypes
userland/libktoken.c           Supporting code (library)
userland/createtoken.c         Creates new token
userland/createuidtoken.c      Create a uid-localpriv token
userland/deletetoken.c         Deletes a token
userland/listtokens.c          Lists current pag token
userland/newpag.c              Creates new pag
userland/reflecttoken.c        Reflects a token
userland/setuid.c              Using an appropriate uid-localpriv token, su
userland/tokcontrol.c          Debugging control and TOKEND creation

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.8 1998/07/13 18:13:11 robert Exp $