This guide gives a tutorial on the use of the Cyrus SASL library
    for a client or server application. It complies with versions up
    to and including 1.5.15. The following pages should only be
    considered a guide, not the final word on programming with the
    Cyrus SASL library. Consult the sasl.h file in the distribution in
    the case of ambiguities.
    What is SASL?
    
SASL stands for Simple Authentication Security Layer and is
    explained in RFC
    2222. That document is very difficult to understand however
    and it should be unnecessary to consult it.
    Background
    How did the world work before SASL?
    
Before SASL, when a new protocol was written which required authentication (users proving who they are to an entity), the protocol had to allow explicitly for each individual authentication mechanism. There had to be a distinct way to say "I want to log in with Kerberos V4". There had to be another distinct way to say "I want to log in with CRAM-MD5". There had to be yet a different way to say "I want to log in anonymously," and so on. This was non-ideal for both the protocol and application writers.
Additionally, many programmers were not very familiar with security, so the protocol did support many mechanisms, or worse, they were supported incorrectly. Moreover, when a new authentication method was invented the protocol needed to be modified to support that mechanism.
This system also was not ideal for application writer. She had
    to have a special case for each mechanism she wished her
    application to support. Also, the mechanisms were difficult to
    implement. Even with a good library, an understanding of how the
    mechanism worked was still necessary. Finally if an application
    used more than one protocol (for example a mail client might use
    IMAP, POP, and SMTP) then "Kerberos V4 for IMAP", "Kerberos V4 for
    POP", "Kerberos V4 for SMTP", "CRAM MD5 for IMAP", "CRAM-MD5 for
    POP", etc... would need to be written. This could quickly create a
    huge number of different mechanism-protocol pairs to implement.
    SASL to the rescue!
    
SASL hopefully solves all these problems. In practice it makes many of them easier to deal with.
Protocol designers simply have to support SASL (in particular RFC 2222). Consequently, any mechanism that supports SASL (just about anything you would want to use does now) is supported by the protocol. If a new authentication mechanism is invented the protocol automatically supports it without any modifications.
Application writers, instead of having to support every mechanism
    for every protocol, only need to support SASL for every
    protocol. Application writers do not need to understand the
    authentication mechanisms at all: the SASL library handles all
    that. Also with the Cyrus SASL library if a new mechanism is
    invented you do not have rewrite your application at all. You may
    not even have to restart your application if it is a long running
    process. This is because the Cyrus SASL library loads each mechanism
    from a shared library. Simply copying a shared library into a
    directory will magically make your application support a new
    mechanism.
    Briefly
    What is the Cyrus SASL library good for?
    
The Cyrus SASL library is good for applications that wish to
    use protocols that support SASL authentication. An non-exhaustive
    list of these are: IMAP, SMTP, ACAP, and LDAP. Also if you are
    making a proprietary system and wish to support authentication it
    is a good way of supporting many different authentication types.
	
    What does the Cyrus SASL library do?
    
From a client point of view, the Cyrus SASL library, given a list of
    mechanisms the server supports it will decide the best mechanism
    to use and tell you what to send to the server at each step of the
    authentication. From a server perspective, it handles
    authentication requests from clients.
    What doesn't the Cyrus SASL library do?
    
   
The Cyrus SASL library is neither network nor protocol aware. It
   is up to the application to send the data over the wire as well as
   to send the data in the protocol specific manner. With IMAP this
   means putting it in the form: + [base64'ed data]\r\n. LDAP
   just sends data in binary via bind requests. The Cyrus SASL library
   has utility base64 encode and decode routines to help with this.
    
Client-only Section
    
    A typical interaction from the client's perspective
    
    
    
	    int result;
	    /* attempt to start sasl 
	     * See the section on Callbacks and Interactions for an 
	     * explanation of the variable callbacks
	     */ 
	    result=sasl_client_init(callbacks);
            
            /* check to see if that worked */
            if (result!=SASL_OK) [failure]
     
     For every network connection make a new SASL connection:
     	     
            		      
            sasl_conn_t *conn; /* The SASL context kept for the life of the connection */
 
            /* client new connection */
            result=sasl_client_new("imap",     /* The service we are using */
			           serverFQDN, /* The fully qualified domain name
                                                  of the server we're connecting to */
			           NULL,
			           0,
			           &conn);     /* allocated on success */
            /* check to see if that worked */
            if (result!=SASL_OK) [failure]
      
       Next get the list of SASL mechanisms the server supports. This
       is usually done throught a capability command. Format the list
       as a single string seperated by spaces.
       
       Feed this string into SASL to begin the authentication process.
       
       
            sasl_interact_t *client_interact=NULL;
            char *out;
            unsigned outlen;
            do {
              result=sasl_client_start(conn,      /* the same context from above */ 
                                       mechlist,  /* the list of mechanisms from the server */
		  		       NULL, 
                                       &client_interact, /* filled in if an interaction is needed */
			  	       &out,      /* filled in on success */
                                       &outlen,   /* filled in on success */
				       &mechusing);
              if (result==SASL_INTERACT)
              {
                 [deal with the interactions. See interactions section below]
              }
           } while (result==SASL_INTERACT); /* the mechanism may ask us to fill in things
                                               many times. result is SASL_CONTINUE on success */
           if (result!=SASL_CONTINUE) [failure]
        
        If this is sucessful send the protocol specific command to
        start the authentication process. This may or may not allow
        for initial data to be sent (see the documentation of the
        protocol to see).
        
        For IMAP this might look like:
          {tag} "AUTHENTICATE" {mechusing}\r\n
          A01 AUTHENTICATE KERBEROS_V4\r\n
           
        SMTP looks like:
         "AUTH" {mechusing}[ {out base64 encoded}]
         AUTH DIGEST-MD5 GHGJJGDDFDKHGHJG=
        
       
	
              do {
                result=sasl_client_step(conn,  /* our context */
				        in,    /* the data from the server */
				        inlen, /* it's length */
				        &client_interact,  /* this should be unallocated and NULL */
				        &out,     /* filled in on success */
				        &outlen); /* filled in on success */
                if (result==SASL_INTERACT)
                {
                   [deal with the interactions. See below]
                }
              } while (result==SASL_INTERACT);
              if (result!=SASL_OK) [failure]
              
          
          Format the output (variable out of lenght outlen) in the
          protocol specific manner and send it across the network to
          the server.
          Before we're done we need to call sasl_client_step() one
          more time to make sure the server isn't trying to fool
          us. Some protocols include data along with the last step. If
          so this data should be used here. If not use a length of
          zero.
	    
                result=sasl_client_step(conn,  /* our context */
				        in,    /* the data from the server */
				        inlen, /* it's length */
				        &client_interact,  /* this should be unallocated and NULL */
				        &out,     /* filled in on success */
				        &outlen); /* filled in on success */
                if (result!=SASL_OK) [failure]
	    
		     
          
Congradulations. You have successfully authenticated to the server.
Don't throw away the SASL connection object (sasl_conn_t* ) yet though. If a security layer was negotiated you will need it to encode and decode the data sent over the network.
	  
               sasl_dispose(&conn);
          
	Done with SASL forever (application quiting for example).
 
          
            sasl_done();         
	  
	    
    
    int sasl_client_init(const sasl_callback_t *callbacks);
    
    
    
    int sasl_client_new(const char *service,
		        const char *serverFQDN,
		        const sasl_callback_t *prompt_supp,
		        int secflags,
		        sasl_conn_t **pconn);
    
    
    
    int sasl_client_start(sasl_conn_t *conn,
		          const char *mechlist,
			  sasl_secret_t *secret,
			  sasl_interact_t **prompt_need,
			  char **clientout,
			  unsigned *clientoutlen,
			  const char **mech);
    
    
    
    int sasl_client_step(sasl_conn_t *conn,
		 const char *serverin,
		 unsigned serverinlen,
		 sasl_interact_t **prompt_need,
		 char **clientout,
		 unsigned *clientoutlen);
    
    
        
    int result;
    /* Initialize SASL */
    result=sasl_server_init(callbacks,      /* Callbacks supported */
                            "TestServer");  /* Name of the application */
    
    This should be called for each new connection. It probably should
    be called right when the socket is accepted. The service name is
    used for PAM authentication if applicable.
    
    sasl_conn_t *conn;
    int result;
    /* Make a new context for this connection */
    result=sasl_server_new("smtp", 
		           NULL, /* my fully qualified domain name; 
			            NULL says use gethostname() */
                           NULL, /* The user realm used for password
			            lookups; NULL means default to serverFQDN
                                    Note: This does not affect Kerberos */
		           NULL, /* Callbacks supported only for this connection */
	                   SASL_SECURITY_LAYER, /* I support encryption layers; 
                                                   otherwise pass 0 */
			   &conn);
    
    When a client requests the list of mechanisms supported by the server. This particular call might produce the string: "{PLAIN, KERBEROS_V4, CRAM-MD5, DIGEST-MD5}"
    
    result=sasl_listmech(conn,  /* The context for this connection */
			 NULL,  /* not supported */
			 "{",   /* What to prepend the string with */
			 ", ",  /* What to seperate mechanisms with */
			 "}",   /* What to append to the string */
			 &result_string, /* The produced string. Allocated by library */
                         &string_length, /* length of the string */
                         &number_of_mechanisms); /* Number of mechanisms in the string */
	
    
    When a client requests to authenticate:
    
    int result;
    const char *errstr;
    char *out;
    unsigned outlen;
    result=sasl_server_start(conn, /* context */
                             mechanism_client_chose,
                             clientin,    /* the optional string the client gave us */
                             clientinlen, /* and it's length */
                             &out, /* allocated by library on success. Might not be NULL 
                                      terminated */
                             &outlen, 
                             &errstr); /* error string filled in on failure */
    if ((result!=SASL_OK) && (result!=SASL_CONTINUE))
    {
      failure. Send client the protocol specific message that says authentication failed
    }
    if (result==SASL_OK)
    {
      client authentication suceeded. Send client the protocol specific message 
      to say that authentication is complete.
    }
    
    When a response is returned by the client. clientin is the
    data from the client decoded from protocol specific format to a
    string of bytes of length clientinlen. This step may occur
    zero or more times. An application should be able to deal with it
    occuring an arbitrary number of times.
    
    int result;
   
    result=sasl_server_step(conn,
                            clientin,      /* what the client gave */
                            clientinlen,   /* it's length */
                            &out,          /* allocated by library on success. 
                                              Might not be NULL terminated */
                            &outlen,
                            &errstr);      /* error string sometimes filled in on failure */
    if ((result!=SASL_OK) && (result!=SASL_CONTINUE))
    {
      failure. Send client the protocol specific message that says authentication failed
    }
    if (result==SASL_OK)
    {
      client authentication suceeded. Send client the protocol specific message 
      to say that authentication is complete.
    }
    send data 'out' with length 'outlen' over the network in protocol
    specific format
    
    
     int sasl_server_start(sasl_conn_t *conn,
			  const char *mech,
			  const char *clientin,
			  unsigned clientinlen,
			  char **serverout,
			  unsigned *serveroutlen,
			  const char **errstr);
    
    
    
    int sasl_server_step(sasl_conn_t *conn,
		         const char *clientin,
		         unsigned clientinlen,
		         char **serverout,
		         unsigned *serveroutlen,
		         const char **errstr);
    
    
    int sasl_listmech(sasl_conn_t *conn,
		      const char *user,
		      const char *prefix,
		      const char *sep,
		      const char *suffix,
		      char **result,
		      unsigned *plen,
		      unsigned *pcount);
    
    
    
    int sasl_checkpass(sasl_conn_t *conn,
                       const char *user,
                       unsigned userlen,
		       const char *pass,
		       unsigned passlen,
		       const char **errstr);
    
    Memory management: Any data passed by the application to the library will be copied by the library. The application is responsible for freeing any memory allocated in the callbacks, if any. Interactions have the same memory management requirements as callbacks.
Apparent random exception: The secret returned from SASL_CB_PASS should be allocated with malloc() and will be freed by the library.
For a detailed description of what each of the callback types are see the sasl.h file. Here are some brief explanations:
    /* callbacks we support. This is a global variable at the 
       top of the program */
    static sasl_callback_t callbacks[] = {
    {
      SASL_CB_GETREALM, NULL, NULL  /* we'll just use an interaction if this comes up */
    }, {
      SASL_CB_USER, NULL, NULL      /* we'll just use an interaction if this comes up */
    }, {
      SASL_CB_AUTHNAME, &getauthname_func, NULL /* A mechanism should call getauthname_func
                                                   if it needs the authentication name */
    }, { 
      SASL_CB_PASS, &getsecret_func, NULL      /* Call getsecret_func if need secret */
    }, {
      SASL_CB_LIST_END, NULL, NULL
    }
    };
    static int getsecret_func(sasl_conn_t *conn,
	  void *context __attribute__((unused)),
	  int id,
	  sasl_secret_t **psecret)
    {
       [ask the user for their secret]
       [allocate psecret and insert the secret]
      return SASL_OK;
    }
    static int getauthname_func(void *context,
                                int id,
                                const char **result,
                                unsigned *len)
    {
       if (id!=SASL_CB_AUTHNAME) return SASL_FAIL;
       [fill in result and len]
       return SASL_OK;
     }
    
    in the main program somewhere
    
    sasl_client_init(callbacks);
    
	
Make sure that you set the IP addresses, the username, the authenticate name, and anything else on the command line (some mechanisms depend on these being present).
Also, sometimes you will receive a get "realm: Information not
available" message, or similar; this is due to the fact that some
mechanisms do not support realms and therefore never set it.
Cyrus imapd v1.6.0 or later
The Cyrus IMAP server now incorporates SASL for all its
authentication needs.  It is a good example of a fairly large server
application.  Also of interest is the prot layer, included in
libcyrus.  This is a stdio-like interface that automatically takes
care of layers using a simple "prot_setsasl()" call.
Cyrus imapd also sets a SASL_CB_PROXY_POLICY callback,
which should be of interest to many applications.
imtest, from cyrus imapd 1.6.0 or later
imtest is an application included with Cyrus imapd.  It is a
very simple IMAP client, but should be of interest to those writing
applications.  It also uses the prot layer, but it is easy to
incorporate similar support without using the prot layer.
Miscelaneous Information
Empty exchanges
Some SASL mechanisms intentionally send no data; an application should
be prepared to either send or receive an empty exchange.  The SASL
profile for the protocol should define how to send an empty string;
make sure to send an empty string when requested, and when receiving
an empty string make sure that the "inlength" passed in is 0.
What's not implemented
Some parts of this API are not implemented by this implementation.  A
brief outline of these features (and what might come of them) is in
this section.
Credentials
None of the modules support passing credentials.  In the future, we
hope to add credential passing to the modules that support it (most
likely the Kerberos modules).  Thus, an application that specifies
SASL_SEC_PASS_CREDENTIALS will not receive any mechanisms.
The functions sasl_cred_install() and
sasl_cred_uninstall() do nothing.
It's likely that the credential API will change, and it's also
likely that you'll need the Cyrus SASL library on both sides of the
connection to make it work.
Secrets
sasl_client_auth() is unimplemented.  It is unclear what this
is intended for.  If we implement it, it will probably be for
generating secrets for fast reauthentication.
The "secret" parameter to sasl_client_start() is
unused.  It is likely that we will use this for fast reauthentication.
Idle
While the implementation & plugins correctly implement the idle calls,
none of them currently do anything.