Kerberos Example Programs
» Table of Contents |  | | » Glossary | | | » Index | | |
| | |
| ||
| ||
This section describes the Kerberos example programs. Kerberos must be configured before any example program is run. For the configuration procedure, see Chapter 2.
The Kerberos example programs are found in SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS...].
The Kerberos example programs are divided between those examples that use DCL to build and those that use GMAKE to build.
The SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.DCL] directory in the Kerberos example directory tree contains the Version 1.0 example programs and build procedures. (No new examples were added to the DCL directory for Version 3.0.) These example programs are described in the following sections.
There are two DCL example programs, each of which has a client and server piece. Command procedures to build and help set up the example programs are provided, along with readme files specific to each example.
The examples should be built and run from a local build area or directory. The following table lists the DCL example programs and information about what aspect of Kerberos each program is attempting to convey.
DCL Example Program | Description |
|---|---|
GSS_CLIENT and GSS_SERVER | GSSAPI example program |
KRB_CLIENT and KRB_SERVER | KRB5 API example program |
The GSSAPI example program is a simple client/server program that authenticates using the GSSAPI.
To run the GSSAPI example client program, perform the following steps:
Create a Kerberos principal name of gss_sample/<node name>@<realm name> before this program is run.
Copy the GSS_*.* example files and the BUILD.COM and SETUP.COM files into a local build area, and then execute the BUILD command file as follows:
$ COPY SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.DCL]GSS*.* local_build_area
$ COPY SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.DCL]*.COM local_build_area
$ SET DEF local_build_area
$ @BUILD GSSExecute the SETUP command file to define the necessary symbols to run the example.
Ensure that Kerberos has been initialized and started, and that the necessary Kerberos principal name has been created in the Kerberos database. The SETUP command file has additional information about creating the principal name.
Copy either GSS_CLIENT.EXE or GSS_SERVER.EXE to another node in the same Kerberos realm, along with the SETUP command file.
Start the client program and server programs using the symbols defined in SETUP.COM.
SYNOPSIS
|
|
|
OPTIONS
-p port
Specifies the TCP/IP port to use for communications. If this argument is absent, port number 4444 is used.
message
Specifies the text message to pass between client and server.
host
Specifies the host system where the GSS_SERVER is located.
SYNOPSIS
|
|
|
OPTIONS
-p port
Specifies the TCP/IP port to use for communications. If this argument is absent, port number 4444 is used.
-l logfile
Indicates that a logging file with the file name specified by logfile should be opened when the GSS_SERVER program is started.
Specifies the service name. If this argument is absent, gss_sample is used as the service name.
The KRB5 example program is a simple client/server program that authenticates using the Kerberos API.
To run the KRB5 API example program, perform the following steps:
Create a Kerberos principal name of krb_sample/node name@realm name before this program is run.
Copy the KRB_*.* example files and the BUILD.COM and SETUP.COM files into a local build area, and then execute the BUILD command file as follows:
$ COPY SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.DCL]KRB*.* local_build_area
$ COPY SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.DCL]*.COM local_build_area
$ SET DEF local_build_area
$ @BUILD KRBExecute the SETUP command file to define the necessary symbols to run the example.
Ensure that Kerberos has been initialized and started and that the necessary Kerberos principal name has been created in the Kerberos database. The SETUP command file has additional information about creating the principal name.
Copy either the KRB_CLIENT.EXE or KRB_SERVER.EXE to another node in the same Kerberos realm, along with the SETUP command file.
Start the client and server programs using the symbols defined in SETUP.COM.
SYNOPSIS
|
|
|
OPTIONS
-p port
Specifies the TCP/IP port to use for communications. If this argument is absent, port number 4444 is used.
message
Specifies the text message to pass between client and server.
host
Specifies the host system where the KRB_SERVER is located.
Specifies the service name. If this argument is absent, krb_sample is used as the service name.
SYNOPSIS
|
|
|
OPTIONS
-p port
Specifies the TCP/IP port to use for communications. If this argument is absent, port number 4444 is used.
-l logfile
Indicates that a logging file with the file name specified by logfile should be opened when the KRB_SERVER program is started.
Specifies the service name. If this argument is absent, krb_sample is used as the service name.
The SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.GMAKE...] directory in the Kerberos example directory tree contains the examples that build with GMAKE.
The example programs in the SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.GMAKE.VMS] subdirectory contain the original OpenVMS Kerberos Version 1.0 example programs (GSSAPI and KRB5). These examples are built with GMAKE instead of DCL. These programs show you how the two GMAKE and DCL build processes compare using the same code base.
This build can produce the GSS and KRB example programs built against the 64-bit and 32-bit Kerberos and GSS libraries respectively. Both types of builds can be produced without directory conflict, and they can be run out of their respective build directories.
The server awaits a connection on a socket, receives a message from the client that it prints out, and then echoes back to the client. Run each program with "-?" to see the runtime options for the client and server.
Four example programs are included in the SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.GMAKE.MIT] subdirectory.
Each of these examples builds against the 32-bit KRB and GSS runtime libraries. Because of the form of UNIX I/O functions that they use, the 64-bit Kerberos libraries cannot be used.
The following table lists the new GMAKE example programs found in SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.GMAKE.MIT] and information about what aspect of Kerberos each program is attempting to convey.
| GMAKE Example Program | Description |
|---|---|
GSS-SAMPLE | 32-bit based application that uses the 32-bit GSS$RTL32 library on Alpha, and the 32-bit implementations of the UNIX I/O library function calls |
SAMPLE | Demonstration client/server application |
SIMPLE | UDP-based client and server application |
USER_USER | Demonstrates a TCP/IP service name used to securely communicate between two network applications |
The SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.GMAKE.MIT.GSS-SAMPLE] subdirectory contains a GSS-SAMPLE.README file that describes in detail the function and operation of the GSS-SAMPLE program. It is a 32-bit based application that uses the 32-bit GSS$RTL32 library on Alpha. It also uses the 32-bit implementations of the UNIX I/O library function calls.
This directory also contains a sample GSSAPI client and server application. In addition to serving as an example of GSSAPI programming, this application is also intended to be a tool for testing the performance of GSSAPI implementations. Each time the client is invoked, it performs one or more exchanges with the server.
The client application can be used to simulate a variety of workloads on the server. It can serve as an example of how to create a performance application to test a new Kerberos GSSAPI based application of your own.
Several command line options can be used to define how the client will interact with the server. The GSS-SAMPLE.README file lists these options in detail. The following is a summary of GSS-SAMPLE options:
SYNOPSIS
|
|
|
OPTIONS
-d
Tells the client to delegate credentials to the server. For the Kerberos GSSAPI mechanism, this means that a forwardable TGT will be sent to the server, which will put it in its credential cache. You must have acquired your tickets with kinit -f for this to work.
-f
Tells the client that the msg argument is actually the name of a file whose contents should be used as the message.
-ccount
Specifies how many sessions the client should initiate with the server (the connection count).
-mcount
Specifies how many times the message should be sent to the server in each session (the message count).
-na
Tells the client not to do any authentication with the server. Implies -nw, -nx and -nm.
-nx
Tells the client not to encrypt messages.
-nw
Tells the client not to wrap messages. Implies -nx.
-nm
Tells the client not to ask the server to send back a cryptographic checksum (MIC).
The SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.GMAKE.MIT.SAMPLE] subdirectory contains the build for a server and a client called sserver and sclient, respectively, that are a simple demonstration client/server application.
When sclient connects to sserver, it performs a Kerberos authentication, then sserver returns to sclient the Kerberos principal that was used for the Kerberos authentication. This example provides a good test that Kerberos has been successfully installed and configured on a machine.
The sclient and sserver images are built in separate directories, but the client and server are run from the top-level directory. There is a complete README file in the sserver directory that describes the detailed information for configuring and running these examples. You can get a fast start by simply running SAMPLE_SETUP.COM in this directory for both the client and the server windows.
The SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.GMAKE.MIT.SIMPLE] subdirectory contains a UDP-based client and server example. It is similar to the original Version 1.0 KRB_CLIENT and KRB_SERVER examples, except that it uses UDP socket-based I/O. The server receives a message from the client and simply reports what it has received. The client reports that it successfully sent the data.
The SYS$COMMON:[SYSHLP.EXAMPLES.KERBEROS.GMAKE.MIT.USER_USER] subdirectory holds a client and a server example that can be used to see how a TCP/IP service name can be used to securely communicate between two network applications. It is similar to the original Version 1.0 KRB_CLIENT and KRB_SERVER examples, except that a TCP/IP service name is defined and used to tell the client the port number on which the server is listening. The client sends its data to the server and the server responds to the client with the message the client sent.