/* $Id: README,v 1.2 1999/08/24 14:59:34 d019080 Exp $ */


Martin Rex,
SAP AG Walldorf
Email:  <Martin.Rex@sap-ag.de>

SNC stands for "Secure Network Communication" and refers to the
functionality in SAP R/3 components that performs strong authentication
and message protection via external software products that implement
the IETF-defined standard "Generic Security Services API Version 2"
(GSS-API v2).

This "document" briefly describes purpose, structure, usage of
the SNC Adapter and tells you how to build an SNC Adapter for
(new) gssapi mechanisms that SNC doesn't know about.

  1. Purpose
        -- What is an SNC Adapter ?

  2. Operational model
        -- How the SNC Adapter works

  3. Usage / Installation
	-- Installation/configuration/use of a
           product with an SNC Adapter.

  4. Configuration Items for a custom SNC-Adapter

  5. Registering a SAPGSS_ID and a PREFIX with SAP

  6. MAKE
	-- How to build your own/custom SNC Adapter.

  7. References
	-- Additional reading material.

1. Purpose: What is an SNC-Adapter.

   The SNC-Adapter is a thin wrapper or intermediate component
   to attach a third party security software to the SNC functionality
   of SAP R/3 via an GSS-API v2 compatible interface.

   The SNC Adapter includes an additional (initialization) call
   that provides SNC with static information about some characteristics
   of the gssapi mechanism that cannot be queried via the regular
   GSS-API functions.  All regular GSS-API v2 functions are simply
   passed on to the gssapi mechanism.

   GSS-API mechanisms can be distinguished by their mechanism OID.
   There are 3 mechanism OIDs which SNC already knows about, and for
   which it may use a built-in SNC-Adapter -- provided that the shared
   library GSS-API interface of the particular product/implementation
   is directly compatible with SNC:

    (1)  The Kerberos 5 GSS-API mechanism (rfc1964),
           mechanism OIDs {1 3 5 1 5 2} and {1 2 840 113554 1 2 2}

    (2)  The proprietary SECUDE 5 gssapi mechanism,
	   mechanism OID {1 3 36 3 1 37 1}

    (3)  The SAPNTLM gssapi mechanism supplied by SAP which
         offers NTLM-based Single Sign-On for Win32 platforms,
           mechanism OID {1 3 6 1 4 1 694 2 1 2}

   External SNC-Adapters for arbitrary GSS-API mechanisms can be built
   with the sample sources provided in this distribution.
   See "Section 6: MAKE" on how to do this.

2. Operational model

   An SNC-Adapter is intended as a very thin wrapper on top of the
   gssapi functions of an arbitrary GSS-API v2 compliant gssapi mechanism.
   I doesn't change any of the functionality available at the gssapi
   level, it only provides a little additional configuration information
   to SNC how to deal with this mechanism and it will allow to accomodate
   for differences at the binary shared library interface between SAP R/3
   and the gssapi library.

   All gss-api functions are imported by the SNC-Adapter with their
   original name and are re-exported with the prefix "sap" to the
   function name, e.g.:

          gss_acquire_cred() --> sapgss_acquire_cred()

   Besides the regular gssapi functions there are 3 additional
   SNC-specific functions:

      (1)    sapsnc_init_adapter()

      (2)    sapsnc_export_cname_blob()  -- HISTORIC, LEAVE IT ALONE
      (3)    sapsnc_import_cname_blob()  -- HISTORIC, LEAVE IT ALONE

   Function (1) "sapsnc_init_adapter()" provides static information
   about some characteristics of the underlying gssapi mechanism to
   which this SNC-Adapter is linked. 

   The functions (2) and (3) are historic and they are no longer used
   by SNC in R/3 Releases 3.1I and newer.

   The only function where the sample adapter source contains extra code
   is sapgss_indicate_mechs(), because SNC will use exactly the first
   mechanism OID from the list of mechanisms returned by

   If SNC is enabled for an R/3 component, SNC will try to dynamically
   load the configured gssapi library at runtime.

     (a)  If SNC finds the 3 additional SNC functions in the library,
          the library is assumed to be an external SNC-Adapter and
          all gssapi functions will be resolved with the function
          name prefixed by "sap".
          When loading is complete, sapsnc_init_adapter() will be
          called followed by a call to sapgss_indicate_mechs().

     (b)  If SNC doesn't find the 3 additional SNC functions in the
          library, the library is assumed to be a vanilla gssapi
          library and the gssapi functions will be resolved with their
          regular names.
	  When loading is complete, gss_indicate_mechs() will be
          called, and the returned OID_set will be searched for
          a known mechanism, for which the SNC-Adapter information
          is already compiled into SNC (see Section 1).

   It is possible to supply an external SNC-Adapter for any of the
   mechanism already known by SNC.  Sample external SNC-Adapters
   for Kerberos5, SECUDE and SAPNTLM are contained in this distribution
   (snckrb5.c, sncsecud.c, sncntlm.c).

3. Usage / Installation / Operation of a Product with SNC-Adapter

   In order to enable Secure Network Communications (SNC) for any
   R/3 component, you must specify the location of shared library
   that provides the gssapi services.  Depending on the component
   this may be through the profile parameter "snc/gssapi_lib",
   the command line parameter SNC_LIB, environment variable SNC_LIB
   or rfc.ini-parameter SNC_LIB.

   Specifying the gssapi shared library directly without an
   intermediate SNC-Adapter works only for the 3 gssapi mechanisms
   (Kerberos5,SECUDE,SAPNTLM) which SNC already knows.
   It is up to the vendor of the third party security software
   whether he includes the SNC-Adapter code directly within
   his own library or provides it as a seperate shared library.
   SNC will always try to load the library as an SNC-Adapter,
   before it checks for a known gssapi library.  Therefore it is
   ok if the shared library exports not only the SNC-Adapter
   functions but lots of other functions/APIs as well,
   including a regular gssapi.

   There are several potential issues with shared libraries and
   dynamic dependencies of one shared library on another one,
   so you should carefully consider your options how you want
   to build and finally ship a shared library suitable for use
   with SNC respectively SAP R/3.
   (The severity of these potential issues vary across platforms.)

   My recommendation: link all of your object files, including the
   SNC-Adapter into one single large shared library (respectively DLL).
   On Unix platforms, relink all of your object files including
   the SNC-Adapter into one large object file with "ld -r"
   and then link that single object into one shared library.
   This will probably save yourself and your customers some headaches
   in the long run.

   Potential issues with shared libraries:

    (1) shared library initialization/cleanup during load/unload

	Certain languages (e.g. C++) may require that an initialization
        function is called when the library is loaded and a cleanup
        function is called before the library is unloaded.

	On Microsoft Windows this is fairly easy, adequately documented
	and it works. (DllMain entry point).

	I don't know how it works on the various Unix platforms,
	but I've heard of various problems, and I haven't seen
        any documentation from any vendor so far.
        (There is apparently a bug in the HP-UX 10.20 linker,
         and AIX supports it only from Release 4.2 onward).
	If your code needs it, GOOD LUCK!

    (2) implicit loading of dependent shared libraries

	If a shared library (or DLL) is not self-contained, but
        contains implicit dynamic dependencies to other shared libraries
	placed there when the shared library was compiled and linked,
        then the system loader will attempt to load the dependents
        whenever the top-level shared library is loaded.

	When dynamic runtime loading (via dlopen()/LoadLibrary()/...)
	is used by the application to load a shared library at runtime,
	it can be loaded from anywhere in the filesystem.
	When the shared library that is to be runtime loaded
        contains implicit dependencies on other shared libraries,
        very platform specific rules will determine where the
        system loader will look for those other shared libraries
        and what it will do when it cannot find suitable libraries.

	Win32 search locations for dependents:
	  the normal search order would be:
	     path of the executable
             PATH environment variable

	  but beware of "Highlanders" -- i.e. registered shared
          libraries and the shared library cache.

	Unix search locations for dependents:
          Is hard to impossible to give any reliable rules, since
          every platform is different and has their own knobs and
          switches to change the behaviour.  Here are some general
          Unix rules:
           * Unix does NOT know the directory of the executable,
             and it does NOT look for shared libraries in the
             PATH environment variable.

	   * There is a system-default list of directories where
             system loader can search for shared libraries.
	     (e.g. /lib, /usr/lib, /usr/share/lib, ...) 

	   * Every platform respects an environment variable that
             may contain one or more directories to search when
             looking for a shared library.  But this environment
             variable is only honored when (uid)==(euid).
                  LD_LIBRARY_PATH     Digital Unix, Linux, Reliant Unix,
                                      Sinix, Solaris
                  SHLIB_PATH          HP-UX
                  LIB_PATH            AIX

           * Most platforms allow to compile-in a list of directories
             into the executable(!) where to search for shared libraries

           * HP-UX memorizes the exact and full pathname where "ld" found
             the shared library during the link step of the executable
             (or higher-level shared library).  This original path
             will be used if other locations fail.  This may cause
             usability problems to NOT show up on development machines.

           * Some platforms allow to reorder the priority of
             (original location), (compiled-in directory list) and
             (environment variable), and some platforms allow to
	     selectively disable one or the other feature.
	     (e.g. HP-UX "chatr" command)

	   * When (uid)==(euid) a platform-dependent environment variable
             (LD_LIBRARY_PATH, SHLIB_PATH or LIBPATH) may contain a
             list of directories where to look for the library.

           * When (uid)!=(euid) or when disabled for the executable,
             only the compiled-in search path and system-default
             shared library directories are searched
             (e.g. /lib,/usr/lib,/usr/share/lib,/usr/local/lib)

	   * On some platforms it is possible to compile a shared
             library search list into executables as well as into shared
             libraries.  Probably the list of the executable takes
             precedence.  However, you cannot set/change the compiled-in
             search path in executables from other vendors ...

4. Configuration Items for a custom SNC-Adapter

   In order to create a custom SNC-Adapter that interfaces to
   your own gssapi mechanism, you need to fill in the following
   information into the "sncadapt.c" sample source:

	ADAPTER_MECH_ID		--  register with SAP
	ADAPTER_MECH_PREFIX	--  register with SAP

   In detail:

   ADAPTER_MECH_ID  (16-bit unsigned integer)  -- register with SAP
      This is a numeric tag that SNC uses internally to distinguish
      different gssapi mechanisms.

   ADAPTER_MECH_PREFIX (ASCII string)          -- register with SAP
      This prefix must be at most 7 alphanumeric lowercase characters,
      and it is used internally by SNC in the nametype-prefix of SNC-Names
      to bind printable names to specific mechanisms.  This prefix can
      be passed to SNC within printable SNC-Names, however the concurrent
      use of multiple gssapi libraries is NOT supported by SNC.

      This name is used for the printable identification of
      the SNC-Adapter and used for diagnostic purposes only.

      This is the mechanism OID of your gssapi mechanism.

      This is the nametype OID that your gssapi mechanism uses
      to tag canonical printable names.  It is also the nametype oid
      that will be used to pass SNC-Names to _this_ gssapi library
      when they were prefixed with "p:"
      (Other valid SNC-Name prefixes are "u:" and "s:", which indicate
       to use the standardized generic nametypes GSS_C_NT_USER_NAME

   ADAPTER_CONF_AVAIL     (Boolean)
      Indicates whether this gssapi mechanism will unconditionally
      support message confidentiality protection on all successfully
      established security contexts.
      Indicates whether this gssapi mechanism will unconditionally
      support message integrity protection on all successfully
      established security contexts.

      Indicates whether this gssapi mechanism will unconditionally
      support mutual authentication on all successfully established
      security context where this feature was requested during

      Indicates whether this gssapi mechanism will unconditionally
      support message replay protection on all successfully established
      security contexts where this feature was requested during

5. Registering a SAPGSS_ID and a PREFIX with SAP

   Send an Email to <Martin.Rex@sap-ag.de> and request a SAPGSS_ID
   and propose a prefix up to 7 alphanumeric lowercase characters.
   Please include the name of your product and the list of
   features (see Section 4) that you are going to configure.

   I would really appreciate if could additionally enclose the output
   from our gssapi verification program GSSTEST when running it with
   your gssapi implementation.

6. MAKE -- How to build your own/custom SNC-Adapter

   This distribution contains the sample sources for several preconfigured
   SNC-Adapters (sncntlm.c, snckrb5.c, sncspkm1.c, sncsecud.c) and the
   template "sncadapt.c" which you can use to build your own SNC-Adapter.

   You are free to tear the "sncadapt.c" template apart and integrate
   the necessary pieces into your own product.  See Section 4 what
   you will need to configure to build an SNC-Adapter for your own
   custom gssapi mechanism.

   Included are a Makefile and build scripts for the following platforms:
       AIX 4.x, Solaris 2.x, Digital Unix 4.x, HP-UX 10.x
   and a batch file "make.bat" for Microsoft Win32 platforms using
   the Microsoft Visual C compiler v5 or v6 (Visual Studio 97 or 98).

   For both, Unix and Win32, the filename for the source and the
   basename of the target shared library is defined in the
   Makefile with "XNAME=".  Edit this definition when necessary.

   On the Unix platforms, you need to add the necessary linker
   parameters into the build.<platform> shell script into the
   variable definition for VENLIB so that your own gssapi library
   can be found and linked to the SNC-Adapter.

   On Windows platforms you also need to edit make.bat and modify
   the variable definition VENLIB.  Currently make.bat is configured
   to supply the name of the included gssntlm.lib so that the
   sample SNC-Adapter debug\sncntlm.dll will be generated if you
   enter "make" in the directory (provided that the Visual compiler
   environment is available).

   If you supply the name of your shared library for "VENLIB="
   then this sample build environment will create a standalone
   SNC-Adapter shared library with an implicit dependency on
   your shared library.  As discussed in Section 3, this approach
   may have significant administrative disadvantages, especially
   on Unix (because this will usually require the environment
   variable for the shared library search path to make it work).
   For Unix, you could either supply an archive library of
   position independent object files or integrate the
   SNC-Adapter source into your own shared library, so
   that you end up with a single shared libraries without
   implicit dependencies on custom libraries, thus removing
   the administrative requirement for the environment variable.

7. References:  Additional reading material

  *  "Generic Security Service Application Program Interface,
      Version 2, Update 1", John Linn, December 1998
     NOTE: This document is available only as an Internet draft with the
           name "draft-ietf-cat-rfc2078bis-08.txt".  However, this draft
           is expected to become an RFC in Fall 1999

  *  RFC2078: "Generic Security Service Application Program Interface,
               Version 2", John Linn, January 1997
     NOTE: This document will soon be updated/replaced by
           "draft-ietf-cat-rfc2078bis-08.txt", see above

  *  "Generic Security Service API Version 2 : C-bindings"
     John Wray, November 1998
     NOTE: This document is available only as an internet draft with the
           name "draft-ietf-cat-gssv2-cbind-08.txt".  However, this draft
           is expected to become an RFC in Fall 1999

   *  RFC-1964: "The Kerberos Version 5 GSS-API Mechanism"
      John Linn, June 1996

   *  RFC-2025: "The Simple Public-Key GSS-API Mechanism (SPKM)"
      Carlisle Adams,  October 1996