Basic processing

Edit online

The following section describes the typical flow when a SASL plug-in is used to provide an extended authentication function.

This flow assumes that the SASL plug-in shared library is already loaded by the LDAP library:
  1. Application calls ldap_sasl_bind_s(), with a mechanism supported by a configured SASL plug-in.
  2. The LDAP library calls the SASL bind worker function, as provided by the appropriate plug-in. The parameters that are supplied on the original ldap_sasl_bind_s() API are passed to the plug-in as elements of a pblock structure.
  3. The plug-in worker function receives control, and extracts the parameters from the pblock by using the ldap_plugin_pblock_get() API. The following SASL-related information can be obtained from the pblock by the plug-in:
    • Distinguished Name (dn)
    • Credentials
    • Server controls
    • Client controls
    • Mechanism (plug-in subtype)
    In addition to these parameters, the plug-in can also obtain other information by using the ldap_plugin_pblock_get(), including:
    • Plug-in configuration information (that is, configuration information that is supplied in ARGC and ARGV form)
    • Target LDAP server host name
  4. The plug-in runs its mechanism-specific logic. Some of the sample mechanisms that can be implemented as SASL plug-ins are as follows. They can be made available to all LDAP applications that are running on the system:
    Authentication that is based on a user fingerprint (for example, mechanism=userfp)
    When the fingerprint plug-in gets control, it uses the DN supplied on the ldap_sasl_bind_s() API to obtain an image of the user fingerprint. This authentication can entail prompting the user to use a fingerprint-scanning device. In this example, the fingerprint image, however obtained, represents the user credentials.
    When the credentials are obtained, the plug-in is ready to run the actual SASL bind. This authentication is done by calling the ldap_plugin_sasl_bind_s() API, supplying the appropriate parameters (DN, credentials, mechanism, server controls). This API is a synchronous API that sends the SASL bind request to the LDAP server. Two items are returned to the plug-in when the bind result is returned from the server, and control is returned to the plug-in:
    • Bind result error code
    • Server credentials

    If the server credentials are to be returned to the application, they must be set in the pblock before it returns control to the LDAP library, and after to the application. This setting is done by using ldap_plugin_pblock_set(). In this example, the plug-in work is complete, and it returns, supplying the bind result error code as the return code.

    Authentication by using credentials that are previously established by the operating system
    When the plug-in gets control, it queries the local security context to obtain the user identity and security token. For this example, we assume the user identity, as associated with the local security context, is used to construct the DN. The information from the security token is used for credentials.

    After the credentials are obtained, the plug-in calls ldap_plugin_sasl_bind_s(), supplying the appropriate parameters (DN, credentials, mechanism, server controls). As in the previous example, the plug-in waits for the results of the bind request, then returns to the LDAP library, again setting server credentials in the pblock, if appropriate. Control is then returned to the application, along with the optional server credentials.

    Authentication by using multiple binds (mechanism=DIGEST-MD5)
    Some SASL mechanisms require multiple transactions between the client and the server (for example, the SASL DIGEST-MD5 mechanism). For this type of mechanism, when the plug-in gains control, it actually calls the ldap_plugin_sasl_bind_s() API multiple times. On each bind operation, the plug-in can supply DN, credentials, mechanism, and server controls, which are passed to the server. The LDAP server can return a result and server credentials back to the client. The plug-in can use this information to formulate another bind, again sent to the server by using ldap_plugin_sasl_bind_s(). When the multi-bind flow is complete, the plug-in returns control to the LDAP library with the result and optional server credentials.