WWWWWW

Current Directory: /usr/share/doc/cyrus-sasl-lib-2.1.26
Viewing File: /usr/share/doc/cyrus-sasl-lib-2.1.26/gssapi.html
<HTML><HEAD>
<title>Configuring GSSAPI and Cyrus SASL</title>
<!-- $Id: gssapi.html,v 1.4 2003/09/24 18:54:05 rjs3 Exp $ -->
</HEAD>
<BODY>
<h1>Configuring GSSAPI and Cyrus SASL</h1>

<p>This document was contributed by <a
href="mailto:kenh@cmf.nrl.navy.mil">Ken Hornstein</a> and updated
by <a href="mailto:Alexey.Melnikov@isode.com">Alexey Melnikov</a>.

<p>A couple of people have asked me privately, "Hey, how did you get the
GSSAPI mechanism to work?  I tried, but the sample apps kept failing".
(The short answer: I'm a tenacious bastard).

<p>I figured that it couldn't hurt to give a quick explanation as to
how you get GSSAPI working with the sample apps, since it wasn't
obvious to me, and I consider myself not completely ignorant of GSSAPI
and Kerberos.

<ol>
<li> Compile the Cyrus-SASL distribution with the GSSAPI plugin
  for your favorite GSS-API mechanism.  I personally use the GSSAPI
  libraries included with the <a href="http://web.mit.edu/kerberos/www/">MIT</a>
  Kerberos 5 distribution; <a href="http://www.pdc.kth.se/heimdal/">Heimdal</a>
  and <a href="http://www.cybersafe.com/">CyberSafe</a> work as well.

<li> Start up the sample-server.  The command-line used for
  sample-server needs to specify the GSSAPI service name and the
  location of the plug-ins; your sample command line might look
  something like this:

<pre>  ./sample-server -s host -p ../plugins/.libs
</pre>

on UNIX and like

<pre>  sample-server -s host -p ..\plugins
</pre>

on Windows.


<p> In this example, I am using "host", which already exists on my
  machine, <i>but</i> only root can read it, so I an running this as root.
  If you want to use an alternate service name, you will need to
  create that service in Kerberos, place it in a keytab readable by
  you, _and_ point your Kerberos library at it.

  Unix: both MIT Kerberos and Heimdal, 
  use /etc/krb5.keytab on Unix by default, but this can be changed
  by setting the <tt>KRB5_KTNAME</tt> environment variable; the default
  for CyberSafe Kerberos is /krb5/v5srvtab for UNIX systems and can be
  changed by setting the <tt>CSFC5KTNAME</tt> environment variable.

  Windows: the default service key table location for CyberSafe is
  C:\Program Files\CyberSafe\v5srvtab, unless the
  CyberSafe registry setting for the KeyTab key is set to an
  alternate path. MIT Kerberos on Windows uses the keytab filename
  krb5kt.

<p>  You should get a response similar to:

<pre>  Generating client mechanism list...
  Sending list of 3 mechanism(s)
  S: R1NTQVBJIFBMQUlOIEFOT05ZTU9VUw==
</pre>

<p>  Note that later on (assuming everything works) you might need to paste
  in lines that are longer than canonical input processing buffer on your
  system.  You can get around that by messing around with stty; while
  the details vary from system to system, on Solaris you can do something
  like:

<pre>  ( stty -icanon min 1 time 0 ; ./sample-server -s host -p ../plugins/.libs )
</pre>

<li> Obtain a Kerberos ticket for the user you want to authenticate as.

<pre>  kinit kenh
</pre>


<li> Start up the sample client.  You need to specify the service
  name, the hostname, and the userid.  An example might be

<pre>  ./sample-client -s host -n your.fqdn.here -u kenh -p ../plugins/.libs
</pre>

<p>  You should get a response similar to this:

<pre>  Waiting for mechanism list from server...
</pre>

<li> Cut-and-paste the initial mechanism line from the server process
  (this <i>includes</i> the "<tt>S: </tt>") into the client process.  You
  should get something similar to:

<pre>  S: R1NTQVBJIFBMQUlOIEFOT05ZTU9VUw==
  Choosing best mechanism from: GSSAPI PLAIN ANONYMOUS
  Using mechanism GSSAPI
  Preparing initial.
  Sending initial response...
  C: <.... lots of base 64 data ...>
  Waiting for server reply...
</pre>

<p>  If GSSAPI isn't selected as the mechanism, there is a few things that
  might have gone wrong:

<ul>
<li> The mechanism might not have been offered by the server.  The decoded
     mechanism list offered by the server appears in the "<tt>Choosing best
     mechanism</tt>" line.  If GSSAPI didn't appear in that list, then
     something is wrong on the server.  Make sure that you specified the
     correct plugins directory.  If the plugin directory is correct, but
     the library fails to load, you <i>might</i> be running across a bug
     in libtool on some platforms.  If you have your Kerberos/gssapi
     libraries not installed in the system library path, those libraries
     are likely not able to be found when the SASL GSSAPI plugin loads.
     The solution varies from system to system; what I did was take
     the linker line generated by libtool and run it by hand, adding
     a <tt>-R/path/to/kerberos/libraries</tt> switch (this was on Solaris).
     You can check with a system call tracer to see exactly what it is
     trying to do.

<li> The client doesn't know about the mechanism.  The reasons for this
     happening are the same as the server: check the -p switch, check
     to make sure the correct libraries are being loaded with the GSSAPI
     plugin.
</ul>

<p>  You can turn on a healthy amount of debugging information by changing
  the definition in config.h of the VL macro to (and recompiling libsasl):

<pre>  #define VL(foo) printf foo;
</pre>

<p> There is a possibility
you might get an error that looks like this:

<pre>  sample-client: Starting SASL negotiation: generic failure
</pre>

<p>  This can mean that you didn't provide all of the required information
  to the sample-client (did you provide a service name with -s, the
  hostname of the service with -n, and a username with -u ?), or that
  GSSAPI has failed (unfortunately, on the client you cannot find out
  the internal GSSAPI error; you will need to break out the debugger
  for that).

<li> Cut and paste the client response (The _entire_ line that begins
  with C:, <i>including</i> the initial "<tt>C: </tt>") to the server
  process.  You should get a response back that starts with "<tt>S:
  </tt>".  Cut and paste <i>that</i> to the client, and continue this
  exchange until you either get "<tt>Negotiation complete</tt>", or an error.
  If you get an error on the server you should get a complete error
  message (including the GSSAPI error string); on the client you
  unfortunately will only probably get "<tt>generic failure</tt>", which will
  again require the use of a debugger (but the VL macro should help
  with this).

<p>  One common thing that happens is that on your server you might see
  the error:

<pre>  sample-server: Performing SASL negotiation: authentication failure
	(Requested identity not authenticated identity)
</pre>

<p>  This comes from not having a requested identity (the -u option) that
  matches the identity that you were authenticated to via the GSSAPI.
  This is of course mechanism specific, but if for example you're using
  Kerberos, the Cyrus SASL library strips out the @REALM from your
  identity <i>if</i> you are in the same realm as the server.  So if your
  Kerberos identity is user@SOME.REALM and the server is in SOME.REALM,
  you need to specify "user" to the -u flag of the client.  If you're
  accessing a server in a foreign realm, you need to pass the full
  principal name via the -u option to make this work correctly.

<p>  If you complete the negotiation successfully, you should see something
  that looks like (on both the client and server):

<pre>  Negotiation complete
  Username: kenh
  sample-server: realm: can't request info until later in exchange
  SSF: 56
</pre>

<p> If you get to that, then you've done it, and GSSAPI works successfully!
If you have questions about any of this, feel free to drop me a line.

<hr>
Back to the <A href=index.html>index</a>

</body>
</html>
F1l3 Manager
