1<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> 2<html> 3<head> 4<meta name="generator" content="HTML Tidy, see www.w3.org"> 5<title>SASL Application Programmer's Guide</title> 6</head> 7<body> 8<h1>SASL Application Programmer's Guide</h1> 9 10<h3>NOTE: This is a work in progress. Any contributions would be 11<i>very</i> appreciated</h3> 12 13<h2>Contents</h2> 14 15<ul> 16<li><a href="#intro">Introduction</a> 17 18<ul> 19<li><a href="#about_this_guide">About this guide</a></li> 20 21<li><a href="#what_is_sasl">What is SASL?</a></li> 22</ul> 23</li> 24 25<li><a href="#background">Background</a> 26 27<ul> 28<li><a href="#world_before">How did the world work before 29SASL?</a></li> 30 31<li><a href="#sasl_rescue">SASL to the rescue!</a></li> 32</ul> 33</li> 34 35<li><a href="#briefly">Briefly</a> 36 37<ul> 38<li><a href="#what_good_for">What is the Cyrus SASL library good 39for?</a></li> 40 41<li><a href="#what_do">What does the Cyrus SASL library 42do?</a></li> 43 44<li><a href="#what_doesnt">What doesn't the Cyrus SASL library 45do?</a></li> 46</ul> 47</li> 48 49<li><a href="#client_only">Client-only Section</a> 50 51<ul> 52<li><a href="#client_typical">A typical interaction from the 53client's perspective</a></li> 54 55<li><a href="#client_code">How does this look in code?</a></li> 56 57<li><a href="#sasl_client_init">sasl_client_init</a></li> 58 59<li><a href="#sasl_client_new">sasl_client_new</a></li> 60 61<li><a href="#sasl_client_start">sasl_client_start</a></li> 62 63<li><a href="#sasl_client_step">sasl_client_step</a></li> 64</ul> 65</li> 66 67<li><a href="#server_section">Server-only Section</a> 68 69<ul> 70<li><a href="#server_typical">A typical interaction from the 71server's perspective</a></li> 72 73<li><a href="#server_code">How does this look in code?</a></li> 74 75<li><a href="#sasl_server_init">sasl_server_init</a></li> 76 77<li><a href="#sasl_server_new">sasl_server_new</a></li> 78 79<li><a href="#sasl_server_start">sasl_server_start</a></li> 80 81<li><a href="#sasl_server_step">sasl_server_step</a></li> 82 83<li><a href="#sasl_listmech">sasl_listmech</a></li> 84 85<li><a href="#sasl_checkpass">sasl_checkpass</a></li> 86</ul> 87</li> 88 89<li><a href="#common_section">Common Section</a> 90 91<ul> 92<li><a href="#callbacks_interactions">Callbacks and 93Interaction</a></li> 94 95<li><a href="#layers">Security layers</a></li> 96</ul> 97</li> 98 99<li><a href="#example_section">Example applications that come with 100the Cyrus SASL library</a> 101 102<ul> 103<li><a href="#sample_client"><tt>sample-client</tt> and 104<tt>sample-server</tt></a></li> 105 106<li><a href="#cyrus_imapd">Cyrus imapd v2.1.0 or later</a></li> 107 108<li><a href="#imtest"><tt>imtest</tt>, from cyrus imapd 2.1.0 or 109later</a></li> 110</ul> 111</li> 112 113<li><a href="#random_things">Miscellaneous Information</a> 114 115<ul> 116<li><a href="#empty_exchanges">Empty exchanges</a></li> 117</ul> 118</li> 119</ul> 120 121<h2><a name="intro">Introduction</a></h2> 122 123<h3><a name="about_this_guide">About this Guide</a></h3> 124 125<p>This guide gives a tutorial on the use of the Cyrus SASL library 126for a client or server application. It complies with versions 127including and after 2.0.0. The following pages should only be 128considered a guide, not the final word on programming with the 129Cyrus SASL library. Consult the header files in the distribution in 130the case of ambiguities.</p> 131 132<h3><a name="what_is_sasl">What is SASL?</a></h3> 133 134<p>SASL stands for Simple Authentication Security Layer and is 135explained in <a href="http://ftp.ietf.org/rfc/rfc2222.txt">RFC 1362222</a>. That document is very difficult to understand however and 137it should be unnecessary to consult it.</p> 138 139<h2><a name="background">Background</a></h2> 140 141<h3><a name="world_before">How did the world work before 142SASL?</a></h3> 143 144<p>Before SASL, when a new protocol was written which required 145authentication (users proving who they are to an entity), the 146protocol had to allow explicitly for each individual authentication 147mechanism. There had to be a distinct way to say "I want to log in 148with Kerberos V4". There had to be another distinct way to say "I 149want to log in with CRAM-MD5". There had to be yet a different way 150to say "I want to log in anonymously," and so on. This was 151non-ideal for both the protocol and application writers.</p> 152 153<p>Additionally, many programmers were not very familiar with 154security, so the protocol did support many mechanisms, or worse, 155they were supported incorrectly. Moreover, when a new 156authentication method was invented the protocol needed to be 157modified to support that mechanism.</p> 158 159<p>This system also was not ideal for application writer. She had 160to have a special case for each mechanism she wished her 161application to support. Also, the mechanisms were difficult to 162implement. Even with a good library, an understanding of how the 163mechanism worked was still necessary. Finally if an application 164used more than one protocol (for example a mail client might use 165IMAP, POP, and SMTP) then "Kerberos V4 for IMAP", "Kerberos V4 for 166POP", "Kerberos V4 for SMTP", "CRAM MD5 for IMAP", "CRAM-MD5 for 167POP", etc... would need to be written. This could quickly create a 168huge number of different mechanism-protocol pairs to implement.</p> 169 170<h3><a name="sasl_rescue">SASL to the rescue!</a></h3> 171 172<p>SASL hopefully solves all these problems. In practice it makes 173many of them easier to deal with.</p> 174 175<p>Protocol designers simply have to support SASL (in particular 176RFC 2222). Consequently, any mechanism that supports SASL (just 177about anything you would want to use does now) is supported by the 178protocol. If a new authentication mechanism is invented the 179protocol automatically supports it without any modifications.</p> 180 181<p>Application writers, instead of having to support every 182mechanism for every protocol, only need to support SASL for every 183protocol. Application writers do not need to understand the 184authentication mechanisms at all: the SASL library handles all 185that. Also with the Cyrus SASL library if a new mechanism is 186invented you do not have rewrite your application at all. You may 187not even have to restart your application if it is a long running 188process. This is because the Cyrus SASL library loads each 189mechanism from a shared library. Simply copying a shared library 190into a directory will magically make your application support a new 191mechanism.</p> 192 193<p>Cyrus SASL version 2 supports a much improved API over version 1941, that allows for much smarter and faster memory allocation for 195the mechanisms as well as the applications. It is also provides for 196several new types of plugins to allow for greater overall 197flexibility. Unfortunately, though similar, this new API is 198completely incompatible with the old API, and applications will 199need to be rewritten.</p> 200 201<h2><a name="briefly">Briefly</a></h2> 202 203<h3><a name="what_good_for">What is the Cyrus SASL library good 204for?</a></h3> 205 206<p>The Cyrus SASL library is good for applications that wish to use 207protocols that support SASL authentication. An non-exhaustive list 208of these are: IMAP, SMTP, ACAP, and LDAP. Also if you are making a 209proprietary system and wish to support authentication it is a good 210way of supporting many different authentication types.</p> 211 212<h3><a name="what_do">What does the Cyrus SASL library do?</a></h3> 213 214<p>From a client point of view, the Cyrus SASL library, given a 215list of mechanisms the server supports it will decide the best 216mechanism to use and tell you what to send to the server at each 217step of the authentication. From a server perspective, it handles 218authentication requests from clients.</p> 219 220<h3><a name="what_doesnt">What doesn't the Cyrus SASL library 221do?</a></h3> 222 223<p>The Cyrus SASL library is neither network nor protocol aware. It 224is up to the application to send the data over the wire as well as 225to send the data in the protocol specific manner. With IMAP this 226means putting it in the form: <tt>+ [base64'ed data]\r\n</tt>. LDAP 227just sends data in binary via bind requests. The Cyrus SASL library 228has utility base64 encode and decode routines to help with 229this.</p> 230 231<h2><a name="client_section">Client-only Section</a></h2> 232 233<h3><a name="client_typical">A typical interaction from the 234client's perspective</a></h3> 235 236<ol> 237<li>A client makes a few calls (explained later) to initialize 238SASL.</li> 239 240<li>Every time the client application makes a new connection it 241should make a new context that is kept for the life of the 242connection.</li> 243 244<li>Ask the server for the list of supported mechanisms</li> 245 246<li>Feed this list to the library</li> 247 248<li>Start the authentication with the mechanism the library 249chose</li> 250 251<li>The server will return some bytes</li> 252 253<li>Give these to the library</li> 254 255<li>The library returns some bytes to the application</li> 256 257<li>Application sends these bytes over the network</li> 258 259<li>repeat the last 4 steps until the server tells you that the 260authentication is completed</li> 261</ol> 262 263<h3><a name="client_code">How does this look in code</a></h3> 264 265<b>Initialize the library</b>. (done once). 266 267<pre> 268 269 int result; 270 271 /* attempt to start sasl 272 * See the section on Callbacks and Interactions for an 273 * explanation of the variable callbacks 274 */ 275 276 result=sasl_client_init(callbacks); 277 278 /* check to see if that worked */ 279 if (result!=SASL_OK) [failure] 280 281</pre> 282 283<b>For every network connection, make a new SASL connection</b>: 284 285<pre> 286 287 /* The SASL context kept for the life of the connection */ 288 sasl_conn_t *conn; 289 290 291 /* client new connection */ 292 result=sasl_client_new("imap", /* The service we are using */ 293 serverFQDN, /* The fully qualified domain 294 name of the server we're 295 connecting to */ 296 NULL, NULL, /* Local and remote IP 297 address strings 298 (NULL disables mechanisms 299 which require this info)*/ 300 NULL, /* connection-specific 301 callbacks */ 302 0, /* security flags */ 303 &conn); /* allocated on success */ 304 305 /* check to see if that worked */ 306 if (result!=SASL_OK) [failure] 307 308 309</pre> 310 311Next get the list of SASL mechanisms the server supports. This is 312usually done through a capability command. Format the list as a 313single string separated by spaces. Feed this string into SASL to 314begin the authentication process. 315 316<pre> 317 318 sasl_interact_t *client_interact=NULL; 319 const char *out, *mechusing; 320 unsigned outlen; 321 322 do { 323 324 result=sasl_client_start(conn, /* the same context from 325 above */ 326 mechlist, /* the list of mechanisms 327 from the server */ 328 &client_interact, /* filled in if an 329 interaction is needed */ 330 &out, /* filled in on success */ 331 &outlen, /* filled in on success */ 332 &mechusing); 333 334 if (result==SASL_INTERACT) 335 { 336 [deal with the interactions. See interactions section below] 337 } 338 339 340 } while (result==SASL_INTERACT); /* the mechanism may ask us to fill 341 in things many times. result is 342 SASL_CONTINUE on success */ 343 if (result!=SASL_CONTINUE) [failure] 344 345 346</pre> 347 348Note that you do not need to worry about the allocation and freeing 349of the output buffer out. This is all handled inside of the 350mechanism. It is important to note, however, that the output buffer 351is not valid after the next call to <tt>sasl_client_start</tt> or 352<tt>sasl_client_step</tt>. 353 354<p>If this is successful send the protocol specific command to 355start the authentication process. This may or may not allow for 356initial data to be sent (see the documentation of the protocol to 357see).</p> 358 359<pre> 360 For IMAP this might look like: 361 {tag} "AUTHENTICATE" {mechusing}\r\n 362 A01 AUTHENTICATE KERBEROS_V4\r\n 363 364 SMTP looks like: 365 "AUTH" {mechusing}[ {out base64 encoded}] 366 AUTH DIGEST-MD5 GHGJJGDDFDKHGHJG= 367 368</pre> 369 370<br> 371 <a name="client_authentication_step"><b>Check Results</b></a> <br> 372 Next, read what the server sent back. It can be one of three 373things: 374 375<ol> 376<li>Authentication failure. Authentication process is halted. This 377might look like <tt>A01 NO Authentication failure</tt> in IMAP or 378<tt>501 Failed</tt> in SMTP. Either retry the authentication or 379abort.</li> 380 381<li>Authentication success. We're now successfully authenticated. 382This might look like <tt>A01 OK Authenticated successful</tt> in 383IMAP or <tt>235 Authentication successful</tt> in SMTP. Go <a href= 384"#client_authentication_success">here</a></li> 385 386<li>Another step in the authentication process is necessary. This 387might look like <tt>+ HGHDS1HAFJ=</tt> in IMAP or <tt>334 388PENCeUxFREJoU0NnbmhNWitOMjNGNndAZWx3b29kLmlubm9zb2Z0LmNvbT4=</tt> 389in SMTP. Note it could be an empty string such as <tt>+ \r\n</tt> 390in IMAP.</li> 391</ol> 392 393Convert the continuation data to binary format (for example, this 394may include base64 decoding it). Perform another step in the 395authentication. 396 397<pre> 398 do { 399 result=sasl_client_step(conn, /* our context */ 400 in, /* the data from the server */ 401 inlen, /* it's length */ 402 &client_interact, /* this should be 403 unallocated and NULL */ 404 &out, /* filled in on success */ 405 &outlen); /* filled in on success */ 406 407 if (result==SASL_INTERACT) 408 { 409 [deal with the interactions. See below] 410 } 411 412 413 } while (result==SASL_INTERACT || result == SASL_CONTINUE); 414 415 if (result!=SASL_OK) [failure] 416 417 418</pre> 419 420Format the output (variable out of length outlen) in the protocol 421specific manner and send it across the network to the server. <br> 422 Goto <a href="#client_authentication_step">here</a> (this process 423repeats until authentication either succeeds or fails. <br> 424<br> 425<br> 426 <a name="client_authentication_success"><b>Authentication 427Successful</b></a><br> 428<br> 429 430 431<p>Before we're done we need to call sasl_client_step() one more 432time to make sure the server isn't trying to fool us. Some 433protocols include data along with the last step. If so this data 434should be used here. If not use a length of zero.</p> 435 436<pre> 437 result=sasl_client_step(conn, /* our context */ 438 in, /* the data from the server */ 439 inlen, /* it's length */ 440 &client_interact, /* this should be unallocated and NULL */ 441 &out, /* filled in on success */ 442 &outlen); /* filled in on success */ 443 444 if (result!=SASL_OK) [failure] 445 446</pre> 447 448<p>Congratulations. You have successfully authenticated to the 449server.</p> 450 451<p>Don't throw away the SASL connection object (sasl_conn_t *) yet 452though. If a security layer was negotiated you will need it to 453encode and decode the data sent over the network.</p> 454 455<br> 456 When you are finally done with connection to server, dispose of 457SASL connection. 458 459<pre> 460 461 sasl_dispose(&conn); 462 463 464</pre> 465 466If you are done with SASL forever (application quiting for 467example): 468 469<pre> 470 sasl_client_done(); 471 472</pre> 473 474Or if your application is both a SASL client and a SASL server: 475 476<pre> 477 sasl_done(); 478 479</pre> 480 481But note that applications should be using sasl_client_done()/sasl_server_done() whenever possible. 482 483 484<h3>sasl_client_init</h3> 485 486<pre> 487 int sasl_client_init(const sasl_callback_t *callbacks); 488 489</pre> 490 491Parameters: 492 493<ul> 494<li>callbacks - List of callbacks. See Callbacks section</li> 495</ul> 496 497This function initializes the SASL library. This must be called 498before any other SASL calls. See the callbacks section for complete 499description of callbacks. 500 501<h3>sasl_client_new</h3> 502 503<pre> 504 int sasl_client_new(const char *service, 505 const char *serverFQDN, 506 const char *iplocalport, 507 const char *ipremoteport, 508 const sasl_callback_t *prompt_supp, 509 unsigned secflags, 510 sasl_conn_t **pconn); 511 512</pre> 513 514Parameters: 515 516<ul> 517<li>service - the service name being used. This usually is the 518protocol name (e.g. "ldap")</li> 519 520<li>serverFQDN - Fully qualified domain name of server</li> 521 522<li>iplocalport and ipremoteport - a string of the format 523"a.b.c.d;p" detailing the local or remote IP and port, or NULL 524(which will disable mechanisms that require this information)</li> 525 526<li>prompt_supp - List off callbacks specific to this 527connection</li> 528 529<li>secflags - security flags ORed together requested (e.g. 530SASL_SEC_NOPLAINTEXT)</li> 531 532<li>pconn - the SASL connection object allocated upon success</li> 533</ul> 534 535This function creates a new SASL connection object. It should be 536called once for every connection you want to authenticate for. 537 538<h3>sasl_client_start</h3> 539 540<pre> 541 int sasl_client_start(sasl_conn_t *conn, 542 const char *mechlist, 543 sasl_interact_t **prompt_need, 544 const char **clientout, 545 unsigned *clientoutlen, 546 const char **mech); 547 548</pre> 549 550Parameters: 551 552<ul> 553<li>conn - the SASL connection object gotten from 554sasl_client_new()</li> 555 556<li>mechlist - the list of mechanisms to try (separated by 557spaces)</li> 558 559<li>prompt_need - filled in when a SASL_INTERACT is returned</li> 560 561<li>clientout - filled in upon success with data to send to 562server</li> 563 564<li>clientoutlen - length of that data</li> 565 566<li>mech - filled in with mechanism being used</li> 567</ul> 568 569This function starts an authentication session. It takes a list of 570possible mechanisms (usually gotten from the server through a 571capability command) and chooses the "best" mechanism to try. Upon 572success clientout points at data to send to the server. 573 574<h3>sasl_client_step</h3> 575 576<pre> 577 int sasl_client_step(sasl_conn_t *conn, 578 const char *serverin, 579 unsigned serverinlen, 580 sasl_interact_t **prompt_need, 581 const char **clientout, 582 unsigned *clientoutlen); 583 584</pre> 585 586Parameters: 587 588<ul> 589<li>conn - the SASL connection object gotten from 590sasl_client_new()</li> 591 592<li>serverin - data from the server</li> 593 594<li>serverinlen - length of data from the server</li> 595 596<li>prompt_need - filled in with a SASL_INTERACT is returned</li> 597 598<li>clientout - filled in upon success with data to send to 599server</li> 600 601<li>clientoutlen - length of that data</li> 602</ul> 603 604This step preforms a step in the authentication process. It takes 605the data from the server (serverin) and outputs data to send to the 606server (clientout) upon success. SASL_CONTINUE is returned if 607another step in the authentication process is necessary. SASL_OK is 608returned if we're all done. 609 610<h2><a name="server_section">Server-only Section</a></h2> 611 612<h3><a name="server_typical">A typical interaction from the 613server's perspective</a></h3> 614 615The server makes a few Cyrus SASL calls for initialization. When it 616gets a new connection it should make a new context for that 617connection immediately. The client may then request a list of 618mechanisms the server supports. The client also may request to 619authenticate at some point. The client will specify the mechanism 620it wishes to use. The server should negotiate this authentication 621and keep around the context afterwards for encoding and decoding 622the layers. 623 624<h3><a name="server_code">How does this look in code?</a></h3> 625 626Initialization (done once). The application name is used for 627reading configuration information. 628 629<pre> 630 631 int result; 632 633 /* Initialize SASL */ 634 result=sasl_server_init(callbacks, /* Callbacks supported */ 635 "TestServer"); /* Name of the application */ 636 637 638</pre> 639 640This should be called for each new connection. It probably should 641be called right when the socket is accepted. 642 643<pre> 644 sasl_conn_t *conn; 645 int result; 646 647 /* Make a new context for this connection */ 648 result=sasl_server_new("smtp", /* Registered name of service */ 649 NULL, /* my fully qualified domain name; 650 NULL says use gethostname() */ 651 NULL, /* The user realm used for password 652 lookups; NULL means default to serverFQDN 653 Note: This does not affect Kerberos */ 654 NULL, NULL, /* IP Address information strings */ 655 NULL, /* Callbacks supported only for this connection */ 656 0, /* security flags (security layers are enabled 657 * using security properties, separately) 658 &conn); 659 660 661</pre> 662 663When a client requests the list of mechanisms supported by the 664server. This particular call might produce the string: <i>"{PLAIN, 665KERBEROS_V4, CRAM-MD5, DIGEST-MD5}"</i> 666 667<pre> 668 result=sasl_listmech(conn, /* The context for this connection */ 669 NULL, /* not supported */ 670 "{", /* What to prepend the string with */ 671 ", ", /* What to separate mechanisms with */ 672 "}", /* What to append to the string */ 673 &result_string, /* The produced string. */ 674 &string_length, /* length of the string */ 675 &number_of_mechanisms); /* Number of mechanisms in 676 the string */ 677 678 679</pre> 680 681When a client requests to authenticate: 682 683<pre> 684 int result; 685 const char *out; 686 unsigned outlen; 687 688 result=sasl_server_start(conn, /* context */ 689 mechanism_client_chose, 690 clientin, /* the optional string the client gave us */ 691 clientinlen, /* and it's length */ 692 &out, /* The output of the library. 693 Might not be NULL terminated */ 694 &outlen); 695 696 if ((result!=SASL_OK) && (result!=SASL_CONTINUE)) 697 [failure. Send protocol specific message that says authentication failed] 698 else if (result==SASL_OK) 699 [authentication succeeded. Send client the protocol specific message 700 to say that authentication is complete] 701 else 702 [send data 'out' with length 'outlen' over the network in protocol 703 specific format] 704 705</pre> 706 707When a response is returned by the client. <i>clientin</i> is the 708data from the client decoded from protocol specific format to a 709string of bytes of length <i>clientinlen</i>. This step may occur 710zero or more times. An application must be able to deal with it 711occurring an arbitrary number of times. 712 713<pre> 714 int result; 715 716 result=sasl_server_step(conn, 717 clientin, /* what the client gave */ 718 clientinlen, /* it's length */ 719 &out, /* allocated by library on success. 720 Might not be NULL terminated */ 721 &outlen); 722 723 if ((result!=SASL_OK) && (result!=SASL_CONTINUE)) 724 [failure. Send protocol specific message that says authentication failed] 725 else if (result==SASL_OK) 726 [authentication succeeded. Send client the protocol specific message 727 to say that authentication is complete] 728 else 729 [send data 'out' with length 'outlen' over the network in protocol 730 specific format] 731 732</pre> 733 734This continues until authentication succeeds. When the connection 735is concluded, make a call to <tt>sasl_dispose</tt> as with the 736client connection. 737 738<h3><a name="sasl_server_init">sasl_server_init</a></h3> 739 740<pre> 741 int sasl_server_init(const sasl_callback_t *callbacks, 742 const char *appname); 743</pre> 744 745Parameters: 746 747<ul> 748<li>callbacks - A list of callbacks supported by the application 749(see Interaction and Callbacks section)</li> 750 751<li>appname - A string of the name of the application. This string 752is what is used when loading configuration options.</li> 753</ul> 754 755sasl_server_init() initializes the session. This should be the 756first function called. In this function the shared library 757authentication mechanisms are loaded. 758 759<h3><a name="sasl_server_new">sasl_server_new</a></h3> 760 761<pre> 762 int sasl_server_new(const char *service, 763 const char *serverFQDN, 764 const char *user_realm, 765 const char *iplocalport, 766 const char *ipremoteport, 767 const sasl_callback_t *callbacks, 768 unsigned secflags, 769 sasl_conn_t **pconn); 770</pre> 771 772Parameters: 773 774<ul> 775<li>service - The name of the service you are supporting. This 776might be "acap" or "smtp". This is used by Kerberos mechanisms and 777possibly other mechanisms. It is also used for PAM 778authentication.</li> 779 780<li>serverFQDN - This is the fully qualified domain name of the 781server (i.e. your hostname); if NULL, the library calls 782<tt>gethostbyname()</tt>.</li> 783 784<li>user_realm - The realm the connected client is in. The Kerberos 785mechanisms ignore this parameter and default to the local Kerberos 786realm. A value of NULL makes the library default, usually to the 787serverFQDN; a value of "" specifies that the client should specify 788the realm; this also changes the semantics of "@" in a username for 789mechanisms that don't support realms.</li> 790 791<li>iplocalport and ipremoteport - a string of the format 792"a.b.c.d;p" detailing the local or remote IP and port, or NULL 793(which will disable mechanisms that require this information)</li> 794 795<li>callbacks - Additional callbacks that you wish only to apply to 796this connection.</li> 797 798<li>secflags - security flags.</li> 799 800<li>pconn - Context. Filled in on success.</li> 801</ul> 802 803<h3><a name="sasl_server_start">sasl_server_start</a></h3> 804 805<pre> 806 int sasl_server_start(sasl_conn_t *conn, 807 const char *mech, 808 const char *clientin, 809 unsigned clientinlen, 810 const char **serverout, 811 unsigned *serveroutlen); 812 813</pre> 814 815Parameters: 816 817<ul> 818<li>conn - The context for the connection</li> 819 820<li>mech - The authentication mechanism the client wishes to try 821(e.g. <tt>KERBEROS_V4</tt>)</li> 822 823<li>clientin - Initial client challenge bytes. Note: some protocols 824do not allow this. If this is the case passing NULL is valid</li> 825 826<li>clientinlen - The length of the challenge. 0 is there is 827none.</li> 828 829<li>serverout - allocated and filled in by the function. These are 830the bytes that should be encoded as per the protocol and sent over 831the network back to the client.</li> 832 833<li>serveroutlen - length of bytes to send to client</li> 834</ul> 835 836This function begins the authentication process with a client. If 837the program returns SASL_CONTINUE that means <tt>serverout</tt> 838should be sent to the client. If SASL_OK is returned that means 839authentication is complete and the application should tell the 840client the authentication was successful. Any other return code 841means the authentication failed and the client should be notified 842of this. 843 844<h3><a name="sasl_server_step">sasl_server_step</a></h3> 845 846<pre> 847 int sasl_server_step(sasl_conn_t *conn, 848 const char *clientin, 849 unsigned clientinlen, 850 const char **serverout, 851 unsigned *serveroutlen); 852 853</pre> 854 855Parameters: 856 857<ul> 858<li>conn - The context for the connection</li> 859 860<li>clientin - Data sent by the client.</li> 861 862<li>clientinlen - The length of the client data. Note that this may 863be 0</li> 864 865<li>serverout - allocated and filled in by the function. These are 866the bytes that should be encoded as per the protocol and sent over 867the network back to the client.</li> 868 869<li>serveroutlen - length of bytes to send to client. Note that 870this may be 0</li> 871</ul> 872 873This function preforms a step of the authentication. This may need 874to be called an arbitrary number of times. If the program returns 875SASL_CONTINUE that means <tt>serverout</tt> should be sent to the 876client. If SASL_OK is returned that means authentication is 877complete and the application should tell the client the 878authentication was successful. Any other return code means the 879authentication failed and the client should be notified of this. 880 881<h3><a name="sasl_listmech">sasl_listmech</a></h3> 882 883<pre> 884 int sasl_listmech(sasl_conn_t *conn, 885 const char *user, 886 const char *prefix, 887 const char *sep, 888 const char *suffix, 889 const char **result, 890 unsigned *plen, 891 unsigned *pcount); 892 893</pre> 894 895Parameters: 896 897<ul> 898<li>conn - The context for this connection</li> 899 900<li>user - Currently not implemented</li> 901 902<li>prefix - The string to prepend</li> 903 904<li>sep - The string to separate mechanisms with</li> 905 906<li>suffix - The string to end with</li> 907 908<li>result - Resultant string</li> 909 910<li>plen - Number of characters in the result string</li> 911 912<li>pcount - Number of mechanisms listed in the result string</li> 913</ul> 914 915This function is used to create a string with a list of SASL 916mechanisms supported by the server. This string is often needed for 917a capability statement. 918 919<h3><a name="sasl_checkpass">sasl_checkpass</a></h3> 920 921<pre> 922 int sasl_checkpass(sasl_conn_t *conn, 923 const char *user, 924 unsigned userlen, 925 const char *pass, 926 unsigned passlen); 927 928</pre> 929 930Parameters: 931 932<ul> 933<li>conn - The context for this connection</li> 934 935<li>user - The user trying to check the password for</li> 936 937<li>userlen - The user length</li> 938 939<li>pass - The password</li> 940 941<li>passlen - The password length</li> 942</ul> 943 944This checks a plaintext password <i>pass</i> for user <i>user</i> 945Some protocols have legacy systems for plaintext authentication 946where this might be used. 947 948<h2><a name="common_section">Common Section</a></h2> 949 950<h3><a name="callbacks_interactions">Callbacks and 951Interactions</a></h3> 952 953When the application starts and calls sasl_client_init() you must 954specify for what data you support callbacks and/or interactions. 955These are for the library getting information needed for 956authentication from the application. This is needed for things like 957authentication name and password. If you do not declare supporting 958a callback you will not be able to use mechanisms that need that 959data. A callback is for when you have the information before you 960start the authentication. The SASL library calls a function you 961specify and your function fills in the requested information. For 962example if you had the userid of the user already for some reason. 963An interaction is usually for things you support but will need to 964ask the user for (e.g. password). sasl_client_start() or 965sasl_client_step() will return SASL_INTERACT. This will be a list 966of sasl_interact_t's which contain a human readable string you can 967prompt the user with, a possible computer readable string, and a 968default result. The nice thing about interactions is you get them 969all at once so if you had a GUI application you could bring up a 970dialog box asking for authentication name and password together 971instead of one at a time. 972 973<p>Any memory that is given to the SASL library for the purposes of 974callbacks and interactions must persist until the exchange 975completes in either success or failure. That is, the data must 976persist until <tt>sasl_client_start</tt> or 977<tt>sasl_client_step</tt> returns something other than 978<tt>SASL_INTERACT</tt> or <tt>SASL_CONTINUE</tt>.</p> 979 980<p><b>Memory management:</b>As in the rest of the SASLv2 API, 981whoever allocates the memory is responsible for freeing it. In 982almost all cases this should be fairly easy to manage, however a 983slight exception where the interaction sasl_interact_t structure is 984allocated and freed by the library, while the results are allocated 985and freed by the application. As noted above, however, <i>the 986results may not be freed until after the exchange completes, in 987either success or failure</i>.</p> 988 989<p>For a detailed description of what each of the callback types 990are see the sasl.h file. Here are some brief explanations:</p> 991 992<ul> 993<li>SASL_CB_AUTHNAME - the name of the user authenticating</li> 994 995<li>SASL_CB_USER - the name of the user acting for. (for example 996postman delivering mail for tmartin might have an AUTHNAME of 997postman and a USER of tmartin)</li> 998 999<li>SASL_CB_PASS - password for AUTHNAME</li> 1000 1001<li>SASL_CB_GETREALM - Realm of the server</li> 1002</ul> 1003 1004An example of a way to handle callbacks: 1005 1006<pre> 1007 /* callbacks we support. This is a global variable at the 1008 top of the program */ 1009 static sasl_callback_t callbacks[] = { 1010 { 1011 SASL_CB_GETREALM, NULL, NULL /* we'll just use an interaction if this comes up */ 1012 }, { 1013 SASL_CB_USER, NULL, NULL /* we'll just use an interaction if this comes up */ 1014 }, { 1015 SASL_CB_AUTHNAME, &getauthname_func, NULL /* A mechanism should call getauthname_func 1016 if it needs the authentication name */ 1017 }, { 1018 SASL_CB_PASS, &getsecret_func, NULL /* Call getsecret_func if need secret */ 1019 }, { 1020 SASL_CB_LIST_END, NULL, NULL 1021 } 1022 }; 1023 1024 1025 static int getsecret_func(sasl_conn_t *conn, 1026 void *context __attribute__((unused)), 1027 int id, 1028 sasl_secret_t **psecret) 1029 { 1030 [ask the user for their secret] 1031 1032 [allocate psecret and insert the secret] 1033 1034 return SASL_OK; 1035 } 1036 1037 static int getauthname_func(void *context, 1038 int id, 1039 const char **result, 1040 unsigned *len) 1041 { 1042 if (id!=SASL_CB_AUTHNAME) return SASL_FAIL; 1043 1044 [fill in result and len] 1045 1046 return SASL_OK; 1047 } 1048 1049 1050 in the main program somewhere 1051 1052 sasl_client_init(callbacks); 1053 1054 1055</pre> 1056 1057<h3><a name="layers">Security layers</a></h3> 1058 1059<p>All is well and good to securely authenticate, but if you don't 1060have some sort of integrity or privacy layer, anyone can hijack 1061your TCP session after authentication. If your application has 1062indicated that it can support a security layer, one <i>might</i> be 1063negotiated.</p> 1064 1065<p>To set that you support a security layer, set a security 1066property structure with <tt>max_ssf</tt> set to a non-zero 1067number:</p> 1068 1069<pre> 1070 sasl_security_properties_t secprops; 1071 1072 secprops.min_ssf = 0; 1073 secprops.max_ssf = 256; 1074 secprops.maxbufsize = /* SEE BELOW */; 1075 1076 secprops.property_names = NULL; 1077 secprops.property_values = NULL; 1078 secprops.security_flags = SASL_SEC_NOANONYMOUS; /* as appropriate */ 1079 1080 sasl_setprop(conn, SASL_SEC_PROPS, &secprops); 1081</pre> 1082 1083The <tt>secprops</tt> variable will be copied during the call to 1084<tt>sasl_setprop</tt>, so you may free its memory immediately. The 1085<i>SSF</i> stands for <i>security strength factor</i> and is a 1086rough indication of how "secure" the connection is. A connection 1087supplying only integrity with no privacy would have an SSF of 1. A 1088connection secured by 56-bit DES would have an SSF of 56. 1089 1090<p>To require a security layer, set <tt>min_ssf</tt> to the minimum 1091acceptable security layer strength.</p> 1092 1093<p>After authentication is successful, you can determine whether or 1094not a security layer has been negotiated by looking at the SASL_SSF 1095property:</p> 1096 1097<pre> 1098 const int *ssfp; 1099 1100 result = sasl_getprop(conn, SASL_SSF, (const **) &ssfp); 1101 if (result != SASL_OK) { 1102 /* ??? */ 1103 } 1104 if (*ssfp > 0) { 1105 /* yay, we have a security layer! */ 1106 } 1107</pre> 1108 1109<p>If a security layer has been negotiated, your application must 1110make use of the <tt>sasl_encode()</tt> and <tt>sasl_decode()</tt> 1111calls. All output must be passed through <tt>sasl_encode()</tt> 1112before being written to the wire; all input must be passed through 1113<tt>sasl_decode()</tt> before being looked at by the application. 1114Your application must also be prepared to deal with 1115<tt>sasl_decode()</tt> not returning any data in the rare case that 1116the peer application did something strange (by splitting a single 1117SASL blob into two seperate TCP packets).</p> 1118 1119<p>The only subtlety dealing with security layers is the maximum size 1120of data that can be passed through <tt>sasl_encode()</tt> or 1121<tt>sasl_decode()</tt>. This must be limited to make sure that only 1122a finite amount of data needs to be buffered. The simple rules to 1123follow:</p> 1124 1125<ul> 1126<li>Before starting authentication, set <tt>maxbufsize</tt> in your 1127security properties to be the buffer size that you pass to the 1128<tt>read()</tt> system call—that is, the amount of data 1129you're prepared to read at any one time.</li> 1130 1131<li>After authentication finishes, use <tt>sasl_getprop()</tt> to 1132retrieve the <tt>SASL_MAXOUTBUF</tt> value, and call 1133<tt>sasl_encode()</tt> with chunks of data of that size or less. 1134<tt>sasl_encode()</tt> will throw an error if you call it with a 1135larger chunk of data, so be careful!</li> 1136</ul> 1137 1138<p><b>Memory management:</b> As usual, whoever allocates the memory 1139must free it. The SASL library will keep the data returned from 1140<tt>sasl_encode()</tt> until the next call to <tt>sasl_encode()</tt> 1141on that connection. (<tt>sasl_decode()</tt> results persist until the 1142next call to <tt>sasl_decode()</tt> on that connection.) The 1143application must not attempt to free the memory returned from either 1144function.</p> 1145 1146<p><b>Internally:</b></p> 1147 1148<ul> 1149<li>your application sets SASL_SEC_PROPS with the buffer size X of 1150the amount of data it will be using to read() from the socket.</li> 1151 1152<li>libsasl passes this number to the mechanism.</li> 1153 1154<li>the mechanism passes this number to the other side. the other 1155side gives the corresponding read() size to our side.</li> 1156 1157<li>the mechanism subtracts the overhead of the layers from the 1158size retrieved from the other side and returns it to the 1159libsasl.</li> 1160 1161<li>libsasl then returns (via SASL_MAXOUTBUF) this number as the 1162maximum amount of plaintext material that can be encoded at any one 1163time, Y.</li> 1164 1165<li>sasl_encode() enforces the restriction of the length Y.</li> 1166</ul> 1167 1168<h2><a name="example_section">Example applications that come with 1169the Cyrus SASL library</a></h2> 1170 1171<h3><a name="sample_client"><tt>sample-client</tt> and 1172<tt>sample-server</tt></a></h3> 1173 1174The sample client and server included with this distribution were 1175initially written to help debug mechanisms. They base64 encode all 1176the data and print it out on standard output. 1177 1178<p>Make sure that you set the IP addresses, the username, the 1179authenticate name, and anything else on the command line (some 1180mechanisms depend on these being present).</p> 1181 1182<p>Also, sometimes you will receive a get "<tt>realm: Information 1183not available</tt>" message, or similar; this is due to the fact 1184that some mechanisms do not support realms and therefore never set 1185it.</p> 1186 1187<h3><a name="cyrus_imapd">Cyrus imapd v2.1.0 or later</a></h3> 1188 1189The Cyrus IMAP server now incorporates SASLv2 for all its 1190authentication needs. It is a good example of a fairly large server 1191application. Also of interest is the prot layer, included in 1192libcyrus. This is a stdio-like interface that automatically takes 1193care of layers using a simple "<tt>prot_setsasl()</tt>" call. 1194 1195<p>Cyrus imapd also sets a <tt>SASL_CB_PROXY_POLICY</tt> callback, 1196which should be of interest to many applications.</p> 1197 1198<h3><a name="imtest"><tt>imtest</tt>, from Cyrus 2.1.0 or 1199later</a></h3> 1200 1201<tt>imtest</tt> is an application included with Cyrus imapd. It is 1202a very simple IMAP client, but should be of interest to those 1203writing applications. It also uses the prot layer, but it is easy 1204to incorporate similar support without using the prot layer. 1205Likewise, there are other sample client applications that you can 1206look at including <tt>smtptest</tt> and <tt>pop3test</tt> in the 1207SASL distribution and the Cyrus IMAPd distribution, respectively. 1208 1209<h2><a name="random_things">Miscellaneous Information</a></h2> 1210 1211<h3><a name="empty_exchanges">Empty exchanges</a></h3> 1212 1213<p>Some SASL mechanisms intentionally send no data; an application 1214should be prepared to either send or receive an empty exchange. The 1215SASL profile for the protocol should define how to send an empty 1216string; make sure to send an empty string when requested, and when 1217receiving an empty string make sure that the "<tt>inlength</tt>" 1218passed in is 0.</p> 1219 1220<p>Note especially that the distinction between the empty string "" 1221and the lack of a string (NULL) is extremely important in many 1222cases (most notably, the client-send first scenario), and the 1223application must ensure that it is passing the correct values to 1224the SASL library at all times.</p> 1225 1226<h3><a name="idle">Idle</a></h3> 1227 1228While the implementation and the plugins correctly implement the 1229idle calls, none of them currently do anything. 1230 1231<hr> 1232Please send any questions or comments to: 1233 1234<address><a href= 1235"mailto:cyrus-bugs@andrew.cmu.edu">cyrus-bugs@andrew.cmu.edu</a></address> 1236 1237<br> 1238 Back to the <a href="index.html">index</a> 1239</body> 1240</html> 1241 1242