doc/gssapi.html

   1 <HTML><HEAD>
   2 <title>Configuring GSSAPI and Cyrus SASL</title>
   3 <!-- $Id: gssapi.html,v 1.4 2003/09/24 18:54:05 rjs3 Exp $ -->
   4 </HEAD>
   5 <BODY>
   6 <h1>Configuring GSSAPI and Cyrus SASL</h1>
   7
   8 <p>This document was contributed by <a
   9 href="mailto:kenh@cmf.nrl.navy.mil">Ken Hornstein</a> and updated
  10 by <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
  13 GSSAPI 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
  17 how you get GSSAPI working with the sample apps, since it wasn't
  18 obvious to me, and I consider myself not completely ignorant of GSSAPI
  19 and 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
  36 on UNIX and like
  37
  38 <pre>  sample-server -s host -p ..\plugins
  39 </pre>
  40
  41 on 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
 140 you 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!
 190 If you have questions about any of this, feel free to drop me a line.
 191
 192 <hr>
 193 Back to the <A href=index.html>index</a>
 194
 195 </body>
 196 </html>