The CRAM-MD5 mechanism uses username (authorization identity only) and password to authenticate users. Only a hashed password is transfered, which means that you cannot use normal policy deciding authentication systems such as PAM which do not support extraction of passwords. Two ways of validating the user is provided, either by having the SASL mechanism retrieve the raw password from the application and perform the validation internally, or by calling the application with the CRAM-MD5 challenge and response and let it decide. If both the validating and the retrieving callbacks are specified by the application, the validating one will be used.
While not documented in the original CRAM-MD5 specification, this implementation normalizes the username and the authorization identity using the Unicode 3.2 NFKC form according to the proposed update of CRAM-MD5.
This mechanism is only enabled in the client and server if you implement the respectively callbacks below and set them in the library (Chapter 7).
int (
*Gsasl_client_callback_authorization_id) (Gsasl_session_ctx * ctx, char * out, size_t * outlen)
ctx: libgsasl handle.
out: output array with authorization identity.
outlen: on input the maximum size of the output array, on output contains the actual size of the output array.
Type of callback function the application implements. It should populate the output array with authorization identity of user and set the output array length, and return GSASL_OK, or fail with an error code. The authorization identity must be encoded in UTF-8, but need not be normalized in any way.
If OUT is NULL, the function should only populate the output length field with the length, and return GSASL_OK. This usage may be used by the caller to allocate the proper buffer size.
int (
*Gsasl_client_callback_password) (Gsasl_session_ctx * ctx, char * out, size_t * outlen)
ctx: libgsasl handle.
out: output array with password.
outlen: on input the maximum size of the output array, on output contains the actual size of the output array.
Type of callback function the application implements. It should populate the output array with password of user and set the output array length, and return GSASL_OK, or fail with an error code. The password must be encoded in UTF-8, but need not be normalized in any way.
If OUT is NULL, the function should only populate the output length field with the length, and return GSASL_OK. This usage may be used by the caller to allocate the proper buffer size.
int (
*Gsasl_server_callback_retrieve) (Gsasl_session_ctx * ctx, char * authentication_id, char * authorization_id, char * realm, char * key, size_t * keylen)
ctx: libgsasl handle.
authentication_id: input array with authentication identity.
authorization_id: input array with authorization identity, or NULL.
realm: input array with realm of user, or NULL.
key: output array with key for authentication identity.
keylen: on input the maximum size of the key output array, on output contains the actual size of the key output array.
Type of callback function the application implements. It should retrieve the password for the indicated user and return GSASL_OK, or an error code such as GSASL_AUTHENTICATION_ERROR. The key must be encoded in UTF-8, but need not be normalized in any way.
If KEY is NULL, the function should only populate the KEYLEN output length field with the length, and return GSASL_OK. This usage may be used by the caller to allocate the proper buffer size.
int (
*Gsasl_server_callback_cram_md5) (Gsasl_session_ctx * ctx, char * username, char * challenge, char * response)
ctx: libgsasl handle.
username: input array with username.
challenge: input array with CRAM-MD5 challenge.
response: input array with CRAM-MD5 response.
Type of callback function the application implements. It should return GSASL_OK if and only if the validation of the provided credential was succesful. GSASL_AUTHENTICATION_ERROR is a good failure if authentication failed, but any available return code may be used.