cyrus-sasl.txt

   1 AUTHOR:   Randy McMurchy <LFS-User_at_mcmurchy_dot_com>
   2
   3 DATE:     2004-05-05
   4
   5 LICENSE:  Creative Commons Attribution-NonCommercial-ShareAlike License
   6           http://creativecommons.org/licenses/by-nc-sa/1.0/
   7
   8 SYNOPSIS: Installing Cyrus-SASL and testing the GSSAPI authentication mechanism
   9
  10 DESCRIPTION:
  11
  12 This hint will guide you through the installation of Cyrus-SASL, then guide
  13 you through testing your Kerberos 5 GSSAPI authentication mechanism
  14 functionality using the Cyrus-SASL sample-server and sample-client
  15 applications.
  16
  17 ATTACHMENTS:
  18
  19 none
  20
  21 PREREQUISITES:
  22
  23 For the purposes of this hint, you must have a Kerberos 5 installation on the
  24 machine you are installing Cyrus-SASL on. Cyrus-SASL does not require a
  25 Kerberos installation, however this hint is based on testing the GSSAPI
  26 authentication mechanism provided by a Cyrus-SASL/Kerberos 5 combination.
  27
  28 My testing was with the Heimdal Kerberos 5 package, though the MIT Kerberos 5
  29 package should work equally well. You can find a hint for deploying the
  30 Heimdal Kerberos 5 package on your network at:
  31 http://www.linuxfromscratch.org/hints/downloads/files/heimdal.txt
  32
  33 HINT:
  34
  35 =========
  36 CONTENTS:
  37 =========
  38
  39         1. Introduction
  40         2. Package Dependencies
  41             Required
  42             Optional
  43         3. Package Installation
  44             Download the package
  45             Configure the build
  46             Build the package
  47             Checking the build
  48             Install the package
  49             Update /etc/ld.so.cache
  50             Stripping the binaries
  51             Installation modifications
  52         4. Package Configuration
  53         5. Testing Cyrus-SASL/GSSAPI
  54             Create the test programs
  55             Notes about the test
  56             Get a Kerberos authentication ticket
  57             Starting the test server
  58             Starting the test client
  59             Starting the negotiation
  60             Possible problem
  61             Continuing the negotiation
  62             Results analysis
  63         6. Issues, Gotchas and Other Sundry Items
  64         7. To Do List
  65         8. Closing
  66
  67 ================
  68 1. INTRODUCTION:
  69 ================
  70
  71 These instructions should allow you to build and install Cyrus-SASL, then
  72 test the installation using your Kerberos 5 GSSAPI authentication mechansim.
  73 The testing is performed using the Cyrus-SASL sample-client and sample-server
  74 applications.
  75
  76 Cyrus-SASL is an authentication "layer" which provides a secure interface
  77 from an application to an authentication mechanism. Cyrus-SASL provides an
  78 interface to many different authentication mechanisms, however, this hint is
  79 based on authentication using the Kerberos 5 GSSAPI.
  80
  81 If you have any plans of integrating Kerberos with OpenLDAP, you'll need
  82 the Cyrus-SASL GSSAPI functionality.
  83
  84 First off, you should already have a functional Kerberos installation. This
  85 could be the MIT or Heimdal variations, both should work equally well with
  86 Cyrus-SASL. My testing is with the Heimdal Kerberos 5 package, so if anyone
  87 is using the MIT version and completes this hint (sample-server and
  88 sample-client testing checks out), please let me know. I'll update the hint
  89 to reflect MIT Kerberos as checked out.
  90
  91 There's a hint for deploying the Heimdal Kerberos 5 package on your network.
  92 You can find the Heimdal hint at:
  93 http://www.linuxfromscratch.org/hints/downloads/files/heimdal.txt
  94
  95 ========================
  96 2. PACKAGE DEPENDENCIES:
  97 ========================
  98
  99 ---------
 100 Required:
 101 ---------
 102
 103 heimdal-0.6.1 or MIT Kerberos5 (for this hint, not required for plain
 104 Cyrus-SASL installation)
 105
 106 ---------
 107 Optional:
 108 ---------
 109
 110 J2SDK-1.4.2, Linux-PAM-0.77, MySQL-4.0.18, PostgreSQL-7.4.2
 111
 112 Additionally, an optional dependency of Heimdal is OpenLDAP-2.1.30. For the
 113 purposes of this hint, OpenLDAP should be installed *after* Cyrus-SASL. If
 114 your intention is simply to store the Cyrus-SASL saslauthd information in
 115 LDAP, and not use SASL authentication mechanisms with LDAP, you should
 116 install LDAP first.
 117
 118 ========================
 119 3. PACKAGE INSTALLATION:
 120 ========================
 121
 122 ---------------------
 123 Download the package:
 124 ---------------------
 125
 126 The current stable package is cyrus-sasl-2.1.18 and can be downloaded using
 127 the following URL's:
 128
 129 Anonymous FTP:
 130 ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/cyrus-sasl-2.1.18.tar.gz
 131
 132 HTTP:
 133 http://ftp.andrew.cmu.edu/pub/cyrus-mail/cyrus-sasl-2.1.18.tar.gz
 134
 135 --------------------
 136 Configure the Build:
 137 --------------------
 138
 139 First run the configure script. I used many options to the script, some of
 140 which may not have been necessary. Omit any as you see fit.
 141
 142 ***WARNING*** DO NOT TRY TO CREATE STATIC LIBRARIES USING --enable-static
 143
 144 I spent a couple of hours trying to figure out why Open-LDAP would not build
 145 correctly after installing Cyrus-SASL. It turns out the libtool script Cyrus
 146 provides is broken. Cyrus-SASL will build and install using --enable-static,
 147 however, Open-LDAP will *not* build against this installation.
 148
 149 Cyrus is aware of the problem, and the above mentioned is listed as a known
 150 bug (with different wording) on the Cyrus web site.
 151
 152 Configure the build:
 153
 154 ./configure --prefix=/usr \
 155     --sysconfdir=/etc \
 156     --localstatedir=/var/lib/sasl \
 157     --with-dbpath=/var/lib/sasl \
 158     --with-saslauthd=/var/lib/sasl \
 159     --with-openssl=/usr
 160
 161 Here's my reasoning with the options to ./configure.
 162
 163 --prefix=/usr will install the libraries in /usr/lib and the programs in
 164 /usr/sbin
 165
 166 --sysconfdir=/etc insures that any configuration files required by Cyrus-SASL
 167 are looked for in /etc.
 168
 169 --localstatedir=/var/lib/sasl is used to point to the run-time files created
 170 and used by saslauthd. In an environment where Cyrus-SASL is used strictly as
 171 a GSSAPI authentication layer, the saslauthd daemon is not used and this
 172 option may be left off.
 173
 174 --with-dbpath=/var/lib/sasl is where the Cyrus-SASL authentication database
 175 is located. In an environment where Cyrus-SASL is used strictly as a GSSAPI
 176 authentication layer, no database is required and this option may be left
 177 off.
 178
 179 --with-saslauthd=/var/lib/sasl is where the saslauthd daemon stores its named
 180 socket. In an environment where Cyrus-SASL is used strictly as a GSSAPI
 181 authentication layer, the saslauthd daemon is not used and this option may be
 182 left off.
 183
 184 --with-openssl=/usr tells configure where to find OpenSSL.
 185
 186 ------------------
 187 Build the Package:
 188 ------------------
 189
 190 Simply running the "make" command will build the package.
 191
 192 -------------------
 193 Checking the Build:
 194 -------------------
 195
 196 There are no "check" rules in the various subdirectory makefiles, so there's
 197 nothing to check. Running the "make check" command is pointless. We'll check
 198 the build during the testing.
 199
 200 --------------------
 201 Install the Package:
 202 --------------------
 203
 204 ****************************************************************************
 205 *****                                                                  *****
 206 *****  The remainder of this hint must be performed by the root user   *****
 207 *****                                                                  *****
 208 ****************************************************************************
 209
 210 Simply issue a "make install" command to install the package.
 211
 212 ------------------------
 213 Update /etc/ld.so.cache:
 214 ------------------------
 215
 216 Update the linker's library cache file by issuing the "ldconfig" command:
 217
 218 ldconfig -v
 219
 220 -----------------------
 221 Stripping the Binaries:
 222 -----------------------
 223
 224 If desired, strip the unnecessary symbols from the installed binaries by
 225 issuing the following commands:
 226
 227 strip --strip-all /usr/sbin/saslpasswd2 \
 228     /usr/sbin/sasldblistusers2 /usr/sbin/saslauthd
 229 strip --strip-debug /usr/lib/libsasl2.so.2.0.18
 230 find /usr/lib/sasl2 -type f -exec strip --strip-debug {} \;
 231
 232 ---------------------------
 233 Installation Modifications:
 234 ---------------------------
 235
 236 The instructions provided by Cyrus say to provide a symbolic link from
 237 wherever you installed the sasl2 library directory to /usr/lib/sasl2. Because
 238 we used --prefix=/usr and installed the libraries directly into
 239 /usr/lib/sasl2, this step is not required.
 240
 241 =========================
 242 4. PACKAGE CONFIGURATION:
 243 =========================
 244
 245 There is no configuration required for the Cyrus-SASL package as used in this
 246 hint. If you are installing Cyrus-SASL for reasons other than used in this
 247 hint, there is probably some configuration involved.
 248
 249 =============================
 250 5. TESTING CYRUS-SASL/GSSAPI:
 251 =============================
 252
 253 This section will run a client-server test of Cyrus-SASL's ability to
 254 communicate with your installed Kerberos 5 installation using the GSSAPI.
 255 Note you must have a fully functional Kerberos 5 installation before this
 256 test will succeed. By fully functional, I mean you must have Kerberos
 257 installed, a valid krb5.keytab file and least one user principal identified
 258 in the Kerberos database. Additionally, the kdc daemon must be running.
 259
 260 The tests should be run by the root user as a direct read of the krb5.keytab
 261 file is necessary and only root should have access to this file.
 262
 263 -------------------------
 264 Create the Test Programs:
 265 -------------------------
 266
 267 Change directories to the first-level deep "sample" subdirectory in the
 268 cyrus-sasl-2.1.18 source tree.
 269
 270 The sample-client and sample-server programs were not created during the
 271 package build, so we must create them now. Issue the following commands:
 272
 273 make sample-client
 274 make sample-server
 275
 276 You should now have "sample-server" and "sample-client" programs in the
 277 current directory.
 278
 279 ---------------------
 280 Notes About the Test:
 281 ---------------------
 282
 283 Throughout the test, we'll be using two different terminals to emulate a
 284 "server" and a "client". Both terminals should be logged in as root from the
 285 machine where Kerberos5 and Cyrus-SASL are installed. One of the terminals is
 286 ready now if you've followed the instructions and created the test programs.
 287 We'll use this one as the "server". You'll need to open a new terminal window
 288 on the same machine and use this terminal as the "client".
 289
 290 We'll be sending commands to the server and clients by cutting and pasting
 291 from one window to the other. The server and client will "talk" to one
 292 another with you acting as the interpreter. The "server" will send a response
 293 starting with "S:". You'll need to copy the entire line (including the S:)
 294 into the client window to send a command from the server to the client.
 295
 296 Likewise, you copy the line starting with "C:" from the client window into
 297 the server window to continue the negotiation between server and client.
 298
 299 Note: Some of the lines I show here in this hint are truncated to stay within
 300 the bounds of an 80-column display. The real responses are very long, and
 301 would extend way past 80 chars.
 302
 303 -------------------------------------
 304 Get a Kerberos Authentication Ticket:
 305 -------------------------------------
 306
 307 Get a ticket from any valid user in the Kerberos database using the "kinit"
 308 program. This is the "user" you will use during the tests.
 309
 310 -------------------------
 311 Starting the Test Server:
 312 -------------------------
 313
 314 Issue the following command to start the server:
 315
 316 ./sample-server -s host -p ../plugins/.libs
 317
 318 You should get a response similar to:
 319
 320 Generating client mechanism list...
 321 Sending list of 6 mechanism(s)
 322 S: QU5PTllNT1ABCDEMQUlOEdTU0FQSSBPVFAgRElHRVNULU1ENSBDUkFNLU1ENQ==
 323 Waiting for client mechanism...
 324
 325 -------------------------
 326 Starting the Test Client:
 327 -------------------------
 328
 329 Change to the sample sub-directory of the cyrus-sasl-2.1.18 source tree and
 330 issue the following command:
 331
 332 ./sample-client -s host -n belgarath.lfs.org -u user -p ../plugins/.libs
 333
 334 Of course, substitute the FQDN of your machine for "belgararth.lfs.org" and
 335 the username of the user you got the authentication ticket for earlier. You
 336 should get a response similar to:
 337
 338 service=host
 339 Waiting for mechanism list from server...
 340
 341 -------------------------
 342 Starting the Negotiation:
 343 -------------------------
 344
 345 >From here on out, I'm simply going to cut and paste the responses back and
 346 forth between server and client and show the output. We'll start by copying
 347 the line from the server window starting with "S:" into the client window.
 348 You must, of course, hit return after you've pasted the data.
 349
 350 S: QU5PTllNT1ABCDEMQUlOEdTU0FQSSBPVFAgRElHRVNULU1ENSBDUkFNLU1ENQ==
 351
 352 The client should respond with something similar to:
 353
 354 recieved 46 byte message
 355 Choosing best mechanism from: ANONYMOUS PLAIN GSSAPI OTP DIGEST-MD5 CRAM-MD5
 356 returning OK: user
 357 Using mechanism GSSAPI
 358 Preparing initial.
 359 Sending initial response...
 360 C: R1NTQVBJAGCCAiEGCSqGABCDEgECAgEAboICEDCCAygAwIBBaEDAgEOogcDBQAgAAAAo4IBKG
 361 GCASQwggEgoAMCAQWhDhsMTUNNVVJDSFkuUFJWoicwJaADAgEBoR4wHBsEaG9zdBsUcm1saW51eC
 362 5tY211cmNoeS5wcnajgd8wgdygAwIBEKEDAgEBooHPBIHMPjIqKN0hDYaInF4oJqsHviI3tFsNY/
 363 o+WJAUavr2fiShzcgMWlFNAiHn5Vu4PDmmahIgrlfTfzb7BVdqUK6DTKGS8frSgaCtZg/UiVR95Y
 364 ilfhbzWtovbK2kbNUESGAgjSrMzLWrcoHLAaX8gdOBh8d9OWuMY0hnHVCGPZgQRFu6HadF1phtjl
 365 Ia5DduhF2yln/ouJQgPAC6ArRTevYw0gynPu+ieKwdcaRr/UZC5DQX7SW3tG8Y12YHxNiuwUQ/jQ
 366 J2CCa0bRhpRefupIHKMIHHoAMCARCigb8Egbx5F6qCmaIzvKYN+qvpk0AwiP+6QQHq1cslZE+Kgo
 367 92PVNnNnWzosPvq0dSbLABuvA0P7jCpIjfxAoxK8KngIkuus1tHClD/fyDn/Yo3vv2ykNxibe5Dt
 368 oPJTLOPIdOlCxNfjSftqhLhyPHuRQkvSQJExVR4XYy69vKierr//ziVH6Bjo0I01Ac/vSlgxD6pQ
 369 qAzUd37luN9SX1O1bFoTg3andX9lgD2JuvtiD6k5K2shDZHWHCuptM9Y8nYw==
 370 Waiting for server reply...
 371
 372 -----------------
 373 Possible Problem:
 374 -----------------
 375
 376 If GSSAPI is not selected as the mechanism, you need to stop and figure out
 377 why. I don't have a lot to offer if it fails other than to look at the
 378 instructions at: http://asg.web.cmu.edu/cyrus/download/sasl/gssapi.html.
 379
 380 ---------------------------
 381 Continuing the Negotiation:
 382 ---------------------------
 383
 384 Next we'll take the clients response and paste it into the server window:
 385
 386 C: R1NTQVBJAGCCAiEGCSqGABCDEgECAgEAboICEDCCAygAwIBBaEDAgEOogcDBQAgAAAAo4IBKG
 387 GCASQwggEgoAMCAQWhDhsMTUNNVVJDSFkuUFJWoicwJaADAgEBoR4wHBsEaG9zdBsUcm1saW51eC
 388 5tY211cmNoeS5wcnajgd8wgdygAwIBEKEDAgEBooHPBIHMPjIqKN0hDYaInF4oJqsHviI3tFsNY/
 389 o+WJAUavr2fiShzcgMWlFNAiHn5Vu4PDmmahIgrlfTfzb7BVdqUK6DTKGS8frSgaCtZg/UiVR95Y
 390 ilfhbzWtovbK2kbNUESGAgjSrMzLWrcoHLAaX8gdOBh8d9OWuMY0hnHVCGPZgQRFu6HadF1phtjl
 391 Ia5DduhF2yln/ouJQgPAC6ArRTevYw0gynPu+ieKwdcaRr/UZC5DQX7SW3tG8Y12YHxNiuwUQ/jQ
 392 J2CCa0bRhpRefupIHKMIHHoAMCARCigb8Egbx5F6qCmaIzvKYN+qvpk0AwiP+6QQHq1cslZE+Kgo
 393 92PVNnNnWzosPvq0dSbLABuvA0P7jCpIjfxAoxK8KngIkuus1tHClD/fyDn/Yo3vv2ykNxibe5Dt
 394 oPJTLOPIdOlCxNfjSftqhLhyPHuRQkvSQJExVR4XYy69vKierr//ziVH6Bjo0I01Ac/vSlgxD6pQ
 395 qAzUd37luN9SX1O1bFoTg3andX9lgD2JuvtiD6k5K2shDZHWHCuptM9Y8nYw==
 396
 397 The server should respond with something similar to the following:
 398
 399 got 'GSSAPI'
 400 Sending response...
 401 S: YGwGCSqGSIb3EgABCEDAb10w6ADAgEFoQMCAQ+iTzBNoAMCARCiRgRE+gyefHkAoVAopWb2gH
 402 Ys1j5GLPAmZUwzi/RCPBT7PUHU9fmHsS0MbnDqOyJpuNxSTfwYW3X6gaynTVSSDskw5Rt+c7o=
 403 Waiting for client reply...
 404
 405 Paste the "S:" line returned by the server into the client and the client
 406 should respond with something similar to the following:
 407
 408 recieved 110 byte message
 409 C:
 410 Waiting for server reply...
 411
 412 Paste the client's response, "C: ", into the server and the server should
 413 respond with something similar to the following:
 414
 415 got ''
 416 Sending response...
 417 S: YD8GCABCDEbEgECAgIBBAD/////vcDLfGe6YcE8C9xSSqtgPmE92SdQaf43nxiCHqpuBjBoWV
 418 IkBwAIAAQEBAQ=
 419 Waiting for client reply...
 420
 421 Paste the "S:" line returned by the server into the client and the client
 422 should respond with something similar to the following:
 423
 424 recieved 65 byte message
 425 Sending response...
 426 C: YD8GCABCEDb3gECAgIBBAD/////wojejnxqRluhJXmIdw+E8QNgrVM51TXK2/3tYjXlFcLGbR
 427 u2BAAIAHJtbAE=
 428 Negotiation complete
 429 Username: user
 430 SSF: 56
 431 Waiting for encoded message...
 432
 433 Paste the "C:" line returned by the client into the server and the server
 434 should respond with something similar to the following:
 435
 436 got '`? *H÷'
 437 Negotiation complete
 438 Username: user
 439 Realm: (NULL)
 440 SSF: 56
 441 sending encrypted message 'srv message 1'
 442 S: AAAASWBHBgkqhkiG9xIBAgICAQQAAgD//3va2sQlP9/yLTzIP5ABCDE8BkUBfeoMYs0n9gdGB
 443 oRCOcp/0JF2NUalD/vXOnllEtTtrA=
 444 Waiting for encrypted message...
 445
 446 Paste the "S:" line returned by the server into the client and the client
 447 should respond with something similar to the following:
 448
 449 recieved 77 byte message
 450 recieved decoded message 'srv message 1'
 451 sending encrypted message 'client message 1'
 452 C: AAAAUWBPBgkqhkiG9xIBAgICAQQAAgD//yyN28j66vOfMxKvbm2XkqJgxCNFpXjB3h2UoaLj+
 453 LkABCEDkO2FS8tNuu3ks+WV4WgagWyf3c6Mbs39g==
 454
 455 At this point the client should return back to the unix shell prompt. Paste
 456 the "C:" line returned by the client into the server and the server should
 457 respond with something similar to the following:
 458
 459 got ''
 460 recieved decoded message 'client message 1'
 461
 462 The server should return back to the unix shell prompt and the client-server
 463 negotiation is finished.
 464
 465 -----------------
 466 Results Analysis:
 467 -----------------
 468
 469 If you got this far and the client-server negotiation tests completed with
 470 responses similar to the ones shown above, you're done. You can feel
 471 confident that your GSSAPI works. If any application using GSSAPI
 472 authentication, such as OpenLDAP or sendmail, can't communicate with Kerberos
 473 via SASL, the problem probably lies somewhere other than with Kerberos or
 474 Cyrus-SASL.
 475
 476 ==========================================
 477 6. ISSUES, GOTCHAS AND OTHER SUNDRY ITEMS:
 478 ==========================================
 479
 480 I can't think of anything other than the issue with building Cyrus-SASL with
 481 the --enable-static option. If others have used Cyrus-SASL for reasons other
 482 than straight GSSAPI authentication, you are welcome to contribute to this
 483 hint. Information on using the saslauthd daemon is especially encouraged.
 484
 485 ========
 486 7. TODO:
 487 ========
 488
 489 Figure out why and how to use the saslauthd daemon and provide instructions.
 490
 491 ===========
 492 8. CLOSING:
 493 ===========
 494
 495 Maybe there's enough information here to go ahead and create a new package
 496 for BLFS. If it's decided to include Cyrus-SASL in BLFS, I'm sure we'll hear
 497 about other problems as they occur. I'm mainly interested in providing the
 498 instructions for a clean build and testing Kerberos/Cyrus-SASL GSSAPI
 499 functionality. I hope I've succeeded. Enjoy!
 500
 501
 502 ACKNOWLEDGEMENTS:
 503
 504 Ken Hornstein <kenh_AT_cmf.nrl.navy.mil> for providing the information at:
 505 http://www.ipnet6.org/src/cyrus-sasl-2/doc/gssapi.html
 506
 507
 508 CHANGELOG:
 509
 510 [2004-05-05]
 511     * Despamify email address of Ken at his request
 512     * Minor wording changes
 513
 514 [2004-05-02]
 515     * Reformatted the document IAW the LFS hint submission guideline
 516     * Changed the Synopsis to identify GSSAPI as the test mechanism
 517     * Removed reference to stripping the static library file
 518     * Minor wording changes
 519
 520 [2004-04-28]
 521     * Minor wording changes
 522
 523 [2004-04-23]
 524     * Original draft
 525