GSSTEST   Version 1.29   09-Jul-2008
====================================

----.----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.x
              64-bit running HP-UX 11.x
       "build.HP-UX" is configured for the HP ANSI-C Compiler /opt/ansic/

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

   IBM S/390 with OS/390 (aka z/OS) OpenSystem Posix environment
       (08.00,10.00,12.00,14.00,16.00) for a SAP-specific LIBASCII-compile
       and link mode compatible with SAP's software
       "build.OS-390" is configured for IBM's c89 with LIBASCII

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

   IBM AS/400 with OS/400 EBCDIC 32-bit SAP-specific Make environment
       works now, but it this make-environment is SAP-homebrew
       and not publicly available.  Note, however, that all newer
       SAP Software for IBM AS/400 is for the AS/400 "PASE" Environment,
       which are fairly vanilla AIX Unix 5.2+ PowerPC 64-bit binaries.

   Intel x86 or compatible running Linux 2.0/2.1/2.2/2.4/2.6 Kernels
       "build.Linux" was originally configured for gcc-2.7.3 & libc6
       and can be used with egcs-2.91.66 or gcc-2.95.3 and glibc-2.x,
       gcc-3.2, gcc-3.3 and gcc-4.1

   Intel x86 running MS Windows NT4/W2K/XP/W2K3 or Windows '95/'98/ME
       using Microsoft Visual C++ 6.0 (=vs98), VS.NET2003 or VS.NET2005
       "make.cmd" is configured for 32-bit compiles on VS98, VS.NET2003
       and VS.NET2005

   AMD x86_64 aka "x64" (dubbed by Intel as "EM64T" and "Intel64")
       with Windows XPpro 64-bit or Windows2003 x64
       "make.cmd" is configured for 64-bit compiles with the free(!)
       Microsoft Platform SDK Windows 2003sp2 AMD64 cross-compiler

   Intel Itanium (IA64) running Windows2003 Server for IA64
       "make.cmd" is configured for the 64-bit compiles with the free(!)
       Microsoft Platform SDK Windows 2003sp2 IA64 cross-compiler

   Intel Itanium (IA64) running Linux 2.4/2.6 (SuSE SLES-7/9 ia64)
       uses build.Linux

   MIPS 32-bit running Sinix (SINIX-Y) 5.43  (out of maintenance!)
       "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, 5.2
		  64-bit running AIX 4.3.x, 5.1, 5.2
       "build.AIX" is configured for the AIX xlc compiler

   Sparc-family 32-bit running Solaris 2.x (SunOS 5.4, 5.5, 5.6, 5.8, 5.9)
                64-bit running SunOS 5.7, 5.8, 5.9
       "build.SunOS" is configured for the SUN Workshop Pro Compiler

   AMD64 x86_64 x64 (EM64T,Intel64) running Solaris (SunOS 5.10)
       "build.SunOS" is configured for the SUN Workshop Pro Compiler

   Finally there is a build.NetBSD included that was sent to me, it
   probably works for Intel x86 32-bit platforms.



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).

Several 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, 5.2
   HP-UX        11.0, 11.11
   ReliantUNIX  5.44 & 5.45
   SunOS        5.7, 5.8, 5.9, 5.10

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>] [-l <2nd-lib>]

  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
    -E           DON'T try user error (typo in names, wrong names)
    -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
    -l <2nd-lib> specifies the name of a secondary shared library / DLL
                   which will then be used for all acceptor side operations
                   Use this for interop-testing of two libraries / DLLs


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.)

NOTE: Please do *NOT* sent me gsstest output created using '-d <num>'
it results in output significantly too large for eyeball-review.
The interesting information is contained in a normal gsstest output.

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

Martin Rex
SAP AG Walldorf
Development Architect, R/3 and SAP WebAS Security

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

Snail Mail:
   Martin Rex
   SAP AG Walldorf
   Dietmar-Hopp-Allee 16
   69190 Walldorf
   GERMANY

