README
1[Out of date; needs updating for thread safety test support. -- KR 2005-02-09]
2
3# Copyright 1993 by OpenVision Technologies, Inc.
4#
5# Permission to use, copy, modify, distribute, and sell this software
6# and its documentation for any purpose is hereby granted without fee,
7# provided that the above copyright notice appears in all copies and
8# that both that copyright notice and this permission notice appear in
9# supporting documentation, and that the name of OpenVision not be used
10# in advertising or publicity pertaining to distribution of the software
11# without specific, written prior permission. OpenVision makes no
12# representations about the suitability of this software for any
13# purpose. It is provided "as is" without express or implied warranty.
14#
15# OPENVISION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
16# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
17# EVENT SHALL OPENVISION BE LIABLE FOR ANY SPECIAL, INDIRECT OR
18# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
19# USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
20# OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
21# PERFORMANCE OF THIS SOFTWARE.
22
23This directory contains a sample GSS-API client and server
24application. In addition to serving as an example of GSS-API
25programming, this application is also intended to be a tool for
26testing the performance of GSS-API implementations.
27
28Each time the client is invoked, it performs one or more exchanges
29with the server. Each exchange with the server consists primarily of
30the following steps:
31
32 1. A TCP/IP connection is established.
33
34 2. (optional, on by default) The client and server establish a
35 GSS-API context, and the server prints the identify of the
36 client.
37
38 / 3. The client sends a message to the server. The message may
39 / be plaintext, cryptographically "signed" but not encrypted,
40 | or encrypted (default).
41 |
420 or | 4. The server decrypts the message (if necessary), verifies
43more | its signature (if there is one) and prints it.
44times|
45 | 5. The server sends either a signature block (the default) or an
46 | empty token back to the client to acknowledge the message.
47 \
48 \ 6. If the server sent a signature block, the client verifies
49 it and prints a message indicating that it was verified.
50
51 7. The client sends an empty block to the server to tell it
52 that the exchange is finished.
53
54 8. The client and server close the TCP/IP connection and
55 destroy the GSS-API context.
56
57The client also supports the -v1 flag which uses an older exchange
58format compatible with previous releases of Kerberos and with samples
59shipped in the Microsoft SDK.
60
61The server's command line usage is
62
63 gss-server [-port port] [-verbose] [-once] [-inetd] [-export]
64 [-logfile file] service_name
65
66where service_name is a GSS-API service name of the form
67"service@host" (or just "service", in which case the local host name
68is used). The command-line options have the following meanings:
69
70-port The TCP port on which to accept connections. Default is 4444.
71
72-once Tells the server to exit after a single exchange, rather than
73 persisting.
74
75-inetd Tells the server that it is running out of inetd, so it should
76 interact with the client on stdin rather than binding to a
77 network port. Implies "-once".
78
79-export Tells the server to test the gss_export_sec_context function
80 after establishing a context with a client.
81
82-logfile
83 The file to which the server should append its output, rather
84 than sending it to stdout.
85
86The client's command line usage is
87
88 gss-client [-port port] [-mech mechanism] [-d] [-f] [-q]
89 [-seq] [-noreplay] [-nomutual]
90 [-ccount count] [-mcount count] [-na] [-nw] [-nx] [-nm]
91 host service_name msg
92
93where host is the host running the server, service_name is the service
94name that the server will establish connections as (if you don't
95specify the host name in the service name when running gss-server, and
96it's running on a different machine from gss-client, make sure to
97specify the server's host name in the service name you specify to
98gss-client!) and msg is the message. The command-line options have
99the following meanings:
100
101-port The TCP port to which to connect. Default is 4444.
102
103-mech The OID of the GSS-API mechanism to use.
104
105-d Tells the client to delegate credentials to the server. For
106 the Kerberos GSS-API mechanism, this means that a forwardable
107 TGT will be sent to the server, which will put it in its
108 credential cache (you must have acquired your tickets with
109 "kinit -f" for this to work).
110
111-seq Tells the client to enforce ordered message delivery via
112 sequencing.
113
114-noreplay Tells the client to disable the use of replay
115 detection.
116
117-nomutual Tells the client to disable the use of mutual authentication.
118
119-f Tells the client that the "msg" argument is actually the name
120 of a file whose contents should be used as the message.
121
122-q Tells the client to be quiet, i.e., to only print error
123 messages.
124
125-ccount Specifies how many sessions the client should initiate with
126 the server (the "connection count").
127
128-mcount Specifies how many times the message should be sent to the
129 server in each session (the "message count").
130
131-na Tells the client not to do any authentication with the
132 server. Implies "-nw", "-nx" and "-nm".
133
134-nw Tells the client not to "wrap" messages. Implies "-nx".
135
136-nx Tells the client not to encrypt messages.
137
138-nm Tells the client not to ask the server to send back a
139 cryptographic checksum ("MIC").
140
141To run the server on a host, you need to make sure that the principal
142corresponding to service_name is in the default keytab on the server
143host, and that the gss-server process can read the keytab. For
144example, the service name "host@server" corresponds to the Kerberos
145principal "host/server.domain.com@REALM".
146
147This sample application uses the following GSS-API functions:
148
149 gss_accept_sec_context gss_inquire_names_for_mech
150 gss_acquire_cred gss_oid_to_str
151 gss_delete_sec_context gss_release_buffer
152 gss_display_name gss_release_cred
153 gss_display_status gss_release_name
154 gss_export_sec_context gss_release_oid
155 gss_get_mic gss_release_oid_set
156 gss_import_name gss_str_to_oid
157 gss_import_sec_context gss_unwrap
158 gss_init_sec_context gss_verify_mic
159 gss_inquire_context gss_wrap
160
161This application was originally written by Barry Jaspan of OpenVision
162Technologies, Inc. It was updated significantly by Jonathan Kamens of
163OpenVision Technologies, Inc.
164
165$Id$
166