diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 447 |
1 files changed, 447 insertions, 0 deletions
@@ -0,0 +1,447 @@ +/*========================================================================*/ +/* $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 + +============================================================================ + |