#
#       README  Connectathon Testsuite  RPCSEC_GSS User Level API
#	
#

RPCSEC User Level API  test
===========================

This directory contains an RPC based client server program designed to
test the RPCSEC user level API. 

In-order to transfer data between client and server a secure context
must be established. Once a secure context has been established, the
server stores the names and corresponding values.  The client program
can be used to add an value to the server's list, delete an value from
the server's list, or retrieve an value from the server.  At any time
after context context establishment, the security service can be
changed between none, privacy, or integrity.

Prior to invoking the test, rpcsec_gss , GSS and Kerberos software must
be installed.

Build instructions:
-------------------

To build "client":
	make client


To build "list_svc":
	make list_svc


To build "client" and "list_svc":
	make


Source details:
---------------
README	 - This file
Makefile - For building client and list_svc

The server program consists of:
	list_svc.c	(the main program)
	list_procs.c	(the service procedures)
	list_xdr.c	(XDR routines)

The client program consists of:
	client_main.c	(the main program)
	list_clnt.c	(the client calls)
	list_xdr.c	(XDR routines)

The include file list.h defines structures exchanged between
client and server.

The file list.x, provided for reference only, defines the
client server data structures in the RPC language.

Required Setup:
---------------
Running the server:
------------------
Prior to executing the server, a server principal must be established
in the KDC database, and a keytab file extracted for the principal.
The server principal should be of the form <service name>/<host name>.
Creation of the principal and extraction of the keytab is accomplished
throught kadmin). 
  
The server is invoked as follows:

	./list_svc [-l] -n <service name> -m <mech_number>
	
The -l option causes the server to lock the security service level so
that it cannot be changed.

The -m indicate the mechanism used.
'-m 1' is for kerberos mechanism. This is also the default.
This is the only value supported currently.

Running the client
------------------
The client is used as follows:
	./client <hostname> <service name> -m <mech_number>
	
	Where hostname is the name of the host on which the server is running 		
	and service name is the name of the service.

	The -m indicate the mechanism used.
	'-m 1' is for kerberos mechanism. This is also the default.
	This is the only value supported currently.

	
	To create a secure context:
	
	create-context
	
	To change the service level:
	
	service (integrity | privacy | none)
	(Only works without -l option on server)
	

	To add an value to the server's list:

	 set <name> <value> 


	To delete an value from the server's list:

	del <name>


	To fetch an value from the server's list:

	get <name>

	To destroy a secure context:
	destroy-context

	loop #loops
	
	Create/destroy context base on number of loops.



For example:

	./client gandolf nfs

commands are:
        set <name> <value>
        get <name>
        del <name>
        service (integrity | privacy | none)
        create-context
        destroy-context
        quit
 enter cmd -> create-context
context created, ret options are:
major 0, minor 76384, vers 68624, flags 65588, time_ret 5, cxt 32, mech 

commands are:
        set <name> <value>
        get <name>
        del <name>
        service (integrity | privacy | none)
        create-context
        destroy-context
        quit
 enter cmd -> set n xxxxxx
value is set

commands are:
        set <name> <value>
        get <name>
        del <name>
        service (integrity | privacy | none)
        create-context
        destroy-context
        quit
 enter cmd -> get n
name:  n
value: xxxxxx

commands are:
        set <name> <value>
        get <name>
        del <name>
        service (integrity | privacy | none)
        create-context
        destroy-context
        quit
 enter cmd -> del n
deleted value

commands are:
        set <name> <value>
        get <name>
        del <name>
        service (integrity | privacy | none)
        create-context
        destroy-context
        quit
 enter cmd -> service privacy
service is set

commands are:
        set <name> <value>
        get <name>
        del <name>
        service (integrity | privacy | none)
        create-context
        destroy-context
        quit
 enter cmd -> destroy-context
context destroyed


SPKM Functionality
------------------

The test program has been modified to test the SPKM implementation. First, 
download and build the SPKM enabled mit-krb5-1.2.1-mech from 
http://www.citi.umich.edu/projects/nfsv4

Then, 
% cd ../rpc 
edit the Makefile, and add -DSPKM to the CFLAGS variable, 
% make clean 
% make

% cd ../rpcsec-tests
edit the Makefile, add -DSPKM to the CFLAGS variable, and set SSLDIR.
% make clean
% make

now the client can be run with -m 2 to turn on the SPKM vrs the 
Kerberos V5 mechanism.

client <host> nfs -m 2
