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.