Chapter 11. Error Handling

Most functions in `Libgsasl' are returning an error if they fail. For this reason, the application should always catch the error condition and take appropriate measures, for example by releasing the resources and passing the error up to the caller, or by displaying a descriptive message to the user and cancelling the operation.

Some error values do not indicate a system error or an error in the operation, but the result of an operation that failed properly.

11.1. Error values

Errors are returned as an int. Except for the OK case an application should always use the constants instead of their numeric value. Applications are encouraged to use the constants even for OK as it improves readability. Possible values are:

GSASL_OK

This value indicates success. The value of this error is guaranteed to always be 0 so you may use it in boolean constructs.

GSASL_NEEDS_MORE

SASL mechanisms needs more data

GSASL_UNKNOWN_MECHANISM

Unknown SASL mechanism

GSASL_MECHANISM_CALLED_TOO_MANY_TIMES

SASL mechanism called too many times

GSASL_TOO_SMALL_BUFFER

SASL function need larger buffer (internal error)

GSASL_FOPEN_ERROR

Could not open file in SASL library

GSASL_FCLOSE_ERROR

Could not close file in SASL library

GSASL_MALLOC_ERROR

Memory allocation error in SASL library

GSASL_BASE64_ERROR

Base 64 coding error in SASL library

GSASL_GCRYPT_ERROR

Gcrypt error in SASL library

GSASL_GSSAPI_RELEASE_BUFFER_ERROR

GSSAPI library could not deallocate memory in gss_release_buffer() in SASL library. This is a serious internal error.

GSASL_GSSAPI_IMPORT_NAME_ERROR

GSSAPI library could not understand a peer name in gss_import_name() in SASL library. This may be due to incorrect user supplied data.

GSASL_GSSAPI_INIT_SEC_CONTEXT_ERROR

GSSAPI error in client while negotiating security context in gss_init_sec_context() in SASL library. This is most likely due insufficient credentials or malicious interactions.

GSASL_GSSAPI_ACCEPT_SEC_CONTEXT_ERROR

GSSAPI error in server while negotiating security context in gss_init_sec_context() in SASL library. This is most likely due insufficient credentials or malicious interactions.

GSASL_GSSAPI_UNWRAP_ERROR

GSSAPI error while decrypting or decoding data in gss_unwrap() in SASL library. This is most likely due to data corruption.

GSASL_GSSAPI_WRAP_ERROR

GSSAPI error while encrypting or encoding data in gss_wrap() in SASL library.

GSASL_GSSAPI_ACQUIRE_CRED_ERROR

GSSAPI error acquiring credentials in gss_acquire_cred() in SASL library. This is most likely due to not having the proper Kerberos key available in /etc/krb5.keytab on the server.

GSASL_GSSAPI_DISPLAY_NAME_ERROR

GSSAPI error creating a display name denoting the client in gss_display_name() in SASL library. This is probably because the client suplied bad data.

GSASL_GSSAPI_UNSUPPORTED_PROTECTION_ERROR

Other entity requested integrity or confidentiality protection in GSSAPI mechanism but this is currently not implemented.

GSASL_NEED_CLIENT_ANONYMOUS_CALLBACK

SASL mechanism needs gsasl_client_callback_anonymous() callback (application error)

GSASL_NEED_CLIENT_PASSWORD_CALLBACK

SASL mechanism needs gsasl_client_callback_password() callback (application error)

GSASL_NEED_CLIENT_PASSCODE_CALLBACK

SASL mechanism needs gsasl_client_callback_passcode() callback (application error)

GSASL_NEED_CLIENT_PIN_CALLBACK

SASL mechanism needs gsasl_client_callback_pin() callback (application error)

GSASL_NEED_CLIENT_AUTHORIZATION_ID_CALLBACK

SASL mechanism needs gsasl_client_callback_authorization_id() callback (application error)

GSASL_NEED_CLIENT_AUTHENTICATION_ID_CALLBACK

SASL mechanism needs gsasl_client_callback_authentication_id() callback (application error)

GSASL_NEED_CLIENT_SERVICE_CALLBACK

SASL mechanism needs gsasl_client_callback_service() callback (application error)

GSASL_NEED_SERVER_VALIDATE_CALLBACK

SASL mechanism needs gsasl_server_callback_validate() callback (application error)

GSASL_NEED_SERVER_CRAM_MD5_CALLBACK

SASL mechanism needs gsasl_server_callback_cram_md5() callback (application error)

GSASL_NEED_SERVER_DIGEST_MD5_CALLBACK

SASL mechanism needs gsasl_server_callback_digest_md5() callback (application error)

GSASL_NEED_SERVER_ANONYMOUS_CALLBACK

SASL mechanism needs gsasl_server_callback_anonymous() callback (application error)

GSASL_NEED_SERVER_EXTERNAL_CALLBACK

SASL mechanism needs gsasl_server_callback_external() callback (application error)

GSASL_NEED_SERVER_REALM_CALLBACK

SASL mechanism needs gsasl_server_callback_realm() callback (application error)

GSASL_NEED_SERVER_SECURID_CALLBACK

SASL mechanism needs gsasl_server_callback_securid() callback (application error)

GSASL_NEED_SERVER_SERVICE_CALLBACK

SASL mechanism needs gsasl_server_callback_service() callback (application error)

GSASL_NEED_SERVER_GSSAPI_CALLBACK

SASL mechanism needs gsasl_server_callback_gssapi() callback (application error)

GSASL_NEED_SERVER_RETRIEVE_CALLBACK

SASL mechanism needs gsasl_server_callback_retrieve() callback (application error)

GSASL_MECHANISM_PARSE_ERROR

SASL mechanism could not parse input

GSASL_AUTHENTICATION_ERROR

Error authentication user

GSASL_CANNOT_GET_CTX

Cannot get internal library handle (library error)

GSASL_INTEGRITY_ERROR

Integrity error in application payload

GSASL_NO_MORE_REALMS

No more realms available (non-fatal)

GSASL_NO_CLIENT_CODE

Client-side functionality not available in library (application error)

GSASL_NO_SERVER_CODE

Server-side functionality not available in library (application error)

GSASL_INVALID_HANDLE

The provided library handle was invalid (application error)