Next: , Previous: Using the Library, Up: Top

4 Properties

The library uses a concept called “properties” to request and pass data between the application and the individual authentication mechanisms. The application can set property values using the gsasl_property_set function. If a mechanism needs a property value the application has not yet provided, this is handled through a callback. The application provides a callback, using gsasl_callback_set, which will be invoked with a property parameter. The callback should set the property before returning, or fail. See Callback Functions, for more information.

There are two kind of properties. The first, a “data property” is the simplest to understand because it normally refers to short strings. For example, the property called GSASL_AUTHID correspond to the username string, e.g., simon.

The latter properties, called “logical properties”, are used by the server to make a authentication decision, and is used as a way to get the application callback invoked. For example, the property GSASL_VALIDATE_SIMPLE is used by the server-side part of mechanisms like PLAIN. The purpose is to ask the server application to decide whether the user should be authenticated successfully or not. The callback typically look at other property fields, such as GSASL_AUTHID and GSASL_PASSWORD, and compare those values with external information (for example data stored in a database or on a LDAP server) and then return OK or not.

Warning: Don't expect that all mechanisms invoke one of the logical properties in the server mode. For example, the CRAM-MD5 and SCRAM-SHA-1 mechanisms will use the data properties (i.e., username and password) provided by the application to internally decide whether to successfully authenticate the user. User authorization decisions needs to be made by the application outside of the SASL mechanism negotiation.

The logical properties are currently only used by servers, but data properties are used by both client and servers. It makes sense to think about the latter category as ‘server properties’ but the reverse is not valid nor useful.

The semantics associated with a data property is different when it is used in client context and in the server context. For example, in the client context, the application is expected to set the property GSASL_AUTHID to signal to the mechanism the username to use, but in the server context, the GSASL_AUTHID property is set by the mechanism and can be used by the application (in the callback) to find out what username the client provided.

Below is a list of all properties and an explanation for each. First is the list of data properties:

Next follows a list of data properties used to trigger the callback, typically used in servers to validate client credentials: