$Id: DOCUMENTATION,v 1.4 1997/01/08 20:50:18 kenh Exp $

Documentation for Tcl-Kerberos 5

Since this is an Alpha release, the documentation will be of Alpha
quality; in other words, I fully admit this part sucks! :-(

DATA STRUCTURE MANAGEMENT
=========================

Data in Tcl is represented by NULL-termiated strings.  Representing the
various structures used by Kerberos 5 in Tcl effectively presents a challenge
in some cases.  Three main approaches were used to solve this problem:

1) Some data is easily converted to a string and back.  One example of this
   is a principal; the functions krb5_parse_name() and krb5_unparse_name()
   exist to convert strings back and forth to krb5_principal types.  Thus,
   in Tcl principals are always represented by a text string, and the glue
   routines convert to and from krb5_principal types automatically.  Another
   example of this are flags; instead of using numeric values of flags,
   tables are maintained which can be used to map symbolic flag names
   to their numeric equivalant.  Numeric flags are converted to to their
   symbolic form on output, so consistancy is preserved.  One example of
   this is "principal type" argument to krb5_sname_to_principal.  Instead
   of remembering that "2" is KRB5_NT_SRV_HST, the programmer can just
   use KRB5_NT_SRV_HST, and the value is converted appropriately.

2) Some data is a structure consisting of various elements.  When feasable,
   structures are converted to a Tcl list with string representations for
   each element.  For example, a krb5_keyblock is a list consisting of
   three elements:

	{ magic_number encryption_type key_data }

   The key data is repesented as a series of hex digits.  Note that since
   a hex string has a known length, it is not necessary to encode the key
   data length.

3) Some structures are opaque, or contain data that has no good string
   representation.  For cases like these, string "handles" are created for
   these stuctures, much like file handles in Tcl.  These structure handles
   are keys into a hash table; when you give a "handle" to a function that
   needs it, a pointer to the appropriate function is looked up in a hash
   table and used by the glue routine for the actual Kerberos 5 function
   call.  For example, a authorization context is represented by a string
   handle of the form "authcon%d", where "%d" is a unique integer.  Data
   represented by this form are authorization contexts, credentials caches,
   and replay caches (in case you're wondering, you are automatically
   allocated one krb5_context per interpreter, and it is automatically
   kept track of).


LIST OF FUNCTIONS
=================

Here is a complete list of all the functions that Tcl-Kerberos 5 provides.
They pretty much have a one-to-one mapping to their appropriate Kerberos
function.  You can look at the example test programs for usage, or read
the source code for more information (in the future, a description of each
function and how to use it will be included):

krb5_get_default_realm
krb5_set_default_realm
krb5_sname_to_principal
krb5_cc_default
krb5_cc_get_principal
krb5_cc_close
krb5_cc_destroy
krb5_auth_con_init
krb5_auth_con_free
krb5_auth_con_getkey
krb5_auth_con_getlocalsubkey
krb5_auth_con_getremotesubkey
krb5_auth_con_getflags
krb5_auth_con_setflags
krb5_auth_con_genaddrs
krb5_auth_con_setrcache
krb5_auth_con_setuseruserkey
krb5_sendauth
krb5_recvauth
krb5_get_credentials
krb5_get_server_rcache
krb5_rc_close
krb5_rc_destroy
krb5_write_mk_safe
krb5_read_rd_safe
krb5_write_mk_priv
krb5_read_rd_priv

The last four require a little bit of explanation.

Since Tcl (currently) doesn't support binary data, it would be difficult
to handle data from a krb5_mk_priv/krb5_mk_safe call, since this data could
conceivably contain binary data.  While it would be possible to return a
hex string and write another function to deal with it, I decided it would
just be easier to have functions that read and write KRB_PRIV and KRB_SAFE
messages (since that's what you're going to do 99% of the time anyway).  Thus,
krb5_{read|write}_{rd|mk}_{safe|priv} perform like their Kerberos 5
counterparts, except that they also take a channel name to read/write the
data on.

Note that if you're going to use the safe/priv functions, you probably want
to do "fconfigure channelId -translation binary" so the data doesn't get
scrambled.
