/*========================================================================*/ /* $Id: README,v 1.2 1999/08/24 14:59:34 d019080 Exp $ */ /*========================================================================*/ SNC Adapter README Martin Rex, SAP AG Walldorf Email: 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 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. 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 ============================================================================