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 divided between those examples
that use DCL to build and those that use GMAKE to build.
DCL Example Programs |
 |
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 GSS |
Execute 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
gss_client [-p port] [message] [host] [service] |
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.
service
SYNOPSIS
gss_server [-p port] [-l logfile] [service] |
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.
service
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 KRB |
Execute 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
krb5_client [-p port] [message] [host] [service] |
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.
service
Specifies the service name. If this argument is absent, krb_sample is
used as the service name.
SYNOPSIS
krb_server [-p port] [-l logfile] [service] |
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.
service
Specifies the service name. If this argument is absent, krb_sample is
used as the service name.
GMAKE Example Programs |
|
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 |
GSS-SAMPLE Example Program
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
gss-sample [-d] [-f] [-ccount] [-mcount] [-na] [-nx] [-nw] [-nm] |
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.
USER_USER
Example Program
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.
