GSSTEST   Version 1.26   03-Sep-2002
====================================

----.----1----.----2----.----3----.----4----.----5----.----6----.----7----.----

GSS-API test program and BC-SNC interoperability certification tool.
(SNC = "Secure Network Communication" is a support library in the
 SAP R/3 software that interfaces to security products via GSS-API v2).


This program will analyze and verify the behaviour of a gssapi mechanism
implementation that conforms to the IETF-defined GSS-API v2 specification
published in RFC-2743 and RFC-2744).  The tests are largely focused on the
usage pattern of the SNC-library in the SAP R/3 software.  In addition
to GSS-API v2 conformance, GSSTEST will check certain constraints and
limits required for interoperability with SNC.

The gssapi mechanism must be provided in form of a shared library, which
will be loaded by GSSTEST at runtime.  There is a source file "link_lib.c"
and a Makefile target "static" which should allow to statically link
GSSTEST with a gssapi mechanism.  However the source link_lib.c may not
be up to date.  Static linking simplifies debugging on some platforms,
however for use with SAP/SNC a shared library will be required.


The accompanying sources should compile on the following platforms:

   Alpha running Digital Unix / Compaq Tru64 (OSF1) 3.2x, 4.0x or 5.0x
       "build.OSF1" is configured for the DEC C Compiler (v5.2)

   HP PA-RISC 32-bit running HP-UX 9.x, 10.x, 11.0
              64-bit running HP-UX 11.0
       "build.HP-UX" is configured for the HP ANSI-C Compiler /opt/ansic/

   HP-UX on IA64 (Intel Itanium) running HP-UX 11.20
       "build.HP-UX" is configured for the HP ANSI-C Compiler /opt/ansic/

   IBM S/390 with OS/390 V2R8.0 Posix environment
       "build.OS-390" is configured for IBM's c89 with LIBASCII

   IBM S/390 with Linux in 32-bit (s390) or 64-bit (s390x)
       "build.Linux" also works for these platforms

   IBM AS/400 with OS/400 EBCDIC SAP-specific Make environment
       is not yet finished...

   Intel x86 or compatible running Linux 2.0/2.1/2.2 Kernels
       "build.Linux" is was originally configured for gcc-2.7.3 & libc6
       but still works with egcs-2.91.66 or gcc-2.95.3 and glibc-2.x

   Intel x86 running MS Windows NT4/W2K/XP/.NET or Windows '95/'98/ME
       using Microsoft Visual C++ 5.0(=vs97) or 6.0 (=vs98).
       "make.cmd" is configured for the Microsoft Visual C++ 5.0/6.0,
       project files for VC 5.0 and 6.0 are also included.
	(I no longer have access to VC 4.2, but I assume it still works.)

   Intel Itanium (IA64) running Linux 2.4 (SuSE SLES-7 ia64)
       using gcc-2.96-ia64-000717 snap 001117
       build.Linux for x86 works fine here

   Intel Itanium (IA64) running Win64 .NET prerelease (build 3621)
       using Microsoft C/C++ Cross-Compiler 13.00.9466.7 for IA-64
       "make.cmd" will use IA64 Cross-Compiler settings when
       the Environment Variable CPU==IA64

   MIPS 32-bit running Sinix (SINIX-Y) 5.43
       "build.SINIX-Y" is configured for SNI compiler
           "SNI: CDS++ V1.0C3200, 1.2.1.4 from 16 Dec 1997"

   MIPS 32-bit running Reliant Unix (ReliantUNIX-N) 5.44 or 5.45
        64-bit running Reliant Unix (ReliantUNIX-N) 5.44 or 5.45
	"build.ReliantUNIX-N" is configured for FSC compiler
	   "Fujitsu Siemens Computers GmbH: CDS++ V2.0C0004, 1.2.7.2"

   PowerPC/RS600  32-bit running AIX 3.2.5, 4.1.x, 4.2.x, 4.3.x, 5.1
		  64-bit running AIX 4.3.x, 5.1
       "build.AIX" is configured for the AIX xlc compiler

   Sparc-family 32-bit running Solaris 2.4, 2.5, 2.6 (SunOS 5.4, 5.5, 5.6)
                64-bit running SunOS 5.7, 5.8
       "build.SunOS" is configured for the SUN Workshop (v4.2 or v5.0)



BUILDING GSSTEST:
=================

Assuming that you have your environment and search path correctly
configured, the only thing that you will have to do after unpacking
the source distribution is to change to the gsstest directory
and type "make".  If you want to use a different compiler than
those that I have used, you may have to adjust the knob/switches
in the "build.*"-scripts (Unix) or in "make.cmd" (Microsoft Windows).

Four of the above platforms support 32-bit and 64-bit environments
on recent versions of the hardware and operating system:

   AIX          4.3.x, 5.1
   HP-UX        11.0
   ReliantUNIX  5.44 & 5.45
   SunOS        5.7  & 5.8

The build script for these platforms therefore builds seperate
executables into seperate sub-directories.  A symlink to the
resulting executable, postfixed with the OS-name and 32/64-bit
indicator is created as the final build step,
e.g. gsstest.aix_32, gsstest.hp_64, gsstest.sun_32.



RUNNING GSSTEST:
================

When gsstest is called with no command line parameters or
with "-h", then it will display a short summary of command line
options that are available:

  gsstest  -l <lib> -a <target_name> [-d <level>] [-n <num>] [-w <level> [-v]
          [-b 1/0] [-s 1/0] [-x 1/0] [-t <level>]    [-f] [-h] [-m] [-e] [-z]
          [-o <logfile>] [-p <logfile>]

  required arguments:
    -l <lib>            specifies the name of the shared library / DLL
    -a <target_name>    specifies the identity of the target / acceptor

  optional arguments:
    -d <level>   level of debug/trace output [0..4]               (default  0)
    -n <num>     number of concurrent security contexts           (default 10)
    -b 1/0       pass bogus or cleared handles into gssapi        (default  1)
    -s 1/0       check/verify SAP-specific constraints            (default  1)
    -w <level>   wrap ranges level (resolution of test [0..3])    (default  0)
    -x 1/0       attempt cross-process security context transfers (default  1)
    -o <logfile> transcript output into logfile and STDOUT
    -p <logfile> transcript output into logfile only
    -e           simulate/test user and application errors
    -f           imply GSS_C_TRANS_FLAG, force security context transfers
    -h           show this help
    -m           imply CONF and INTEG, force message protection
    -v           show location&line-numbers for ERROR messages
    -z           zap trailing NUL chars on names (dirty hack!)
    -t <level>   print detailed timing statistics for gssapi calls (default  0)
                   0=none, 1=parent, 2=child, 3=both


To get a feeling for how it should work, I have included a
DLL that should work on Microsoft Win32 (NT/95/98/ME/W2K).
It basically a wrapper of Microsofts SSPI and uses the
NTLM target-only authentication.  This DLL does NOT offer
any message protection (i.e. integrity/confidentiality)
services, but it is able to "transfer" the established
security context across process boundaries.  (I know that
a trying to hold on to an established security context that
lacks message protection is not really useful -- well, except
for testing security context transfer facilites...).

TRY:      "gsstest -l gssntlm.dll"

I highly recommend using tools like "Purify", "BoundsChecker" or
"Electric Fence" to verify the correct operation of your gssapi
implementation regarding memory&resource management during the test.



BUG REPORTS / FEEDBACK
======================

I will appreciate almost any kind of feedback on my GSS-API test
program.  I am especially interested in the output that this tool
produces for *your* gss-api implemenation on any of the supported
hardware platforms.
(You don't even have to add comments, just Email me the output of gsstest.)

Please send all (technical) feedback and bug reports for gsstest
(preferably via Email !) to:

Martin Rex
SAP AG Walldorf
Developer, R/3 Network Security

Email:  <Martin.Rex@sap.com>
Voice:  +49 (6227) 7-45351
Fax:    +49 (6227) 7-62066

Snail Mail:
   Martin Rex
   SAP AG Walldorf
   Neurottstrasse 16
   69190 Walldorf
   GERMANY

