5.2 Debugging Tools

The MIT Kerberos distribution includes a small sample Kerberized client/server application. These example applications are located in the src/appl/sample subdirectory of the MIT Kerberos 5 distribution.

Just like any other Kerberized server, the sample server requires a service principal and access to the secret key associated with that principal through a keytab file. By default, the sample server uses a principal name of "sample," with an instance of the hostname that it is running on. If you're having trouble with a particular service principal, the sample server and client can use any principal name to communicate with each other, given the sample server has read access to the service's keytab file.

The command-line arguments accepted by the sample server are:

> ./sserver -h
usage: ./sserver [-p port] [-s service] [-S keytab]

The -p argument specifies what TCP port that the server will listen on for client requests. If this argument isn't specified, then sserver will immediately exit. The -s option can be used to specify a particular service principal (instead of the default, "sample"). For example, the host principal can be specified by -s host. Finally, the -S option specifies a keytab file in which the server can find the secret key for the service principal. By default, sserver will use /etc/krb5.keytab.

Ensure that a valid keytab entry for the principal you're using to test exists in a keytab file and is readable by the user you're starting sserver as. Note that the server won't test for the readability of the keytab until a client connects to it, and your client will report "Permission denied".

The command-line arguments that the client accepts are similar:

> ./sclient 
usage: ./sclient <hostname> [port] [service]

A successful exchange looks like the following, assuming that you have shells open on both of the hosts freebsd and slave, and their prompts are freebsd> and slave> respectively:

freebsd> ./sserver -p 8888 -s sample -S /tmp/sample.keytab
slave> ./sclient freebsd 8888 sample
sendauth succeeded, reply is:
reply len 27, contents:
You are jgarman@WEDGIE.ORG

If you choose a service name other than "sample," specify the service name on the command lines to both the server and the client. Just like with any other Kerberos client/server application, you'll see that you now have Kerberos tickets for the sample service principal:

client> klist
Ticket cache: FILE:/tmp/krb5cc_p27758
Default principal: jgarman@WEDGIE.ORG

Valid starting     Expires            Service principal
02/26/03 02:34:47  02/26/03 10:58:19  krbtgt/WEDGIE.ORG@WEDGIE.ORG
02/26/03 02:35:51  02/26/03 10:58:19  sample/freebsd.wedgie.org@WEDGIE.ORG

A similar set of programs exists for Heimdal Kerberos. Heimdal actually includes several sample client/server applications, and the two client/server sets that are the most useful for our debugging purposes are the tcp_client/tcp_server applications and the gssapi_client/gssapi_server applications, both found in the appl/test directory inside of the Heimdal source distribution. The tcp_client and tcp_server applications use the Kerberos 5 API directly, and the gssapi_client and gssapi_server applications are simple applications that utilize the GSSAPI for authentication.

The command-line arguments for these programs are similar to the MIT Kerberos sample applications:

> ./gssapi_server -h
Usage: gssapi_server [-fh] [--port=port] [-p port] [--service=service]
   [-s service] [--keytab=keytab] [-k keytab] [--fork] [--help] [--version] 
-p port, --port=port          port to listen to
-s service, --service=service service to use
-k keytab, --keytab=keytab    keytab to use
-f, --fork                    do fork
> ./gssapi_client -h
Usage: gssapi_client [-fh] [--port=port] [-p port] [--service=service]
   [-s service] [--keytab=keytab] [-k keytab] [--fork] [--help] [--version] host
-p port, --port=port          port to listen to
-s service, --service=service service to use
-k keytab, --keytab=keytab    keytab to use
-f, --fork                    do fork

The arguments accepted by tcp_client and tcp_server are the same as the gssapi_client and gssapi_server applications, respectively. Unlike the MIT Kerberos sample applications, the default principal name used by the Heimdal testing applications is "test".

When testing these programs, it was noted that the keytab command-line option did not function correctly; instead, the application continued to try and access /etc/krb5.keytab regardless of the filename passed through the -k parameter.

An example of successful output:

freebsd> ./gssapi_server -s sample -p 8888
slave> ./gssapi_client -s sample -p 8888 freebsd
User is 'jgarman@WEDGIE.ORG'
gss_verify_mic: hej
gss_unwrap: hemligt

Another tool that can be helpful is the Kerberized telnet daemon. It has rather verbose output so that errors can be readily gleamed from the messages it prints when connecting. When creating the realm in Chapter 4, we set up a telnet daemon to test the new realm. Make sure that, when using telnet to test Kerberos functionality, you use the -a option on the client to tell it to automatically attempt Kerberos authentication. Also, ensure that the telnet client program is actually a Kerberized version, and not the system telnet that may not be Kerberized.