$Id: README,v 1.3 1997/01/08 21:46:50 kenh Exp $ Tcl-Kerberos 5 - A Tcl binding to the Kerberos 5 API Version 0.9 By Ken Hornstein CHANGES FROM PREVIOUS VERSION ============================= Added support for doing User-To-User authentication, and added an example to show how to do it. Commented the test programs. INTRODUCTION ============ Welcome to the Tcl-Kerberos 5 distribution! Tcl-Kerberos 5 is a loadable Tcl module that provides a set of bindings to the Kerberos 5 API. Using this module, a Tcl programmer can write programs that authenticate to remote services using Kerberos, and can exchange integrity-protected or encrypted messages with these services. For instructions on how to install Tcl-Kerberos 5, see the "INSTALLATION" section below. For uberhackers, the ultra-quick instructions are: % ./configure % make < ... place Tcl-Kerberos in your Tcl-extension directory ... > If you are going to hack on Tcl-Kerberos 5, please read the "HACKING" file included with the distribution. INSTALLATION ============ To install this extension, you need the following things: - A Tcl installation (7.5 or higher) that supports loadable extensions. - A Kerberos 5 1.0 full installation (client binaries, libraries, and include files) that supports being linked as a shared library. Note that even though Kerberos is not supported as a shared library on all systems, you can link it as a shared library on some architectures (notably, SGI's Irix 5.3 and higher is this way). To build Tcl-Kerberos 5, run the supplied "configure" script. Read the "INSTALL.generic" file supplied with this distribution for more information on running configure. configure will try to guess the value of "prefix" by looking for tclsh on your path, if you didn't supply a --prefix argument. Two additional options that you might possibly need are: --with-tclconfig=PATH Location of the Tcl configuration file (tclConfig.sh) Every Unix Tcl installation should come with a Tcl configuration file, called "tclConfig.sh". By default, this is location in "$prefix/lib" when you installed Tcl. configure will default to "$prefix/lib" as the location of tclConfig.sh, but you can specify an alternate location with this switch. --with-krb5=PATH Location of the Kerberos 5 installation The location of your Kerberos 5 installation. It is assumed that your Kerberos libraries are in "$krb5/lib" and your Kerberos include files are in "$krb5/include". If this isn't true, you'll need to set the CPPFLAGS and LDFLAGS environment variables appropriately before you run configure. If you don't supply a value for this switch, it defaults to "$prefix". Once configure is run successfully, you can then run "make" to build Tcl-Kerberos 5. You should get a kerberos shared object (kerberos.so on most platforms) and a pkgIndex.tcl file. Install the Kerberos shared object wherever is appropriate for your system, and either use the supplied pkgIndex.tcl, or generate your own using pkg_mkIndex (read the man page for pkg_mkIndex to see how to do this). If you just want to play around with the test scripts, then you don't need to bother to install the shared object; the test scripts will look for the shared object in the current directory. If you would prefer not to use configure, then copy "Makefile.old" to "Makefile" and edit appropriately. Note that this is the Makefile I used before I converted to GNU Autoconf, and since I no longer use it, it is not guaranteed to work correctly. TESTING ======= You probably want to test out the Tcl-Kerberos extension before you try to use it. A sample client/server application is provided in the scripts "test.client" and "test.server". To use test.client and test.server, perform the following steps (please note that some of these steps will either require creating principals or access to keytabs, so you will probably need to be a Kerberos administrator, or get your Kerberos admin to do those steps for you): 1) Pick a host to run your test server. It doesn't really matter where host is located. By default, the test server runs on port 9999; if you wish it to run on a different port, then change "port" in both test.client and test.server. 2) Create a service principal for the test server. By default, test.server uses a service name of "testserver"; you can use whatever you want, but if you decide to use something other than "testserver", then change the "service" variable in test.client and test.server. If you are using kadmin, you would run the following command: kadmin: add_principal -randkey testserver/my.test.host.fqdn Once you've created this principal, extract the key out into a keytab on the host which is running your test.server. If you're not root on that system, then you can extract out the key into a different keytab than the default and set the KRB5_KTNAME variable as outlined below. Note that by default on Unix systems, the keytab is readable only by root, so you might want to extract the service key to a different keytab anyway. 3) On the host which is running the test.server, change directory to the Tcl-Kerberos build directory, run "tclsh", and enter "source test.server". It should look something like this: serverhost% tclsh % source test.server Ready! 4) Once you get a "Ready!" prompt, go to another machine. Make sure you have Kerberos credentials on this machine! Change to the Tcl-Kerberos build directory, run "tclsh", and then enter "source test.client". You will be prompted for the hostname which is running your test server. Enter it at this prompt, and you should see something similar to the following: clienthost% tclsh % source test.client Enter hostname running test server: serverhost Authentication successful On the server, you should see something similar to the following: Got connection from 123.456.78.9/4476 Authentication successful User authenticated as foo@MY.REALM.NAME 5) At this point, you will get a prompt to enter a message on the client side. This message will be sent integrity-protected. The message should be received on the server side. Once the message is received, you will be prompted to enter a reply on the server; you should see this reply on the client. 6) Next you will again see a prompt for a message and a reply; the difference here is that the message will be sent encrypted. If all the messages are transmitted and received correctly, Tcl-Kerberos 5 works on your system! Also included is a example of user-to-user authentication. The code that implements this test are in test.u2u.client and test.u2u.server. You can follow the same steps as outlined above, except that you don't need to create a service principal; you only need to have valid credentials on both the client and server side. If you can't get a service principal created at your site, using the U2U test is a good alternative to the regular test program, since it doesn't require any administrator intervention. USE === To use Tcl-Kerberos 5 in your scripts, put the following at the top of your script files: package require Kerberos (This assumes that you have installed Tcl-Kerberos into your Tcl search path). The "DOCUMENTATION" file included in the distribution provides some more information on the commands available, and how to use them. You can also use the test programs as examples. Tcl-Kerberos 5 has been tested on SunOS 4.x, Solaris 2.x, Irix 5.x, and NetBSD 1.2. BUGS ==== It is possible to get the Kerberos library to dump core by not setting things up in the authorization context correctly. I don't have a good way to fix this. Right now the implementation of krb5_sendauth/krb5_recvauth writes on file descriptors directly, rather than using Tcl_Read/Tcl_Write. This is due to the way krb5_sendauth/krb5_recvauth are implemented in the Kerberos library.