1<HTML><HEAD> 2<title>Configuring GSSAPI and Cyrus SASL</title> 3<!-- $Id: gssapi.html,v 1.6 2006/01/20 20:15:07 snsimon Exp $ --> 4</HEAD> 5<BODY> 6<h1>Configuring GSSAPI and Cyrus SASL</h1> 7 8<p>This document was contributed by <a 9href="mailto:kenh@cmf.nrl.navy.mil">Ken Hornstein</a> and updated 10by <a href="mailto:Alexey.Melnikov@isode.com">Alexey Melnikov</a>. 11 12<p>A couple of people have asked me privately, "Hey, how did you get the 13GSSAPI mechanism to work? I tried, but the sample apps kept failing". 14(The short answer: I'm a tenacious bastard). 15 16<p>I figured that it couldn't hurt to give a quick explanation as to 17how you get GSSAPI working with the sample apps, since it wasn't 18obvious to me, and I consider myself not completely ignorant of GSSAPI 19and Kerberos. 20 21<ol> 22<li> Compile the Cyrus-SASL distribution with the GSSAPI plugin 23 for your favorite GSS-API mechanism. I personally use the GSSAPI 24 libraries included with the <a href="http://web.mit.edu/kerberos/www/">MIT</a> 25 Kerberos 5 distribution; <a href="http://www.pdc.kth.se/heimdal/">Heimdal</a> 26 and <a href="http://www.cybersafe.com/">CyberSafe</a> work as well. 27 28<li> Start up the sample-server. The command-line used for 29 sample-server needs to specify the GSSAPI service name and the 30 location of the plug-ins; your sample command line might look 31 something like this: 32 33<pre> /sample-server -s host -p /plugins/.libs 34</pre> 35 36on UNIX and like 37 38<pre> sample-server -s host -p ..\plugins 39</pre> 40 41on Windows. 42 43 44<p> In this example, I am using "host", which already exists on my 45 machine, <i>but</i> only root can read it, so I an running this as root. 46 If you want to use an alternate service name, you will need to 47 create that service in Kerberos, place it in a keytab readable by 48 you, _and_ point your Kerberos library at it. 49 50 Unix: both MIT Kerberos and Heimdal, 51 use /etc/krb5.keytab on Unix by default, but this can be changed 52 by setting the <tt>KRB5_KTNAME</tt> environment variable; the default 53 for CyberSafe Kerberos is /krb5/v5srvtab for UNIX systems and can be 54 changed by setting the <tt>CSFC5KTNAME</tt> environment variable. 55 56 Windows: the default service key table location for CyberSafe is 57 C:\Program Files\CyberSafe\v5srvtab, unless the 58 CyberSafe registry setting for the KeyTab key is set to an 59 alternate path. MIT Kerberos on Windows uses the keytab filename 60 krb5kt. 61 62<p> You should get a response similar to: 63 64<pre> Generating client mechanism list... 65 Sending list of 3 mechanism(s) 66 S: R1NTQVBJIFBMQUlOIEFOT05ZTU9VUw== 67</pre> 68 69<p> Note that later on (assuming everything works) you might need to paste 70 in lines that are longer than canonical input processing buffer on your 71 system. You can get around that by messing around with stty; while 72 the details vary from system to system, on Solaris you can do something 73 like: 74 75<pre> ( stty -icanon min 1 time 0 ; /sample-server -s host -p /plugins/.libs ) 76</pre> 77 78<li> Obtain a Kerberos ticket for the user you want to authenticate as. 79 80<pre> kinit kenh 81</pre> 82 83 84<li> Start up the sample client. You need to specify the service 85 name, the hostname, and the userid. An example might be 86 87<pre> /sample-client -s host -n your.fqdn.here -u kenh -p /plugins/.libs 88</pre> 89 90<p> You should get a response similar to this: 91 92<pre> Waiting for mechanism list from server... 93</pre> 94 95<li> Cut-and-paste the initial mechanism line from the server process 96 (this <i>includes</i> the "<tt>S: </tt>") into the client process. You 97 should get something similar to: 98 99<pre> S: R1NTQVBJIFBMQUlOIEFOT05ZTU9VUw== 100 Choosing best mechanism from: GSSAPI PLAIN ANONYMOUS 101 Using mechanism GSSAPI 102 Preparing initial. 103 Sending initial response... 104 C: <.... lots of base 64 data ...> 105 Waiting for server reply... 106</pre> 107 108<p> If GSSAPI isn't selected as the mechanism, there is a few things that 109 might have gone wrong: 110 111<ul> 112<li> The mechanism might not have been offered by the server. The decoded 113 mechanism list offered by the server appears in the "<tt>Choosing best 114 mechanism</tt>" line. If GSSAPI didn't appear in that list, then 115 something is wrong on the server. Make sure that you specified the 116 correct plugins directory. If the plugin directory is correct, but 117 the library fails to load, you <i>might</i> be running across a bug 118 in libtool on some platforms. If you have your Kerberos/gssapi 119 libraries not installed in the system library path, those libraries 120 are likely not able to be found when the SASL GSSAPI plugin loads. 121 The solution varies from system to system; what I did was take 122 the linker line generated by libtool and run it by hand, adding 123 a <tt>-R/path/to/kerberos/libraries</tt> switch (this was on Solaris). 124 You can check with a system call tracer to see exactly what it is 125 trying to do. 126 127<li> The client doesn't know about the mechanism. The reasons for this 128 happening are the same as the server: check the -p switch, check 129 to make sure the correct libraries are being loaded with the GSSAPI 130 plugin. 131</ul> 132 133<p> You can turn on a healthy amount of debugging information by changing 134 the definition in config.h of the VL macro to (and recompiling libsasl): 135 136<pre> #define VL(foo) printf foo; 137</pre> 138 139<p> There is a possibility 140you might get an error that looks like this: 141 142<pre> sample-client: Starting SASL negotiation: generic failure 143</pre> 144 145<p> This can mean that you didn't provide all of the required information 146 to the sample-client (did you provide a service name with -s, the 147 hostname of the service with -n, and a username with -u ?), or that 148 GSSAPI has failed (unfortunately, on the client you cannot find out 149 the internal GSSAPI error; you will need to break out the debugger 150 for that). 151 152<li> Cut and paste the client response (The _entire_ line that begins 153 with C:, <i>including</i> the initial "<tt>C: </tt>") to the server 154 process. You should get a response back that starts with "<tt>S: 155 </tt>". Cut and paste <i>that</i> to the client, and continue this 156 exchange until you either get "<tt>Negotiation complete</tt>", or an error. 157 If you get an error on the server you should get a complete error 158 message (including the GSSAPI error string); on the client you 159 unfortunately will only probably get "<tt>generic failure</tt>", which will 160 again require the use of a debugger (but the VL macro should help 161 with this). 162 163<p> One common thing that happens is that on your server you might see 164 the error: 165 166<pre> sample-server: Performing SASL negotiation: authentication failure 167 (Requested identity not authenticated identity) 168</pre> 169 170<p> This comes from not having a requested identity (the -u option) that 171 matches the identity that you were authenticated to via the GSSAPI. 172 This is of course mechanism specific, but if for example you're using 173 Kerberos, the Cyrus SASL library strips out the @REALM from your 174 identity <i>if</i> you are in the same realm as the server. So if your 175 Kerberos identity is user@SOME.REALM and the server is in SOME.REALM, 176 you need to specify "user" to the -u flag of the client. If you're 177 accessing a server in a foreign realm, you need to pass the full 178 principal name via the -u option to make this work correctly. 179 180<p> If you complete the negotiation successfully, you should see something 181 that looks like (on both the client and server): 182 183<pre> Negotiation complete 184 Username: kenh 185 sample-server: realm: can't request info until later in exchange 186 SSF: 56 187</pre> 188 189<p> If you get to that, then you've done it, and GSSAPI works successfully! 190If you have questions about any of this, feel free to drop me a line. 191 192<hr> 193Back to the <A href=index.html>index</a> 194 195</body> 196</html> 197