cyrus_sasl API使用方法

/**/ /*  This is a proposed C API for support of SASL
 *
 *********************************IMPORTANT*******************************
 * send email to [email protected] and [email protected] *
 * if you need to add new error codes, callback types, property values,  *
 * etc.   It is important to keep the multiple implementations of this   *
 * API from diverging.                                                   *
 *********************************IMPORTANT*******************************
 *
 * Basic Type Summary:
 *  sasl_conn_t       Context for a SASL connection negotiation
 *  sasl_ssf_t        Security layer Strength Factor
 *  sasl_callback_t   A typed client/server callback function and context
 *  sasl_interact_t   A client interaction descriptor
 *  sasl_secret_t     A client password
 *  sasl_rand_t       Random data context structure
 *  sasl_security_properties_t  An application's required security level
 *
 * Callbacks:
 *  sasl_getopt_t     client/server: Get an option value
 *  sasl_logmsg_t     client/server: Log message handler
 *  sasl_getsimple_t  client: Get user/language list
 *  sasl_getsecret_t  client: Get authentication secret
 *  sasl_chalprompt_t client: Display challenge and prompt for response
 *
 * Server only Callbacks:
 *  sasl_authorize_t             user authorization policy callback
 *  sasl_server_userdb_checkpass check password and auxprops in userdb
 *  sasl_server_userdb_setpass   set password in userdb
 *  sasl_server_canon_user       canonicalize username routine
 *
 * Client/Server Function Summary:
 *  sasl_done         Release all SASL global state
 *  sasl_dispose      Connection done: Dispose of sasl_conn_t
 *  sasl_getprop      Get property (e.g., user name, security layer info)
 *  sasl_setprop      Set property (e.g., external ssf)
 *  sasl_errdetail    Generate string from last error on connection
 *  sasl_errstring    Translate sasl error code to a string
 *  sasl_encode       Encode data to send using security layer
 *  sasl_decode       Decode data received using security layer
 *  
 * Utility functions:
 *  sasl_encode64     Encode data to send using MIME base64 encoding
 *  sasl_decode64     Decode data received using MIME base64 encoding
 *  sasl_erasebuffer  Erase a buffer
 *
 * Client Function Summary:
 *  sasl_client_init  Load and initialize client plug-ins (call once)
 *  sasl_client_new   Initialize client connection context: sasl_conn_t
 *  sasl_client_start Select mechanism for connection
 *  sasl_client_step  Perform one authentication step
 *
 * Server Function Summary
 *  sasl_server_init  Load and initialize server plug-ins (call once)
 *  sasl_server_new   Initialize server connection context: sasl_conn_t
 *  sasl_listmech     Create list of available mechanisms
 *  sasl_server_start Begin an authentication exchange
 *  sasl_server_step  Perform one authentication exchange step
 *  sasl_checkpass    Check a plaintext passphrase
 *  sasl_checkapop    Check an APOP challenge/response (uses pseudo "APOP"
 *                    mechanism similar to CRAM-MD5 mechanism; optional)
 *  sasl_user_exists  Check if user exists
 *  sasl_setpass      Change a password or add a user entry
 *  sasl_auxprop_request  Request auxiliary properties
 *  sasl_auxprop_getctx   Get auxiliary property context for connection
 *  sasl_auxprop_store    Store a set of auxiliary properties
 *
 * Basic client model:
 *  1. client calls sasl_client_init() at startup to load plug-ins
 *  2. when connection formed, call sasl_client_new()
 *  3. once list of supported mechanisms received from server, client
 *     calls sasl_client_start().  goto 4a
 *  4. client calls sasl_client_step()
 * [4a. If SASL_INTERACT, fill in prompts and goto 4
 *      -- doesn't happen if callbacks provided]
 *  4b. If SASL error, goto 7 or 3
 *  4c. If SASL_OK, continue or goto 6 if last server response was success
 *  5. send message to server, wait for response
 *  5a. On data or success with server response, goto 4
 *  5b. On failure goto 7 or 3
 *  5c. On success with no server response continue
 *  6. continue with application protocol until connection closes
 *     call sasl_getprop/sasl_encode/sasl_decode() if using security layer
 *  7. call sasl_dispose(), may return to step 2
 *  8. call sasl_done() when program terminates
 *
 * Basic Server model:
 *  1. call sasl_server_init() at startup to load plug-ins
 *  2. On connection, call sasl_server_new()
 *  3. call sasl_listmech() and send list to client]
 *  4. after client AUTH command, call sasl_server_start(), goto 5a
 *  5. call sasl_server_step()
 *  5a. If SASL_CONTINUE, output to client, wait response, repeat 5
 *  5b. If SASL error, then goto 7
 *  5c. If SASL_OK, move on
 *  6. continue with application protocol until connection closes
 *     call sasl_getprop to get username
 *     call sasl_getprop/sasl_encode/sasl_decode() if using security layer
 *  7. call sasl_dispose(), may return to step 2
 *  8. call sasl_done() when program terminates
 *
 *************************************************

从sasl.h中截取的。