The GSSAPI mechanism uses a framework similar to SASL for authenticating the user. While GSSAPI can be implemented using many techniques, libgsasl currently links with GSS, Heimdal or MIT Kerberos and is limited to Kerberos 5 only. The GSSAPI client mechanism assumes the user acquired credentials (kerberos tickets) before it is invoked (it will fail if this has not been done). The client need (via callbacks) the name of the service and the name of the user. The server needs the name of the service and a function that authorizes a user. 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_authentication_id) (Gsasl_session_ctx * ctx, char * out, size_t * outlen)
ctx: libgsasl handle.
out: output array with authentication 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 authentiction identity of user and set the output array length, and return GSASL_OK, or fail with an error code. The authentication 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_service) (Gsasl_session_ctx * ctx, char * service, size_t * servicelen, char * hostname, size_t * hostnamelen, char * servicename, size_t * servicenamelen)
ctx: libgsasl handle.
service: output array with name of service.
servicelen: on input the maximum size of the service output array, on output contains the actual size of the service output array.
hostname: output array with hostname of server.
hostnamelen: on input the maximum size of the hostname output array, on output contains the actual size of the hostname output array.
servicename: output array with generic name of server in case of replication (DIGEST-MD5 only).
servicenamelen: on input the maximum size of the servicename output array, on output contains the actual size of the servicename output array.
Type of callback function the application implements. It should retrieve the service (which should be a registered GSSAPI host based service name, such as “imap”) on the server, hostname of server (usually canoncial DNS hostname) and optionally generic service name of server in case of replication (e.g. “mail.example.org” when the hostname is “mx42.example.org”, see the RFC 2831 for more information). It should return GSASL_OK, or an error such as GSASL_AUTHENTICATION_ERROR if it fails.
If SERVICE, HOSTNAME or SERVICENAME is NULL, the function should only populate SERVICELEN, HOSTNAMELEN or SERVICENAMELEN with the output length of the respective field, and return GSASL_OK. This usage may be used by the caller to allocate the proper buffer size. Furthermore, SERVICENAMELEN may also be NULL, indicating that the mechanism is not interested in this field.
int (
*Gsasl_server_callback_service) (Gsasl_session_ctx * ctx, char * service, size_t * servicelen, char * hostname, size_t * hostnamelen)
ctx: libgsasl handle.
service: output array with name of service.
servicelen: on input the maximum size of the service output array, on output contains the actual size of the service output array.
hostname: output array with hostname of server.
hostnamelen: on input the maximum size of the hostname output array, on output contains the actual size of the hostname output array.
Type of callback function the application implements. It should retrieve the service (which should be a registered GSSAPI host based service name, such as “imap”) the server provides and hostname of server (usually canoncial DNS hostname). It should return GSASL_OK, or an error such as GSASL_AUTHENTICATION_ERROR if it fails.
If SERVICE or HOSTNAME is NULL, the function should only populate SERVICELEN or HOSTNAMELEN with the output length of the respective field, and return GSASL_OK. This usage may be used by the caller to allocate the proper buffer size.
int (
*Gsasl_server_callback_gssapi) (Gsasl_session_ctx * ctx, char * clientname, char * authentication_id)
ctx: libgsasl handle.
clientname: input array with GSSAPI client name.
authentication_id: input array with authentication identity.
Type of callback function the application implements. It should return GSASL_OK if and only if the GSSAPI user is authorized to log on as the given authentication_id. GSASL_AUTHENTICATION_ERROR is a good failure if authentication failed, but any available return code may be used. This callback is usually implemented in the application as a call to krb5_kuserok(), such as:
int callback_gssapi (Gsasl_session_ctx *ctx, char *clientname, char *authentication_id) { int rc = GSASL_AUTHENTICATION_ERROR; krb5_principal p; krb5_context kcontext; krb5_init_context (&kcontext); if (krb5_parse_name (kcontext, clientname, &p) != 0) return -1; if (krb5_kuserok (kcontext, p, authentication_id)) rc = GSASL_OK; krb5_free_principal (kcontext, p); return rc; }