Release notes for gsskrb5 v1.09 17-Jun-2008 Martin Rex ************************************************************************ * * Copyright (c) 1997-2008 SAP AG. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * 3. All advertising materials mentioning features or use of this * software must display the following acknowledgment: * "This product includes software developed by SAP AG" * * 4. The name "SAP AG" must not be used to endorse or promote products * derived from this software without prior written permission. * For written permission, please contact www.press@sap.com * * 5. Redistributions of any form whatsoever must retain the following * acknowledgment: * "This product includes software developed by SAP AG" * * THIS SOFTWARE IS PROVIDED BY SAP AG ``AS IS'' AND ANY EXPRESSED * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR * PURPOSE ARE DISCLAIMED. SAP AG SHALL BE LIABLE FOR ANY DAMAGES * ARISING OUT OF THE USE OF THIS SOFTWARE ONLY IF CAUSED BY SAP AG'S * INTENT OR GROSS NEGLIGENCE. IN CASE SAP AG IS LIABLE UNDER THIS * AGREEMENT FOR DAMAGES CAUSED BY SAP AG'S GROSS NEGLIGENCE SAP AG * FURTHER SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, * OR TORT, AND SHALL NOT BE LIABLE IN EXCESS OF THE AMOUNT OF * DAMAGES TYPICALLY FORESEEABLE FOR SAP AG, WHICH SHALL IN NO EVENT * EXCEED US$ 500.000.- * ************************************************************************ 1.) Project "Homepage" (Home/Download Location) =============================================== The most recent version of *MY* gsskrb5 (remember, it's Open Source) is available for download via FTP from the following directory: ftp://ftp.sap.com/pub/ietf-work/gssapi/gsskrb5/ 2.) Status of this code: ======================== This code has release status. I have tested only those features that we at SAP require for our application (which are many but not all of the GSS-API v2 features), but it seems to work OK for all *our* purposes (well, except that Microsoft keeps adding bugs to their Kerberos and require me to add workarounds to gsskrb5.dll for Microsoft Windows Service packs or new OS Releases...) Since the code was originally written with the whole spec in mind, there are features that I have implemented but not really tested, and there are a few shortcuts and ommissions in a few places that might need to be aligned before some of the untested, unfinished or missing features may actually work. See the section "Tested functionality and implementation notes". I have used Microsoft Visual Studio 98 (aka VC6) to develop this code and I still use VS98. The 64-bit version require the Windows 2003 SDK (sp1 or sp2), which has been available for free download (with both IA64 and AMD64 cross-Compilers). I have made a few tweaks so that this code should compile with Visual Studio 2005, but I **STRONGLY** recommend using VS98, because VS98 is so much less hazzle and so much more reliable and you don't need the braindead VCREDIST.EXE libc-variant of the day, you can just copy the DLL **alone** to every Win32-Platform (Win9x and NT4 included). 3.) Purpose of of this code: ============================ The gsskrb5 v1.09 codebase can be used to build two different DLLs implementing two independent GSSAPI mechanisms: 1) gsskrb5.dll which implements an RFC-1964 compatible GSS-API v2 mechanism on top of the Kerberos SSP of Microsoft Windows 2000. It supports secure mutual authentication and single-DES message protection as specified in RFC-1964. It is interoperable with MIT Kerberos 5. 2) gssntlm.dll which implements a simple GSS-API v2 mechanism using the NTLM SSP of Windows 9x and Windows NT/2000. This is a "proprietary" gssapi-style framing of NTLM by SAP. I have no formal spec for it. NTLM is a simple target-only challenge-response authentication. When accepting contexts on Win 9x, an insecure pass-through authentication request to an NT machine is performed. As it is configured, the mechanism supports no message protection (although implemented, the message integrity protection of NTLMv1 is insecure, broken and incompatible with context export/import). 3) gssboth.dll (I haven't tried that for quite some time now ...) which is a multi-mechanism containing both the Kerberos 5 and the SAP NTLM SSP gssapi mechanisms in a single DLL. NOTICE: This multimechanism is only very marginally tested. Some things may not work (or work different than they should). 4) gss-sample is the OpenVision donated gss-sample application taken from the MIT Kerberos5 v1.0.5 source tree and modified to work on Win32 platforms with this GSSAPI wrapper for the W2K Kerberos SSP. NOTE! Getting host-based service names to work on Windows 2000 is a little tricky, and as W2K doesn't support MIT-style keytabs, hostbased service names do *NOT* work with non-Microsoft KDCs. When using a Microsoft KDC (i.e. a W2K-Domain) then hostbased service names are not regular principals, but aliases for regular W2K-Accounts. The Microsoft KDC can cheat when issuing tickets and stuff the hostbased service name alias into tickets to make traditional Kerberos clients happy. 4.) Additional Information for Microsoft W2K Kerberos Interoperability ====================================================================== There's a Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability available from Microsoft. Go to http://www.microsoft.com and search for "ksetup". KSETUP.EXE along with KTPASS.EXE are two command line tools that are shipped on W2K CDs in the archive-file \SUPPORT\TOOLS\SUPPORT.CAB Keep in mind that changes to the Kerberos configuration with KSETUP.EXE usually require a reboot to take effect. as in "Your mouse pointer has moved, please reboot for changes to take effect". 5.) Tested functionality ======================== I'm simply lacking the time to list each and every feature here. I have build a gssapi test program that tests all the functionality our application needs. I have planned to make this program generally available (removing all the SAP-specific tests and complaints), however I still need some more time. The current SAP R/3 interoperability test tool is available through our public FTP-Server from the following directory: ftp://ftp.sap.com/pub/ietf-work/gssapi/gsstest/ gsstest-1.26.zip 381 KB Sep 03 20:24 gsstest-1.26.zip.asc 284 bytes Sep 03 20:24 It is distributed as source, but also includes a Win32 Binary of gsstest.exe and a gssntlm.dll. 6.) Missing and untested GSS-API features ========================================= This list is from a quick scan of my memories, and incomplete and outdated... :-o name handling: -------------- (hostbased) service names: implemented -- however WATCHOUT, they're INSECURE!! rfc1964 lists hostbased service names but fails to define how these should be transformed into a Kerberos principal name. There are 4 issues with resolving "service@hostname": (1) how service names are canonicalized/transformed (2) how hostnames are canonicalized/transformed (3) how a Kerberos REALM is determined (4) how a Kerberos principal name is created from above components. This implementation performs the following: (1) service names are copied literally (2) hostnames are canonicalized via INSECURE DNS and lowercased, as it is proposed in rfc2743, section 4.1 and as it is done by MIT's Kerberos 5 v1.0.x and v1.1.x implementations. (3) The realm is determined with a similar strategy as described for the [domain_realm] section of krb5.conf in MIT Kerberos 5 v1.1. However the [domain_realm] information is actually parsed from the registry and not from a file. The registry key is "HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\HostToRealm" I don't know whether this has been officially documented yet, but this location and its interpretation was proposed by Microsoft's Kerberos development team during Email disucussion. (4) The resulting Kerberos principal name is formed from the components as "service/f.q.d.n@SOME-REALM" Additional Notes for (3): You can supply "domain->realm" mappings as well as "host->realm" mappings; a leading dot "." will indicate that it is a DNS-domain. domain and hostname matching is performed case-insensitive. When searching through the values, the longest match will be used (Remind that registry values under a key are unordered). The realm name will be copied literally, it will not be uppercased! The general Kerberos convention is to use uppercase Realms, however some people are using lower or mixed case realms and therefore this wrapper uses the case as specified in the mapping table (registry). If there is neither a matching domain nor a matching host mapping defined, the *uppercased* DNS domain name of the f.q.d.n will be used as the realm name. Unicode User names: missing rfc1964 doesn't define how to deal with non-ASCII usernames, therefore I didn't implement them either. When a spec becomes available how to deal with Unicode Kerberos names, then I will probably update this code. credential management: ---------------------- credential "verification": This wrapper attempts to verify whether credentials can really be acquired. Since AcquireCredentialsHandle() for the Kerberos SSP does not perform any checks, the wrapper will try to establish a security context with itself to find out whether credentials for a given name can really be acquired. BEWARE: this causes an overhead of a few milliseconds and requires the acquisition of a ticket, even for the acceptor. If you don't like this, you can change krb5/krb5cred.c:318 from "#if 1" to "#if 0" before compiling this code. server credentials (server keys) INCOMPLETE/MISSING Accepting security contexts with a User's credentials work fine. However, the client must use the Users account name as target name! Although it is possible to define a mapping of a service-principal name (like "service/f.q.d.n") to an W2K account with KSETUP, this service name can only be used as a target name when an Active Directory (i.e. an NT5 Domain) is present. It will *NOT* work with a standalone W2K pro Workstation attached to an MIT-style KDC (even though it can be defined). Machine ("host") server credentials (accepting credentials) in general don't seem to work with W2K Kerberos. Although each W2K machine has a "host" service account and host-based credentials for this service, these credentials are only available for processes running as "LocalSystem". I haven't yet bothered to make this work. W2K doesn't have keytabs, and the Feb'2000 release of W2K doesn't allow to import keys as they're stored in a MIT-Kerberos style keytab. In contrast to MIT Kerberos, the credentials of an interactive user session can be used to accept security contexts because the long term secret (=password) of the user is cached on Microsoft Windows Platforms. Default accepting credentials under W2K differ from MIT Kerberos. With W2K, default accepting credentials are always the credentials of the current thread, usually for the logged-on user. With MIT Kerberos, the default accepting credentials always resolve to "host/f.q.d.n". However credentials for this identity are normally not accessible by non-root users. gss_add_cred() is missing. (You shouldn't be using it anyway.) This GSS-API v2 call is the only call that I consider broken/mis-spec'd. However it was to late to change the spec when I realized how broken it is. Anyway -- I have not implemented this call, and I really don't feel like ever doing it. GSS_C_BOTH type credentials are not supported. Only GSS_C_INITIATE and GSS_C_ACCEPT are implemented; an application should always know which kind of credentials it needs for context establishment. Credential delegation (TGT forwarding) acceptor side is UNTESTED!! The initiator side of credential delegation should be working. However for W2K to permit credential delegation, the target may need a "clearance". Individual service principals in Microsoft's active directory may need to be configured with "trusted for delegation" to make this happen. It is possible to allow delegation to all principals of a REALM by adding "RealmFlags = REG_DWORD 4" to the Registry under the key "HKLM\SYSTEM\CurrentControlSet\Control\LSA\Kerberos\Domains\YOUR-REALM" According to Microsoft, information on this is available in the ResKit for W2K online docs: Start->Programs->Windows 2000 Resource Kit-> Documentation->Registry Reference I have added some code (bending the internal layer seperation) for the acceptor side of credential delegation which should be able to return a handle for a delegated credential. However I have never used credential delegation and not tested this functionality at all -- good luck! context establishment: ---------------------- Channel Bindings are not implemented in Microsoft W2K Kerberos, therefore they're not available through this wrapper. You will get an error returned when you supply a channel bindings parameter to gss_init_sec_context() or gss_accept_sec_context(). (Maybe this feature is added with a later W2K service pack...) I have never tested target-only authentication (without the GSS_C_MUTUAL_FLAG). The underlying W2K Kerberos SSP seems to support it. GSS_C_PROT_READY_FLAG: Currently this code doesn't return it at all, and I haven't checked whether/how the W2K Kerberos SSP supports it (i.e. message protection availability prior to full context establishment). Sequence/Replay detection: The sequence and replay detection implemented by the W2K Kerberos SSP is fairly simple, it uses a sequence number for each direction. Therefore, if data replay detection is requested, data sequencing will be additionally provided/enforced. This code does not transfer KERB_ERROR tokens. Although such tokens are allowed by the rfc1964 spec and produced by the W2K Kerberos SSP, this code will at most emit two context level tokens for a context establishment handshake with mutual authentication. When using an invalid target name, W2K Kerberos seems to return a KERB_ERROR token from AcceptSecurityContext() while MIT Kerberos will recognize the wrong target name immediately and abort with an error like "wrong principal in request". If one would let W2K Kerberos carry on the token exchange, it would make two full roundtrips, returning the same KERB_ERROR message twice before the initiator aborts with the correct error message. I personally strongly prefer the MIT Kerberos behaviour and my wrapper will currently abort when AcceptSecurityContext() returns CONTINUE_NEEDED with a minor_status that gss_display_status() visualizes as "SSPI talks garbage (maybe wrong target name?)" Microsoft's proprietary user2user 3-token security context establishment is not currently supported by gsskrb5.dll It can be requested with the ISC_REQ_USE_SESSION_KEY context attribute, it has been available in Windows2000 Kerberos already and it is "enforced" for plain user accounts in Windows 2003 domains when running at "windows 2003" domain functional level (instead of "Windows 2000 mixed") New error codes&text have been added to specifically identify the situation when Microsoft's Kerberos SSP tries to perform a user2user token exchange which gsskrb5.dll does not (currently) support. If a service principal is defined for a (service) account, then the regular 2-token authentication exchange from rfc-1964/rfc-4121 can be used. The command line tool "setspn" from the SUPPORT.CAB on the OS installation CD can be used to flip the necessary bit in the Microsoft Active Directory to re-enable rfc-1964 conforming 2-token authentication exchanges, e.g. SETSPN -A SAPServiceC11/dontcare NT4DOMAIN\SAPServiceC11 to enable it for account "NT4DOMAIN\SAPServiceC11" It really doesn't matter what the service principal looks like, -- it is not being used by SAP, because it only works for accepting security contexts, not for initiating security context--this is because Service Principals are not real Kerberos principals in Microsoft Kerberos, instead they're only aliases to real accounts. Microsoft seems to have shipped a few defective Versions of SETSPN.exe that fail to parse the NT4DOMAIN\SAPServiceC11 account syntax, these seem to accept only plain account names in the current domain...