---

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:

• GSASL_AUTHID

  The authentication identity.

• GSASL_AUTHZID

  The authorization identity.

• GSASL_PASSWORD

  The password of the authentication identity.

• GSASL_ANONYMOUS_TOKEN

  The anonymous token. This is typically the email address of the user.

• GSASL_SERVICE

  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.

• GSASL_HOSTNAME

  Should be the local host name of the machine.

• GSASL_GSSAPI_DISPLAY_NAME

  Contain the GSSAPI “display name”, set by the server GSSAPI mechanism. Typically you retrieve this property in your callback, when invoked for GSASL_VALIDATE_GSSAPI.

• GSASL_REALM

  The name of the authentication domain. This is used by several mechanisms, including DIGEST-MD5, GSS-API, and NTLM.

• GSASL_PASSCODE

  The SecurID passcode.

• GSASL_PIN

  The SecurID personal identification number (PIN).

• GSASL_SUGGESTED_PIN

  A SecurID personal identification number (PIN) suggested by the server.

• GSASL_DIGEST_MD5_HASHED_PASSWORD

  For the DIGEST-MD5 mechanism, this is a hashed password. It is used in servers to avoid storing clear-text credentials.

• GSASL_QOPS

  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, for example qop-auth, qop-int. Valid keywords are qop-auth, qop-int, and qop-conf.

• GSASL_QOP

  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 keywords for GSASL_QOPS. The client must chose one of the QOP values offered by the server (which may be inspected through the GSASL_QOPS property).

• GSASL_SCRAM_SALTED_PASSWORD

  In a client, the SCRAM mechanism (see The SCRAM mechanisms) will request this property from the application. The value should be hex-encoded string (40 characters for SCRAM-SHA-1 and 64 characters for SCRAM-SHA-256) with the user’s PBKDF2-prepared password. Note that the value is different for the same password for each value of the GSASL_SCRAM_ITER and GSASL_SCRAM_SALT properties. The property can be used to avoid storing a clear-text credential in the client, however note that an attacker who steal it may impersonate both a SCRAM client and SCRAM server. If the property is not available, the mechanism will ask for the GSASL_PASSWORD property instead.

  The GSASL_SCRAM_SALTED_PASSWORD property is set by the SCRAM mechanism if it derived the value from a GSASL_PASSWORD value supplied during authentication. Thus, the application may cache this value for future authentication attempts.

• GSASL_SCRAM_ITER
• GSASL_SCRAM_SALT

  In the server, the application can set these properties to influence the hash iteration count and hash salt to use when deriving the password in the SCRAM mechanism (see The SCRAM mechanisms). The default hash iteration count is 4096 and often you should use a higher value. The salt should be a base64-encoded string with random data, typical length 4 to 16 bytes.

  In the client, the SCRAM mechanism set these properties (using values received from the server) before asking the application to provide a GSASL_SCRAM_SALTED_PASSWORD value.

  After the final authentication step, the properties are set by the mechanism, to allow the application to retrieve the values used (required when storing the GSASL_SCRAM_SALTED_PASSWORD value, for example).

• GSASL_SCRAM_SERVERKEY
• GSASL_SCRAM_STOREDKEY

  These properties are requested by the SCRAM server mechanism (see The SCRAM mechanisms), and if they are not available it will ask for GSASL_PASSWORD or GSASL_SCRAM_SALTED_PASSWORD to complete authentication. The values are base64-encoded strings; 28 characters for SCRAM-SHA-1 and 44 characters for SCRAM-SHA-256. The properties are set after completing the final authentication step; so if GSASL_PASSWORD or GSASL_SCRAM_SALTED_PASSWORD was used for authentication, the application may extract GSASL_SCRAM_SERVERKEY and GSASL_SCRAM_STOREDKEY to use these values in a future authentication instead of the password. The values can be calculated using gsasl_scram_secrets_from_password, gsasl_scram_secrets_from_salted_password (see Utilities) or using the --mkpasswd parameter for the gsasl utility (see Invoking gsasl).

• GSASL_CB_TLS_UNIQUE

  This property holds base64 encoded tls-unique channel binding data. As a hint, if you use GnuTLS, the API gnutls_session_channel_binding can be used to extract channel bindings for a session. To be secure, a TLS channel MUST have the session hash extension (RFC 7627) negotiated, or session resumption MUST NOT have been used. The library cannot enforce this, so it is up to the application to only provide the GSASL_CB_TLS_UNIQUE property when the condition holds. Note that TLS version 1.3 and later do not support this channel binding.

• GSASL_CB_TLS_EXPORTER

  This property holds base64 encoded tls-exporter channel binding data. As a hint, if you use GnuTLS, the API gnutls_session_channel_binding can be used to extract channel bindings for a session. This fixes some of the security problems with the tls-unique channel binding and supports modern TLS versions.

• GSASL_SAML20_IDP_IDENTIFIER

  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 the GSASL_SAML20_REDIRECT_URL callback.

• GSASL_SAML20_REDIRECT_URL This property holds the SAML redirect URL that the server wants the client to access. It will be available in the GSASL_SAML20_AUTHENTICATE_IN_BROWSER callback for the client.
• GSASL_OPENID20_REDIRECT_URL This property holds the SAML redirect URL that the server wants the client to access. It will be available in the GSASL_OPENID20_AUTHENTICATE_IN_BROWSER callback for the client.
• GSASL_OPENID20_OUTCOME_DATA OpenID 2.0 authentication outcome data. This is either the OpenID SREG values or a value list starting with "openid.error=" to signal error.

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

• GSASL_VALIDATE_SIMPLE

  Used by multiple mechanisms in server mode. The callback may retrieve the GSASL_AUTHID, GSASL_AUTHZID and GSASL_PASSWORD property values and use them to make an authentication and authorization decision.

• GSASL_VALIDATE_EXTERNAL

  Used by EXTERNAL mechanism on the server side to validate the client. The GSASL_AUTHID will contain the authorization identity of the client.

• GSASL_VALIDATE_ANONYMOUS

  Used by ANONYMOUS mechanism on the server side to validate the client. The GSASL_ANONYMOUS_TOKEN will contain token that identity the client.

• GSASL_VALIDATE_GSSAPI

  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.

• GSASL_VALIDATE_SECURID

  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.

• GSASL_VALIDATE_SAML20

  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_VALIDATE_OPENID20

  Used by the OPENID20 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_BROWSER Used by the SAML20 mechanism in the client side to request that the client should launch the SAML redirect URL (the GSASL_SAML20_REDIRECT_URL property) in a browser to continue with authentication.
• GSASL_OPENID20_AUTHENTICATE_IN_BROWSER Used by the OPENID20 mechanism in the client side to request that the client should launch the OpenID redirect URL (the GSASL_OPENID20_REDIRECT_URL property) in a browser to continue with authentication.