SASL Programmer's Guide

NOTE: This is a work in progress. Any contributions would be very appreciated

Contents

• Introduction
  • About this guide
  • What is SASL?
• Background
  • How did the world work before SASL?
  • SASL to the rescue!
• Briefly
  • What is the Cyrus SASL library good for?
  • What does the Cyrus SASL library do?
  • What doesn't the Cyrus SASL library do?
• Client-only Section
  • A typical interaction from the client's perspective
  • How does this look in code?
  • sasl_client_init
  • sasl_client_new
  • sasl_client_start
  • sasl_client_step
• Server-only Section
  • A typical interaction from the server's perspective
  • How does this look in code?
  • sasl_server_init
  • sasl_server_new
  • sasl_server_start
  • sasl_server_step
  • sasl_listmech
  • sasl_checkpass
• Common Section
  • Callbacks and Interaction
  • sasl_encode
  • sasl_decode
• Example applications that come with the Cyrus SASL library
  • sample-client and sample-server
  • Cyrus imapd v1.6.0 or later
  • imtest, from cyrus imapd 1.6.0 or later
• Miscelaneous Information
  • Empty exchanges
• What's not implemented
  • Credentials
  • Secrets
  • Idle

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

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

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

1. A client makes a few calls (explained later) to initialize SASL.
2. Every time the client application makes a new connection it should make a new context that is kept for the life of the connection.
3. Ask the server for the list of supported mechanisms
4. Feed this list to the library
5. Start the authentication with the mechanism the library chose
6. The server will return some bytes
7. Give these to the library
8. The library returns some bytes to the application
9. Application sends these bytes over the network
10. repeat the last 4 steps until the server tells you that the authentication is completed

    
	    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]
     

	     
            		      
            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]

      

       
            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]

        

        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=
        

1. Authentication failure. Authentication process is halted. This might look like A01 NO Authentication failure in IMAP or 501 Failed in SMTP. Either retry the authentication or abort.
2. Authentication success. We're now sucessfully authenticated. This might look like A01 OK Authenticated successful in IMAP or 235 Authentication successful in SMPT. Go here
3. Another step in the authentication process is necessary. This might look like + HGHDS1HAFJ= in IMAP or 334 PENCeUxFREJoU0NnbmhNWitOMjNGNndAZWx3b29kLmlubm9zb2Z0LmNvbT4= in SMTP. Note it could be an empty string such as + \r\n in IMAP.

              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]
              
          

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);

          

            sasl_done();         
	  

sasl_client_init

    int sasl_client_init(const sasl_callback_t *callbacks);
    

Paramaters:
• callbacks - List of callbacks. See Callbacks section

sasl_client_new

    int sasl_client_new(const char *service,
		        const char *serverFQDN,
		        const sasl_callback_t *prompt_supp,
		        int secflags,
		        sasl_conn_t **pconn);
    

Paramaters:
• service - the service name being used. This usually is the protocol name (e.g. "ldap")
• serverFQDN - Fully qualified domain name of server
• prompt_supp - List off callbacks specific to this connection
• secflags - security flags ORed together requested (e.g. SASL_SEC_NOPLAINTEXT)
• pconn - the SASL connection object allocated upon success

sasl_client_start

    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);
    

Paramaters:
• conn - the SASL connection object gotten from sasl_client_new()
• mechlist - the list of mechanisms to try seperated by spaces
• secret - secret (optional)
• prompt_need - filled in when a SASL_INTERACT is returned
• clientout - filled in upon sucess with data to send to server
• clientoutlen - length of that data
• mech - filled in with mechanism being used

sasl_client_step

    int sasl_client_step(sasl_conn_t *conn,
		 const char *serverin,
		 unsigned serverinlen,
		 sasl_interact_t **prompt_need,
		 char **clientout,
		 unsigned *clientoutlen);
    

Paramaters:
• conn - the SASL connection object gotten from sasl_client_new()
• serverin - data from the server
• serverinlen - length of data from the server
• prompt_need - filled in with a SASL_INTERACT is returned
• clientout - filled in upon sucess with data to send to server
• clientoutlen - length of that data

    
    int result;

    /* Initialize SASL */
    result=sasl_server_init(callbacks,      /* Callbacks supported */
                            "TestServer");  /* Name of the application */


    

    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);

    

    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 */
	
    

    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.
    }


    

    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

    

Parameters:
• callbacks - A list of callbacks supported by the application (see Interaction and Callbacks section)
• appname - A string of the name of the application. This string is what is used when loading configuration options.

Parameters:
• service - The name of the service you are supporting. This might be "acap" or "smtp". This is used by Kerberos mechanisms and possibly other mechanisms. It is also used for PAM authentication.
• serverFQDN - This is the fully qualified domain name of the server (i.e. your hostname); if NULL, the library calls gethostbyname().
• user_realm - The realm the connected client is in. The Kerberos mechanisms ignore this parameter and default to the local Kerberos realm. A value of NULL makes the library default, usually to the serverFQDN; a value of "" specifies that the client should specify the realm; this also changes the semantics of "@" in a username for mechanisms that don't support realms.
• callbacks - Additional callbacks that you wish only to apply to this connection.
• secflags - security flags. SASL_SECURITY_LAYER if your application supports security layers. 0 otherwise.
• pconn - Context. Filled in on success.

     int sasl_server_start(sasl_conn_t *conn,
			  const char *mech,
			  const char *clientin,
			  unsigned clientinlen,
			  char **serverout,
			  unsigned *serveroutlen,
			  const char **errstr);
    

Paramaters:
• conn - The context for the connection
• mech - The authentication mechanism the client wishes to try (e.g. KERBEROS_V4)
• clientin - Initial client challenge bytes. Note: some protocols do not allow this. If this is the case passing NULL is valid
• clientinlen - The length of the challenge. 0 is there is none.
• serverout - allocated and filled in by the function. These are the bytes that should be encoded as per the protocol and sent over the network back to the client.
• serveroutlen - length of bytes to send to client
• errstr - string possibly filled in on error

    int sasl_server_step(sasl_conn_t *conn,
		         const char *clientin,
		         unsigned clientinlen,
		         char **serverout,
		         unsigned *serveroutlen,
		         const char **errstr);
    

Paramaters:
• conn - The context for the connection
• clientin - Data sent by the client.
• clientinlen - The length of the client data. Note that this may be 0
• serverout - allocated and filled in by the function. These are the bytes that should be encoded as per the protocol and sent over the network back to the client.
• serveroutlen - length of bytes to send to client. Note that this may be 0
• errstr - string possibly filled in on error

    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);
    

Paramaters:
• conn - The context for this connection
• user - Currently not implemented
• prefix - The string to prepend
• sep - The string to seperate mechanisms with
• suffix - The string to end with
• result - Resultant string
• plen - Number of characters in the result string
• pcount - Number of mechanisms listed in the result string

    int sasl_checkpass(sasl_conn_t *conn,
                       const char *user,
                       unsigned userlen,
		       const char *pass,
		       unsigned passlen,
		       const char **errstr);
    

Parameters:
• conn - The context for this connection
• user - The user trying to check the password for
• userlen - The user length
• pass - The password
• passlen - The password length
• errstr - Possibly filled in on failure

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:

• SASL_CB_AUTHNAME - the name of the user authenticating
• SASL_CB_USER - the name of the user acting for. (for example postman delivering mail for tmartin might have an AUTHNAME of postman and a USER of tmartin)
• SASL_CB_PASS - password for AUTHNAME
• SASL_CB_GETREALM - Realm of the server

    /* 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

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

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

The "secret" parameter to sasl_client_start() is unused. It is likely that we will use this for fast reauthentication.

Idle