1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
4 <meta name="generator" content="HTML Tidy, see www.w3.org">
5 <title>SASL Application Programmer's Guide</title>
8 <h1>SASL Application Programmer's Guide</h1>
10 <h3>NOTE: This is a work in progress. Any contributions would be
11 <i>very</i> appreciated</h3>
16 <li><a href="#intro">Introduction</a>
19 <li><a href="#about_this_guide">About this guide</a></li>
21 <li><a href="#what_is_sasl">What is SASL?</a></li>
25 <li><a href="#background">Background</a>
28 <li><a href="#world_before">How did the world work before
31 <li><a href="#sasl_rescue">SASL to the rescue!</a></li>
35 <li><a href="#briefly">Briefly</a>
38 <li><a href="#what_good_for">What is the Cyrus SASL library good
41 <li><a href="#what_do">What does the Cyrus SASL library
44 <li><a href="#what_doesnt">What doesn't the Cyrus SASL library
49 <li><a href="#client_only">Client-only Section</a>
52 <li><a href="#client_typical">A typical interaction from the
53 client's perspective</a></li>
55 <li><a href="#client_code">How does this look in code?</a></li>
57 <li><a href="#sasl_client_init">sasl_client_init</a></li>
59 <li><a href="#sasl_client_new">sasl_client_new</a></li>
61 <li><a href="#sasl_client_start">sasl_client_start</a></li>
63 <li><a href="#sasl_client_step">sasl_client_step</a></li>
67 <li><a href="#server_section">Server-only Section</a>
70 <li><a href="#server_typical">A typical interaction from the
71 server's perspective</a></li>
73 <li><a href="#server_code">How does this look in code?</a></li>
75 <li><a href="#sasl_server_init">sasl_server_init</a></li>
77 <li><a href="#sasl_server_new">sasl_server_new</a></li>
79 <li><a href="#sasl_server_start">sasl_server_start</a></li>
81 <li><a href="#sasl_server_step">sasl_server_step</a></li>
83 <li><a href="#sasl_listmech">sasl_listmech</a></li>
85 <li><a href="#sasl_checkpass">sasl_checkpass</a></li>
89 <li><a href="#common_section">Common Section</a>
92 <li><a href="#callbacks_interactions">Callbacks and
95 <li><a href="#layers">Security layers</a></li>
99 <li><a href="#example_section">Example applications that come with
100 the Cyrus SASL library</a>
103 <li><a href="#sample_client"><tt>sample-client</tt> and
104 <tt>sample-server</tt></a></li>
106 <li><a href="#cyrus_imapd">Cyrus imapd v2.1.0 or later</a></li>
108 <li><a href="#imtest"><tt>imtest</tt>, from cyrus imapd 2.1.0 or
113 <li><a href="#random_things">Miscellaneous Information</a>
116 <li><a href="#empty_exchanges">Empty exchanges</a></li>
121 <h2><a name="intro">Introduction</a></h2>
123 <h3><a name="about_this_guide">About this Guide</a></h3>
125 <p>This guide gives a tutorial on the use of the Cyrus SASL library
126 for a client or server application. It complies with versions
127 including and after 2.0.0. The following pages should only be
128 considered a guide, not the final word on programming with the
129 Cyrus SASL library. Consult the header files in the distribution in
130 the case of ambiguities.</p>
132 <h3><a name="what_is_sasl">What is SASL?</a></h3>
134 <p>SASL stands for Simple Authentication Security Layer and is
135 explained in <a href="http://ftp.ietf.org/rfc/rfc2222.txt">RFC
136 2222</a>. That document is very difficult to understand however and
137 it should be unnecessary to consult it.</p>
139 <h2><a name="background">Background</a></h2>
141 <h3><a name="world_before">How did the world work before
144 <p>Before SASL, when a new protocol was written which required
145 authentication (users proving who they are to an entity), the
146 protocol had to allow explicitly for each individual authentication
147 mechanism. There had to be a distinct way to say "I want to log in
148 with Kerberos V4". There had to be another distinct way to say "I
149 want to log in with CRAM-MD5". There had to be yet a different way
150 to say "I want to log in anonymously," and so on. This was
151 non-ideal for both the protocol and application writers.</p>
153 <p>Additionally, many programmers were not very familiar with
154 security, so the protocol did support many mechanisms, or worse,
155 they were supported incorrectly. Moreover, when a new
156 authentication method was invented the protocol needed to be
157 modified to support that mechanism.</p>
159 <p>This system also was not ideal for application writer. She had
160 to have a special case for each mechanism she wished her
161 application to support. Also, the mechanisms were difficult to
162 implement. Even with a good library, an understanding of how the
163 mechanism worked was still necessary. Finally if an application
164 used more than one protocol (for example a mail client might use
165 IMAP, POP, and SMTP) then "Kerberos V4 for IMAP", "Kerberos V4 for
166 POP", "Kerberos V4 for SMTP", "CRAM MD5 for IMAP", "CRAM-MD5 for
167 POP", etc... would need to be written. This could quickly create a
168 huge number of different mechanism-protocol pairs to implement.</p>
170 <h3><a name="sasl_rescue">SASL to the rescue!</a></h3>
172 <p>SASL hopefully solves all these problems. In practice it makes
173 many of them easier to deal with.</p>
175 <p>Protocol designers simply have to support SASL (in particular
176 RFC 2222). Consequently, any mechanism that supports SASL (just
177 about anything you would want to use does now) is supported by the
178 protocol. If a new authentication mechanism is invented the
179 protocol automatically supports it without any modifications.</p>
181 <p>Application writers, instead of having to support every
182 mechanism for every protocol, only need to support SASL for every
183 protocol. Application writers do not need to understand the
184 authentication mechanisms at all: the SASL library handles all
185 that. Also with the Cyrus SASL library if a new mechanism is
186 invented you do not have rewrite your application at all. You may
187 not even have to restart your application if it is a long running
188 process. This is because the Cyrus SASL library loads each
189 mechanism from a shared library. Simply copying a shared library
190 into a directory will magically make your application support a new
193 <p>Cyrus SASL version 2 supports a much improved API over version
194 1, that allows for much smarter and faster memory allocation for
195 the mechanisms as well as the applications. It is also provides for
196 several new types of plugins to allow for greater overall
197 flexibility. Unfortunately, though similar, this new API is
198 completely incompatible with the old API, and applications will
199 need to be rewritten.</p>
201 <h2><a name="briefly">Briefly</a></h2>
203 <h3><a name="what_good_for">What is the Cyrus SASL library good
206 <p>The Cyrus SASL library is good for applications that wish to use
207 protocols that support SASL authentication. An non-exhaustive list
208 of these are: IMAP, SMTP, ACAP, and LDAP. Also if you are making a
209 proprietary system and wish to support authentication it is a good
210 way of supporting many different authentication types.</p>
212 <h3><a name="what_do">What does the Cyrus SASL library do?</a></h3>
214 <p>From a client point of view, the Cyrus SASL library, given a
215 list of mechanisms the server supports it will decide the best
216 mechanism to use and tell you what to send to the server at each
217 step of the authentication. From a server perspective, it handles
218 authentication requests from clients.</p>
220 <h3><a name="what_doesnt">What doesn't the Cyrus SASL library
223 <p>The Cyrus SASL library is neither network nor protocol aware. It
224 is up to the application to send the data over the wire as well as
225 to send the data in the protocol specific manner. With IMAP this
226 means putting it in the form: <tt>+ [base64'ed data]\r\n</tt>. LDAP
227 just sends data in binary via bind requests. The Cyrus SASL library
228 has utility base64 encode and decode routines to help with
231 <h2><a name="client_section">Client-only Section</a></h2>
233 <h3><a name="client_typical">A typical interaction from the
234 client's perspective</a></h3>
237 <li>A client makes a few calls (explained later) to initialize
240 <li>Every time the client application makes a new connection it
241 should make a new context that is kept for the life of the
244 <li>Ask the server for the list of supported mechanisms</li>
246 <li>Feed this list to the library</li>
248 <li>Start the authentication with the mechanism the library
251 <li>The server will return some bytes</li>
253 <li>Give these to the library</li>
255 <li>The library returns some bytes to the application</li>
257 <li>Application sends these bytes over the network</li>
259 <li>repeat the last 4 steps until the server tells you that the
260 authentication is completed</li>
263 <h3><a name="client_code">How does this look in code</a></h3>
265 <b>Initialize the library</b>. (done once).
271 /* attempt to start sasl
272 * See the section on Callbacks and Interactions for an
273 * explanation of the variable callbacks
276 result=sasl_client_init(callbacks);
278 /* check to see if that worked */
279 if (result!=SASL_OK) [failure]
283 <b>For every network connection, make a new SASL connection</b>:
287 /* The SASL context kept for the life of the connection */
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
296 NULL, NULL, /* Local and remote IP
298 (NULL disables mechanisms
299 which require this info)*/
300 NULL, /* connection-specific
302 0, /* security flags */
303 &conn); /* allocated on success */
305 /* check to see if that worked */
306 if (result!=SASL_OK) [failure]
311 Next get the list of SASL mechanisms the server supports. This is
312 usually done through a capability command. Format the list as a
313 single string separated by spaces. Feed this string into SASL to
314 begin the authentication process.
318 sasl_interact_t *client_interact=NULL;
319 const char *out, *mechusing;
324 result=sasl_client_start(conn, /* the same context from
326 mechlist, /* the list of mechanisms
328 &client_interact, /* filled in if an
329 interaction is needed */
330 &out, /* filled in on success */
331 &outlen, /* filled in on success */
334 if (result==SASL_INTERACT)
336 [deal with the interactions. See interactions section below]
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]
348 Note that you do not need to worry about the allocation and freeing
349 of the output buffer out. This is all handled inside of the
350 mechanism. It is important to note, however, that the output buffer
351 is not valid after the next call to <tt>sasl_client_start</tt> or
352 <tt>sasl_client_step</tt>.
354 <p>If this is successful send the protocol specific command to
355 start the authentication process. This may or may not allow for
356 initial data to be sent (see the documentation of the protocol to
360 For IMAP this might look like:
361 {tag} "AUTHENTICATE" {mechusing}\r\n
362 A01 AUTHENTICATE KERBEROS_V4\r\n
365 "AUTH" {mechusing}[ {out base64 encoded}]
366 AUTH DIGEST-MD5 GHGJJGDDFDKHGHJG=
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
376 <li>Authentication failure. Authentication process is halted. This
377 might look like <tt>A01 NO Authentication failure</tt> in IMAP or
378 <tt>501 Failed</tt> in SMTP. Either retry the authentication or
381 <li>Authentication success. We're now successfully authenticated.
382 This might look like <tt>A01 OK Authenticated successful</tt> in
383 IMAP or <tt>235 Authentication successful</tt> in SMTP. Go <a href=
384 "#client_authentication_success">here</a></li>
386 <li>Another step in the authentication process is necessary. This
387 might look like <tt>+ HGHDS1HAFJ=</tt> in IMAP or <tt>334
388 PENCeUxFREJoU0NnbmhNWitOMjNGNndAZWx3b29kLmlubm9zb2Z0LmNvbT4=</tt>
389 in SMTP. Note it could be an empty string such as <tt>+ \r\n</tt>
393 Convert the continuation data to binary format (for example, this
394 may include base64 decoding it). Perform another step in the
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 */
407 if (result==SASL_INTERACT)
409 [deal with the interactions. See below]
413 } while (result==SASL_INTERACT || result == SASL_CONTINUE);
415 if (result!=SASL_OK) [failure]
420 Format the output (variable out of length outlen) in the protocol
421 specific manner and send it across the network to the server. <br>
422 Goto <a href="#client_authentication_step">here</a> (this process
423 repeats until authentication either succeeds or fails. <br>
426 <a name="client_authentication_success"><b>Authentication
427 Successful</b></a><br>
431 <p>Before we're done we need to call sasl_client_step() one more
432 time to make sure the server isn't trying to fool us. Some
433 protocols include data along with the last step. If so this data
434 should be used here. If not use a length of zero.</p>
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 */
444 if (result!=SASL_OK) [failure]
448 <p>Congratulations. You have successfully authenticated to the
451 <p>Don't throw away the SASL connection object (sasl_conn_t *) yet
452 though. If a security layer was negotiated you will need it to
453 encode and decode the data sent over the network.</p>
456 When you are finally done with connection to server, dispose of
461 sasl_dispose(&conn);
466 If you are done with SASL forever (application quiting for
474 <h3>sasl_client_init</h3>
477 int sasl_client_init(const sasl_callback_t *callbacks);
484 <li>callbacks - List of callbacks. See Callbacks section</li>
487 This function initializes the SASL library. This must be called
488 before any other SASL calls. See the callbacks section for complete
489 description of callbacks.
491 <h3>sasl_client_new</h3>
494 int sasl_client_new(const char *service,
495 const char *serverFQDN,
496 const char *iplocalport,
497 const char *ipremoteport,
498 const sasl_callback_t *prompt_supp,
500 sasl_conn_t **pconn);
507 <li>service - the service name being used. This usually is the
508 protocol name (e.g. "ldap")</li>
510 <li>serverFQDN - Fully qualified domain name of server</li>
512 <li>iplocalport and ipremoteport - a string of the format
513 "a.b.c.d;p" detailing the local or remote IP and port, or NULL
514 (which will disable mechanisms that require this information)</li>
516 <li>prompt_supp - List off callbacks specific to this
519 <li>secflags - security flags ORed together requested (e.g.
520 SASL_SEC_NOPLAINTEXT)</li>
522 <li>pconn - the SASL connection object allocated upon success</li>
525 This function creates a new SASL connection object. It should be
526 called once for every connection you want to authenticate for.
528 <h3>sasl_client_start</h3>
531 int sasl_client_start(sasl_conn_t *conn,
532 const char *mechlist,
533 sasl_interact_t **prompt_need,
534 const char **clientout,
535 unsigned *clientoutlen,
543 <li>conn - the SASL connection object gotten from
544 sasl_client_new()</li>
546 <li>mechlist - the list of mechanisms to try (separated by
549 <li>prompt_need - filled in when a SASL_INTERACT is returned</li>
551 <li>clientout - filled in upon success with data to send to
554 <li>clientoutlen - length of that data</li>
556 <li>mech - filled in with mechanism being used</li>
559 This function starts an authentication session. It takes a list of
560 possible mechanisms (usually gotten from the server through a
561 capability command) and chooses the "best" mechanism to try. Upon
562 success clientout points at data to send to the server.
564 <h3>sasl_client_step</h3>
567 int sasl_client_step(sasl_conn_t *conn,
568 const char *serverin,
569 unsigned serverinlen,
570 sasl_interact_t **prompt_need,
571 const char **clientout,
572 unsigned *clientoutlen);
579 <li>conn - the SASL connection object gotten from
580 sasl_client_new()</li>
582 <li>serverin - data from the server</li>
584 <li>serverinlen - length of data from the server</li>
586 <li>prompt_need - filled in with a SASL_INTERACT is returned</li>
588 <li>clientout - filled in upon success with data to send to
591 <li>clientoutlen - length of that data</li>
594 This step preforms a step in the authentication process. It takes
595 the data from the server (serverin) and outputs data to send to the
596 server (clientout) upon success. SASL_CONTINUE is returned if
597 another step in the authentication process is necessary. SASL_OK is
598 returned if we're all done.
600 <h2><a name="server_section">Server-only Section</a></h2>
602 <h3><a name="server_typical">A typical interaction from the
603 server's perspective</a></h3>
605 The server makes a few Cyrus SASL calls for initialization. When it
606 gets a new connection it should make a new context for that
607 connection immediately. The client may then request a list of
608 mechanisms the server supports. The client also may request to
609 authenticate at some point. The client will specify the mechanism
610 it wishes to use. The server should negotiate this authentication
611 and keep around the context afterwards for encoding and decoding
614 <h3><a name="server_code">How does this look in code?</a></h3>
616 Initialization (done once). The application name is used for
617 reading configuration information.
623 /* Initialize SASL */
624 result=sasl_server_init(callbacks, /* Callbacks supported */
625 "TestServer"); /* Name of the application */
630 This should be called for each new connection. It probably should
631 be called right when the socket is accepted.
637 /* Make a new context for this connection */
638 result=sasl_server_new("smtp", /* Registered name of service */
639 NULL, /* my fully qualified domain name;
640 NULL says use gethostname() */
641 NULL, /* The user realm used for password
642 lookups; NULL means default to serverFQDN
643 Note: This does not affect Kerberos */
644 NULL, NULL, /* IP Address information strings */
645 NULL, /* Callbacks supported only for this connection */
646 0, /* security flags (security layers are enabled
647 * using security properties, separately)
653 When a client requests the list of mechanisms supported by the
654 server. This particular call might produce the string: <i>"{PLAIN,
655 KERBEROS_V4, CRAM-MD5, DIGEST-MD5}"</i>
658 result=sasl_listmech(conn, /* The context for this connection */
659 NULL, /* not supported */
660 "{", /* What to prepend the string with */
661 ", ", /* What to separate mechanisms with */
662 "}", /* What to append to the string */
663 &result_string, /* The produced string. */
664 &string_length, /* length of the string */
665 &number_of_mechanisms); /* Number of mechanisms in
671 When a client requests to authenticate:
678 result=sasl_server_start(conn, /* context */
679 mechanism_client_chose,
680 clientin, /* the optional string the client gave us */
681 clientinlen, /* and it's length */
682 &out, /* The output of the library.
683 Might not be NULL terminated */
686 if ((result!=SASL_OK) && (result!=SASL_CONTINUE))
687 [failure. Send protocol specific message that says authentication failed]
688 else if (result==SASL_OK)
689 [authentication succeeded. Send client the protocol specific message
690 to say that authentication is complete]
692 [send data 'out' with length 'outlen' over the network in protocol
697 When a response is returned by the client. <i>clientin</i> is the
698 data from the client decoded from protocol specific format to a
699 string of bytes of length <i>clientinlen</i>. This step may occur
700 zero or more times. An application must be able to deal with it
701 occurring an arbitrary number of times.
706 result=sasl_server_step(conn,
707 clientin, /* what the client gave */
708 clientinlen, /* it's length */
709 &out, /* allocated by library on success.
710 Might not be NULL terminated */
713 if ((result!=SASL_OK) && (result!=SASL_CONTINUE))
714 [failure. Send protocol specific message that says authentication failed]
715 else if (result==SASL_OK)
716 [authentication succeeded. Send client the protocol specific message
717 to say that authentication is complete]
719 [send data 'out' with length 'outlen' over the network in protocol
724 This continues until authentication succeeds. When the connection
725 is concluded, make a call to <tt>sasl_dispose</tt> as with the
728 <h3><a name="sasl_server_init">sasl_server_init</a></h3>
731 int sasl_server_init(const sasl_callback_t *callbacks,
732 const char *appname);
738 <li>callbacks - A list of callbacks supported by the application
739 (see Interaction and Callbacks section)</li>
741 <li>appname - A string of the name of the application. This string
742 is what is used when loading configuration options.</li>
745 sasl_server_init() initializes the session. This should be the
746 first function called. In this function the shared library
747 authentication mechanisms are loaded.
749 <h3><a name="sasl_server_new">sasl_server_new</a></h3>
752 int sasl_server_new(const char *service,
753 const char *serverFQDN,
754 const char *user_realm,
755 const char *iplocalport,
756 const char *ipremoteport,
757 const sasl_callback_t *callbacks,
759 sasl_conn_t **pconn);
765 <li>service - The name of the service you are supporting. This
766 might be "acap" or "smtp". This is used by Kerberos mechanisms and
767 possibly other mechanisms. It is also used for PAM
770 <li>serverFQDN - This is the fully qualified domain name of the
771 server (i.e. your hostname); if NULL, the library calls
772 <tt>gethostbyname()</tt>.</li>
774 <li>user_realm - The realm the connected client is in. The Kerberos
775 mechanisms ignore this parameter and default to the local Kerberos
776 realm. A value of NULL makes the library default, usually to the
777 serverFQDN; a value of "" specifies that the client should specify
778 the realm; this also changes the semantics of "@" in a username for
779 mechanisms that don't support realms.</li>
781 <li>iplocalport and ipremoteport - a string of the format
782 "a.b.c.d;p" detailing the local or remote IP and port, or NULL
783 (which will disable mechanisms that require this information)</li>
785 <li>callbacks - Additional callbacks that you wish only to apply to
786 this connection.</li>
788 <li>secflags - security flags.</li>
790 <li>pconn - Context. Filled in on success.</li>
793 <h3><a name="sasl_server_start">sasl_server_start</a></h3>
796 int sasl_server_start(sasl_conn_t *conn,
798 const char *clientin,
799 unsigned clientinlen,
800 const char **serverout,
801 unsigned *serveroutlen);
808 <li>conn - The context for the connection</li>
810 <li>mech - The authentication mechanism the client wishes to try
811 (e.g. <tt>KERBEROS_V4</tt>)</li>
813 <li>clientin - Initial client challenge bytes. Note: some protocols
814 do not allow this. If this is the case passing NULL is valid</li>
816 <li>clientinlen - The length of the challenge. 0 is there is
819 <li>serverout - allocated and filled in by the function. These are
820 the bytes that should be encoded as per the protocol and sent over
821 the network back to the client.</li>
823 <li>serveroutlen - length of bytes to send to client</li>
826 This function begins the authentication process with a client. If
827 the program returns SASL_CONTINUE that means <tt>serverout</tt>
828 should be sent to the client. If SASL_OK is returned that means
829 authentication is complete and the application should tell the
830 client the authentication was successful. Any other return code
831 means the authentication failed and the client should be notified
834 <h3><a name="sasl_server_step">sasl_server_step</a></h3>
837 int sasl_server_step(sasl_conn_t *conn,
838 const char *clientin,
839 unsigned clientinlen,
840 const char **serverout,
841 unsigned *serveroutlen);
848 <li>conn - The context for the connection</li>
850 <li>clientin - Data sent by the client.</li>
852 <li>clientinlen - The length of the client data. Note that this may
855 <li>serverout - allocated and filled in by the function. These are
856 the bytes that should be encoded as per the protocol and sent over
857 the network back to the client.</li>
859 <li>serveroutlen - length of bytes to send to client. Note that
863 This function preforms a step of the authentication. This may need
864 to be called an arbitrary number of times. If the program returns
865 SASL_CONTINUE that means <tt>serverout</tt> should be sent to the
866 client. If SASL_OK is returned that means authentication is
867 complete and the application should tell the client the
868 authentication was successful. Any other return code means the
869 authentication failed and the client should be notified of this.
871 <h3><a name="sasl_listmech">sasl_listmech</a></h3>
874 int sasl_listmech(sasl_conn_t *conn,
888 <li>conn - The context for this connection</li>
890 <li>user - Currently not implemented</li>
892 <li>prefix - The string to prepend</li>
894 <li>sep - The string to separate mechanisms with</li>
896 <li>suffix - The string to end with</li>
898 <li>result - Resultant string</li>
900 <li>plen - Number of characters in the result string</li>
902 <li>pcount - Number of mechanisms listed in the result string</li>
905 This function is used to create a string with a list of SASL
906 mechanisms supported by the server. This string is often needed for
907 a capability statement.
909 <h3><a name="sasl_checkpass">sasl_checkpass</a></h3>
912 int sasl_checkpass(sasl_conn_t *conn,
923 <li>conn - The context for this connection</li>
925 <li>user - The user trying to check the password for</li>
927 <li>userlen - The user length</li>
929 <li>pass - The password</li>
931 <li>passlen - The password length</li>
934 This checks a plaintext password <i>pass</i> for user <i>user</i>
935 Some protocols have legacy systems for plaintext authentication
936 where this might be used.
938 <h2><a name="common_section">Common Section</a></h2>
940 <h3><a name="callbacks_interactions">Callbacks and
941 Interactions</a></h3>
943 When the application starts and calls sasl_client_init() you must
944 specify for what data you support callbacks and/or interactions.
945 These are for the library getting information needed for
946 authentication from the application. This is needed for things like
947 authentication name and password. If you do not declare supporting
948 a callback you will not be able to use mechanisms that need that
949 data. A callback is for when you have the information before you
950 start the authentication. The SASL library calls a function you
951 specify and your function fills in the requested information. For
952 example if you had the userid of the user already for some reason.
953 An interaction is usually for things you support but will need to
954 ask the user for (e.g. password). sasl_client_start() or
955 sasl_client_step() will return SASL_INTERACT. This will be a list
956 of sasl_interact_t's which contain a human readable string you can
957 prompt the user with, a possible computer readable string, and a
958 default result. The nice thing about interactions is you get them
959 all at once so if you had a GUI application you could bring up a
960 dialog box asking for authentication name and password together
961 instead of one at a time.
963 <p>Any memory that is given to the SASL library for the purposes of
964 callbacks and interactions must persist until the exchange
965 completes in either success or failure. That is, the data must
966 persist until <tt>sasl_client_start</tt> or
967 <tt>sasl_client_step</tt> returns something other than
968 <tt>SASL_INTERACT</tt> or <tt>SASL_CONTINUE</tt>.</p>
970 <p><b>Memory management:</b>As in the rest of the SASLv2 API,
971 whoever allocates the memory is responsible for freeing it. In
972 almost all cases this should be fairly easy to manage, however a
973 slight exception where the interaction sasl_interact_t structure is
974 allocated and freed by the library, while the results are allocated
975 and freed by the application. As noted above, however, <i>the
976 results may not be freed until after the exchange completes, in
977 either success or failure</i>.</p>
979 <p>For a detailed description of what each of the callback types
980 are see the sasl.h file. Here are some brief explanations:</p>
983 <li>SASL_CB_AUTHNAME - the name of the user authenticating</li>
985 <li>SASL_CB_USER - the name of the user acting for. (for example
986 postman delivering mail for tmartin might have an AUTHNAME of
987 postman and a USER of tmartin)</li>
989 <li>SASL_CB_PASS - password for AUTHNAME</li>
991 <li>SASL_CB_GETREALM - Realm of the server</li>
994 An example of a way to handle callbacks:
997 /* callbacks we support. This is a global variable at the
998 top of the program */
999 static sasl_callback_t callbacks[] = {
1001 SASL_CB_GETREALM, NULL, NULL /* we'll just use an interaction if this comes up */
1003 SASL_CB_USER, NULL, NULL /* we'll just use an interaction if this comes up */
1005 SASL_CB_AUTHNAME, &getauthname_func, NULL /* A mechanism should call getauthname_func
1006 if it needs the authentication name */
1008 SASL_CB_PASS, &getsecret_func, NULL /* Call getsecret_func if need secret */
1010 SASL_CB_LIST_END, NULL, NULL
1015 static int getsecret_func(sasl_conn_t *conn,
1016 void *context __attribute__((unused)),
1018 sasl_secret_t **psecret)
1020 [ask the user for their secret]
1022 [allocate psecret and insert the secret]
1027 static int getauthname_func(void *context,
1029 const char **result,
1032 if (id!=SASL_CB_AUTHNAME) return SASL_FAIL;
1034 [fill in result and len]
1040 in the main program somewhere
1042 sasl_client_init(callbacks);
1047 <h3><a name="layers">Security layers</a></h3>
1049 <p>All is well and good to securely authenticate, but if you don't
1050 have some sort of integrity or privacy layer, anyone can hijack
1051 your TCP session after authentication. If your application has
1052 indicated that it can support a security layer, one <i>might</i> be
1055 <p>To set that you support a security layer, set a security
1056 property structure with <tt>max_ssf</tt> set to a non-zero
1060 sasl_security_properties_t secprops;
1062 secprops.min_ssf = 0;
1063 secprops.max_ssf = 256;
1064 secprops.maxbufsize = /* SEE BELOW */;
1066 secprops.property_names = NULL;
1067 secprops.property_values = NULL;
1068 secprops.security_flags = SASL_SEC_NOANONYMOUS; /* as appropriate */
1070 sasl_setprop(conn, SASL_SEC_PROPS, &secprops);
1073 The <tt>secprops</tt> variable will be copied during the call to
1074 <tt>sasl_setprop</tt>, so you may free its memory immediately. The
1075 <i>SSF</i> stands for <i>security strength factor</i> and is a
1076 rough indication of how "secure" the connection is. A connection
1077 supplying only integrity with no privacy would have an SSF of 1. A
1078 connection secured by 56-bit DES would have an SSF of 56.
1080 <p>To require a security layer, set <tt>min_ssf</tt> to the minimum
1081 acceptable security layer strength.</p>
1083 <p>After authentication is successful, you can determine whether or
1084 not a security layer has been negotiated by looking at the SASL_SSF
1090 result = sasl_getprop(conn, SASL_SSF, (const **) &ssfp);
1091 if (result != SASL_OK) {
1095 /* yay, we have a security layer! */
1099 <p>If a security layer has been negotiated, your application must
1100 make use of the <tt>sasl_encode()</tt> and <tt>sasl_decode()</tt>
1101 calls. All output must be passed through <tt>sasl_encode()</tt>
1102 before being written to the wire; all input must be passed through
1103 <tt>sasl_decode()</tt> before being looked at by the application.
1104 Your application must also be prepared to deal with
1105 <tt>sasl_decode()</tt> not returning any data in the rare case that
1106 the peer application did something strange (by splitting a single
1107 SASL blob into two seperate TCP packets).</p>
1109 <p>The only subtlety dealing with security layers is the maximum size
1110 of data that can be passed through <tt>sasl_encode()</tt> or
1111 <tt>sasl_decode()</tt>. This must be limited to make sure that only
1112 a finite amount of data needs to be buffered. The simple rules to
1116 <li>Before starting authentication, set <tt>maxbufsize</tt> in your
1117 security properties to be the buffer size that you pass to the
1118 <tt>read()</tt> system call—that is, the amount of data
1119 you're prepared to read at any one time.</li>
1121 <li>After authentication finishes, use <tt>sasl_getprop()</tt> to
1122 retrieve the <tt>SASL_MAXOUTBUF</tt> value, and call
1123 <tt>sasl_encode()</tt> with chunks of data of that size or less.
1124 <tt>sasl_encode()</tt> will throw an error if you call it with a
1125 larger chunk of data, so be careful!</li>
1128 <p><b>Memory management:</b> As usual, whoever allocates the memory
1129 must free it. The SASL library will keep the data returned from
1130 <tt>sasl_encode()</tt> until the next call to <tt>sasl_encode()</tt>
1131 on that connection. (<tt>sasl_decode()</tt> results persist until the
1132 next call to <tt>sasl_decode()</tt> on that connection.) The
1133 application must not attempt to free the memory returned from either
1136 <p><b>Internally:</b></p>
1139 <li>your application sets SASL_SEC_PROPS with the buffer size X of
1140 the amount of data it will be using to read() from the socket.</li>
1142 <li>libsasl passes this number to the mechanism.</li>
1144 <li>the mechanism passes this number to the other side. the other
1145 side gives the corresponding read() size to our side.</li>
1147 <li>the mechanism subtracts the overhead of the layers from the
1148 size retrieved from the other side and returns it to the
1151 <li>libsasl then returns (via SASL_MAXOUTBUF) this number as the
1152 maximum amount of plaintext material that can be encoded at any one
1155 <li>sasl_encode() enforces the restriction of the length Y.</li>
1158 <h2><a name="example_section">Example applications that come with
1159 the Cyrus SASL library</a></h2>
1161 <h3><a name="sample_client"><tt>sample-client</tt> and
1162 <tt>sample-server</tt></a></h3>
1164 The sample client and server included with this distribution were
1165 initially written to help debug mechanisms. They base64 encode all
1166 the data and print it out on standard output.
1168 <p>Make sure that you set the IP addresses, the username, the
1169 authenticate name, and anything else on the command line (some
1170 mechanisms depend on these being present).</p>
1172 <p>Also, sometimes you will receive a get "<tt>realm: Information
1173 not available</tt>" message, or similar; this is due to the fact
1174 that some mechanisms do not support realms and therefore never set
1177 <h3><a name="cyrus_imapd">Cyrus imapd v2.1.0 or later</a></h3>
1179 The Cyrus IMAP server now incorporates SASLv2 for all its
1180 authentication needs. It is a good example of a fairly large server
1181 application. Also of interest is the prot layer, included in
1182 libcyrus. This is a stdio-like interface that automatically takes
1183 care of layers using a simple "<tt>prot_setsasl()</tt>" call.
1185 <p>Cyrus imapd also sets a <tt>SASL_CB_PROXY_POLICY</tt> callback,
1186 which should be of interest to many applications.</p>
1188 <h3><a name="imtest"><tt>imtest</tt>, from Cyrus 2.1.0 or
1191 <tt>imtest</tt> is an application included with Cyrus imapd. It is
1192 a very simple IMAP client, but should be of interest to those
1193 writing applications. It also uses the prot layer, but it is easy
1194 to incorporate similar support without using the prot layer.
1195 Likewise, there are other sample client applications that you can
1196 look at including <tt>smtptest</tt> and <tt>pop3test</tt> in the
1197 SASL distribution and the Cyrus IMAPd distribution, respectively.
1199 <h2><a name="random_things">Miscellaneous Information</a></h2>
1201 <h3><a name="empty_exchanges">Empty exchanges</a></h3>
1203 <p>Some SASL mechanisms intentionally send no data; an application
1204 should be prepared to either send or receive an empty exchange. The
1205 SASL profile for the protocol should define how to send an empty
1206 string; make sure to send an empty string when requested, and when
1207 receiving an empty string make sure that the "<tt>inlength</tt>"
1210 <p>Note especially that the distinction between the empty string ""
1211 and the lack of a string (NULL) is extremely important in many
1212 cases (most notably, the client-send first scenario), and the
1213 application must ensure that it is passing the correct values to
1214 the SASL library at all times.</p>
1216 <h3><a name="idle">Idle</a></h3>
1218 While the implementation and the plugins correctly implement the
1219 idle calls, none of them currently do anything.
1222 Please send any questions or comments to:
1225 "mailto:cyrus-bugs@andrew.cmu.edu">cyrus-bugs@andrew.cmu.edu</a></address>
1228 Back to the <a href="index.html">index</a>