/*========================================================================*/
/* $Id: README,v 1.2 1999/08/24 14:59:34 d019080 Exp $ */
/*========================================================================*/
SNC Adapter README
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
sapgss_indicate_mechs().
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
%SystemRoot%\System32
%SystemRoot%
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
ADAPTER_MECH_NAME
ADAPTER_MECHANISM_OID
ADAPTER_NAMETYPE_OID
ADAPTER_CONF_AVAIL
ADAPTER_INTEG_AVAIL
ADAPTER_MUTUAL_AUTH
ADAPTER_REPLAY_PROT
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.
ADAPTER_MECH_NAME (ASCII string)
This name is used for the printable identification of
the SNC-Adapter and used for diagnostic purposes only.
ADAPTER_MECHANISM_OID (gss_OID)
This is the mechanism OID of your gssapi mechanism.
ADAPTER_NAMETYPE_OID (gss_OID)
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
and GSS_C_NT_HOSTBASED_SERVICE)
ADAPTER_CONF_AVAIL (Boolean)
Indicates whether this gssapi mechanism will unconditionally
support message confidentiality protection on all successfully
established security contexts.
ADAPTER_INTEG_AVAIL (Boolean)
Indicates whether this gssapi mechanism will unconditionally
support message integrity protection on all successfully
established security contexts.
ADAPTER_MUTUAL_AUTH (Boolean)
Indicates whether this gssapi mechanism will unconditionally
support mutual authentication on all successfully established
security context where this feature was requested during
gss_init_sec_context().
ADAPTER_REPLAY_PROT (Boolean)
Indicates whether this gssapi mechanism will unconditionally
support message replay protection on all successfully established
security contexts where this feature was requested during
gss_init_sec_context()
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
============================================================================
