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. For more information, see See Callback Functions.
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
correspond to the username string, e.g.,
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
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
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:
The authentication identity.
The authorization identity.
The password of the authentication identity.
The anonymous token. This is typically the email address of the user.
The registered GSSAPI service name of the application service, e.g. “imap”. While the names are registered for GSSAPI, other mechanisms such as DIGEST-MD5 may also use this.
Should be the local host name of the machine.
Contain the GSSAPI “display name”, set by the server GSSAPI
mechanism. Typically you retrieve this property in your callback,
when invoked for
The name of the authentication domain. This is used by several mechanisms, including DIGEST-MD5, GSS-API, KERBEROS_V5 and NTLM.
The SecurID passcode.
The SecurID personal identification number (PIN).
A SecurID personal identification number (PIN) suggested by the server.
For the DIGEST-MD5 mechanism, this is a hashed password. It is used in servers to avoid storing clear-text credentials.
The DIGEST-MD5 server query for this property to get the set of
quality of protection (QOP) values to advertise. The property holds
strings with comma separated keywords denoting the set of qops to use,
qop-auth, qop-int. Valid keywords are
The DIGEST-MD5 client query for this property to get the quality of
protection (QOP) values to request. The property value is one of the
GSASL_QOPS. The client must chose one of the QOP
values offered by the server (which may be inspected through the
The SCRAM-SHA-1 client requests this property from the application,
and the value should be 40 character long hex-encoded string with the
user's hashed password. Note that the value is different for the same
password for each value of the
GSASL_SCRAM_ITER properties. The property can be used to avoid
storing a clear-text credential in the client. If the property is not
available, the client will ask for the
In the server, the application can set these properties to influence
the hash iteration count and hash salt to use when deriving the
password. The default hash iteration count is 4096 and normally you
should not need to use a lower setting. The salt should be a random
string. In the client, the SCRAM-SHA-1 mechanism set these properties
before asking for asking the application to provide a
This property holds the SAML identifier of the user. The SAML20
mechanism in client mode will send it to the other end for
identification purposes, and in server mode it will be accessible in
GSASL_SAML20_REDIRECT_URLThis property holds the SAML redirect URL that the server wants the client to access. It will be available in the
GSASL_SAML20_AUTHENTICATE_IN_BROWSERcallback for the client.
Next follows a list of data properties used to trigger the callback, typically used in servers to validate client credentials:
Used by multiple mechanisms in server mode. The callback may retrieve
GSASL_PASSWORD property values and use them to make an
authentication and authorization decision.
Used by EXTERNAL mechanism on the server side to validate the client. The GSASL_AUTHID will contain the authorization identity of the client.
Used by ANONYMOUS mechanism on the server side to validate the client. The GSASL_ANONYMOUS_TOKEN will contain token that identity the client.
Used by the GSSAPI and GS2-KRB5 mechanisms on the server side, to validate the client. You may retrieve the authorization identity from GSASL_AUTHZID and the GSS-API display name from GSASL_GSSAPI_DISPLAY_NAME.
Used by SECURID mechanism on the server side to validate client. The GSASL_AUTHID, GSASL_AUTHZID, GSASL_PASSCODE, and GSASL_PIN will be set. It can return GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE to ask the client to supply another passcode, and GSASL_SECURID_SERVER_NEED_NEW_PIN to require the client to supply a new PIN code.
Used by the SAML20 mechanism on the server side to request that the
application perform authentication. The callback should return
GSASL_OK if the user should be permitted access, and
GSASL_AUTHENTICATION_ERROR (or another error code) otherwise.
GSASL_SAML20_AUTHENTICATE_IN_BROWSERUsed by the SAML20 mechanism in the client side to request that the client should launch the SAML redirect URL (the
GSASL_SAML20_REDIRECT_URLproperty) in a browser to continue with authentication.