Server Plug-ins

Server plug-ins are used to manage the server-side of a SASL negotiation. Server plug-ins are usually packaged with the corresponding client plug-ins. A server plug-in contains one or more server-side SASL mechanisms. Each SASL server mechanism supports authentication, and optionally integrity and confidentiality. Each mechanism provides information about that mechanism's capabilities:

• Maximum SSF

• Maximum security flags

• Plug-in features

• Callbacks and prompt IDs for using the plug-in

Server plug-ins must export sasl_server_plug_init(). libsasl calls sasl_server_plug_init() to initialize the plug-in for the server. The plug-in returns a sasl_server_plug_t structure. The sasl_server_plug_t provides the following entry points for libsasl to call the mechanism:

• mech_new() – The server starts a connection by calling sasl_server_start(), which uses mech_new(). mech_new() performs initialization that is specific to the mechanism. If necessary, mech_new() allocates a connection context.

• mech_step() – mech_step() can be called by sasl_server_start() and sasl_server_step(). mech_step() performs authentication on the server-side after mech_new() has been called. mech_step() returns SASL_OK if authentication is successful. SASL_CONTINUE is returned if more data is required. A SASL error code is returned if authentication fails. If an error occurs, then seterror() is called. If the authentication is successful, mech_step() must return the sasl_out_params_t structure with the relevant security layer information and callbacks. The canon_user() function is part of this structure. canon_user() must be called when the server receives the authentication and authorization IDs. Calling the canon_user() function causes propctx to be filled in. Any required auxiliary property requests should be performed before the authentication is canonicalized. Authorization ID lookups are performed after the authentication is canonicalized.

  The mech_step() function must fill any related sasl_out_params_t fields before SASL_OK is returned. These fields perform the following functions:

  • doneflag – Indicates a complete exchange

  • maxoutbuf – Indicates maximum output size for a security layer

  • mech_ssf – Supplied SSF for the security layer

  • encode() – Called by sasl_encode(), sasl_encodev(), and sasl_decode()

  • decode() – Called by sasl_encode(), sasl_encodev(), and sasl_decode()

  • encode_context() – Called by sasl_encode(), sasl_encodev(), and sasl_decode()

  • decode_context() – Called by sasl_encode(), sasl_encodev(), and sasl_decode()

• mech_dispose() – mech_dispose() is called when the context can be safely closed. mech_dispose() is called by sasl_dispose().

• mech_free() – mech_free() is called when libsasl shuts down. Any remaining global state for the plug-in is freed by mech_free().

• setpass() sets a user's password. setpass() enables a mechanism to have an internal password.

• mech_avail() is called by sasl_listmech() to check if a mechanism is available for a given user. mech_avail() can create a new context and thus avoid a call to mech_new(). Use this method to create a context as long as performance is not affected.