Previous: Utility Functions, Up: Using libfko


3.7 Error Handling

Most fko functions return an integer value that corresponds to either success (0), or one of the non-zero values thar corresponds to a number of possible errors. libfko provides a function to get a descriptive string for the given error code.

— Function: const char * fko_errstr (int err_code)

The function fko_errstr returns a pointer to a statically allocated string containing the descripton of the error.

The list of the possible error codes and their corresponding descriptions as returned by fko_errstr follows:

— Variable: int error_code
FKO_SUCCESS
Success
FKO_ERROR_CTX_NOT_INITIALIZED
FKO Context is not initialized
FKO_ERROR_MEMORY_ALLOCATION
Unable to allocate memory
FKO_ERROR_FILESYSTEM_OPERATION
Read/write bytes mismiatch
FKO_ERROR_INVALID_DATA
Args contain invalid data
FKO_ERROR_DATA_TOO_LARGE
Value or Size of the data exceeded the max allowed
FKO_ERROR_INVALID_KEY_LEN
Invalid key length
FKO_ERROR_USERNAME_UNKNOWN
Unable to determine username
FKO_ERROR_INCOMPLETE_SPA_DATA
Missing or incomplete SPA data
FKO_ERROR_MISSING_ENCODED_DATA
There is no encoded data to process
FKO_ERROR_INVALID_DIGEST_TYPE
Invalid digest type
FKO_ERROR_INVALID_ALLOW_IP
Invalid allow IP address in the SPA message data
FKO_ERROR_INVALID_SPA_COMMAND_MSG
Invalid SPA command message format
FKO_ERROR_INVALID_SPA_ACCESS_MSG
Invalid SPA access message format
FKO_ERROR_INVALID_SPA_NAT_ACCESS_MSG
Invalid SPA nat_access message format
FKO_ERROR_INVALID_ENCRYPTION_TYPE
Invalid encryption type
FKO_ERROR_WRONG_ENCRYPTION_TYPE
Wrong or inappropriate encryption type for this operation
FKO_ERROR_DECRYPTION_SIZE
Unexpected or invalid size for decrypted data
FKO_ERROR_DECRYPTION_FAILURE
Decryption failed or decrypted data is invalid
FKO_ERROR_DIGEST_VERIFICATION_FAILED
The computed digest did not match the digest in the spa data
FKO_ERROR_INVALID_HMAC_KEY_LEN
Invalid HMAC key length
FKO_ERROR_UNSUPPORTED_HMAC_MODE
Unsupported HMAC mode (default: SHA256)
FKO_ERROR_UNSUPPORTED_FEATURE
Unsupported or unimplemented feature or function
FKO_ERROR_UNKNOWN
Unknown/Unclassified error

If GPG support is available, there are additional possible error conditions and error codes. The GPG support is implemented via GPGME. The libfko error handling code wraps many of the GPGME error codes that may be encountered while using libfko's GPG related functions. These are:

— Variable: int error_code (gpgme support only)
FKO_ERROR_MISSING_GPG_KEY_DATA
Missing GPG key data (signer or recipient not set)
FKO_ERROR_GPGME_NO_OPENPGP
This GPGME implementation does not support OpenPGP
FKO_ERROR_GPGME_CONTEXT
Unable to create GPGME context
FKO_ERROR_GPGME_PLAINTEXT_DATA_OBJ
Error creating the plaintext data object
FKO_ERROR_GPGME_SET_PROTOCOL
Unable to set GPGME to use OpenPGP protocol
FKO_ERROR_GPGME_CIPHER_DATA_OBJ
Error creating the encrypted data data object
FKO_ERROR_GPGME_BAD_PASSPHRASE
The GPG passphrase was not valid
FKO_ERROR_GPGME_ENCRYPT_SIGN
Error during the encrypt and sign operation
FKO_ERROR_GPGME_CONTEXT_SIGNER_KEY
Unable to create GPGME context for the signer key
FKO_ERROR_GPGME_SIGNER_KEYLIST_START
Error from signer keylist start operation
FKO_ERROR_GPGME_SIGNER_KEY_NOT_FOUND
The key for the given signer was not found
FKO_ERROR_GPGME_SIGNER_KEY_AMBIGUOUS
Ambiguous name/id for the signer key (mulitple matches)
FKO_ERROR_GPGME_ADD_SIGNER
Error adding the signer key to the gpgme context
FKO_ERROR_GPGME_CONTEXT_RECIPIENT_KEY
Unable to create GPGME context for the recipient key
FKO_ERROR_GPGME_RECIPIENT_KEYLIST_START
Error from signer keylist start operation
FKO_ERROR_GPGME_RECIPIENT_KEY_NOT_FOUND
The key for the given recipient was not found
FKO_ERROR_GPGME_RECIPIENT_KEY_AMBIGUOUS
Ambiguous name/id for the recipient key (mulitple matches)
FKO_ERROR_GPGME_DECRYPT_FAILED
Decryption operation failed
FKO_ERROR_GPGME_BAD_GPG_EXE
Unable to stat the given GPG executable
FKO_ERROR_GPGME_BAD_HOME_DIR
Unable to stat the given GPG home directory
FKO_ERROR_GPGME_SET_HOME_DIR
Unable to set the given GPG home directory
FKO_ERROR_GPGME_NO_SIGNATURE
Missing GPG signature
FKO_ERROR_GPGME_BAD_SIGNATURE
Bad GPG signature
FKO_ERROR_GPGME_SIGNATURE_VERIFY_DISABLED
Trying to check signature with verification disabled

You can use the IS_GPGME_ERROR(err_code) macro to determine whether or not an error id GPGME related. If the macro evaluates to a true value, you may be able to get additional information about the error using the following function:

— Function: const char * fko_gpg_errstr (int err_code)

The function fko_errstr returns a pointer to a statically allocated string containing the descripton of the GPGME error.

Note: For some errors, this function may return an empty string.