### 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 description 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 mismatch

  `FKO_ERROR_INVALID_DATA`

    Args contain invalid data

  `FKO_ERROR_INVALID_DATA_CLIENT_TIMEOUT_NEGATIVE`

    Invalid data: negative timeout value

  `FKO_ERROR_INVALID_DATA_DECODE_MSGLEN_VALIDFAIL`

    Invalid data: invalid message length

  `FKO_ERROR_INVALID_DATA_DECODE_NON_ASCII`

    Invalid data: contains non-ascii characters

  `FKO_ERROR_INVALID_DATA_DECODE_LT_MIN_FIELDS`

    Invalid data: insufficient number of data fields

  `FKO_ERROR_INVALID_DATA_DECODE_GT_MAX_FIELDS`

    Invalid data: too many data fields

  `FKO_ERROR_INVALID_DATA_DECODE_WRONG_NUM_FIELDS`

    Invalid data: invalid number of fields

  `FKO_ERROR_INVALID_DATA_DECODE_ENC_MSG_LEN_MT_T_SIZE`

    Invalid data: decode: encoded message - digest size is not valid

  `FKO_ERROR_INVALID_DATA_DECODE_RAND_MISSING`

    Invalid data: decode: missing random data

  `FKO_ERROR_INVALID_DATA_DECODE_USERNAME_MISSING`

    Invalid data: decode: missing username

  `FKO_ERROR_INVALID_DATA_DECODE_USERNAME_TOOBIG`

    Invalid data: decode: username to large

  `FKO_ERROR_INVALID_DATA_DECODE_USERNAME_DECODEFAIL`

    Invalid data: decode: failed to decode username

  `FKO_ERROR_INVALID_DATA_DECODE_USERNAME_VALIDFAIL`

    Invalid data: decode: invalid username

  `FKO_ERROR_INVALID_DATA_DECODE_TIMESTAMP_MISSING`

    Invalid data: decode: missing timestamp

  `FKO_ERROR_INVALID_DATA_DECODE_TIMESTAMP_TOOBIG`

    Invalid data: decode: timestamp too large

  `FKO_ERROR_INVALID_DATA_DECODE_TIMESTAMP_DECODEFAIL`

    Invalid data: decode: failed to decode timestamp

  `FKO_ERROR_INVALID_DATA_DECODE_VERSION_MISSING`

    Invalid data: decode: missing version data

  `FKO_ERROR_INVALID_DATA_DECODE_VERSION_TOOBIG`

    Invalid data: decode: version data is too large

  `FKO_ERROR_INVALID_DATA_DECODE_MSGTYPE_MISSING`

    Invalid data: decode: missing message type

  `FKO_ERROR_INVALID_DATA_DECODE_MSGTYPE_TOOBIG`

    Invalid data: decode: message type is too large

  `FKO_ERROR_INVALID_DATA_DECODE_MSGTYPE_DECODEFAIL`

    Invalid data: decode: failed to decode message type

  `FKO_ERROR_INVALID_DATA_DECODE_MESSAGE_MISSING`

    Invalid data: decode: missing message data

  `FKO_ERROR_INVALID_DATA_DECODE_MESSAGE_TOOBIG`

    Invalid data: decode: message data is too large

  `FKO_ERROR_INVALID_DATA_DECODE_MESSAGE_DECODEFAIL`

    Invalid data: decode: failed to decode message data

  `FKO_ERROR_INVALID_DATA_DECODE_MESSAGE_VALIDFAIL`

    Invalid data: decode: invalid message data

  `FKO_ERROR_INVALID_DATA_DECODE_ACCESS_VALIDFAIL`

    Invalid data: decode: invliad access data

  `FKO_ERROR_INVALID_DATA_DECODE_NATACCESS_MISSING`

    Invalid data: decode: missing NAT access data

  `FKO_ERROR_INVALID_DATA_DECODE_NATACCESS_TOOBIG`

    Invalid data: decode: NAT access data is too large

  `FKO_ERROR_INVALID_DATA_DECODE_NATACCESS_DECODEFAIL`

    Invalid data: decode: failed to decode NAT access data

  `FKO_ERROR_INVALID_DATA_DECODE_NATACCESS_VALIDFAIL`

    Invalid data: decode: invalid NAT access

  `FKO_ERROR_INVALID_DATA_DECODE_SRVAUTH_MISSING`

    Invalid data: decode: missing server auth

  `FKO_ERROR_INVALID_DATA_DECODE_SRVAUTH_DECODEFAIL`

    Invalid data: decode: server auth decode fail

  `FKO_ERROR_INVALID_DATA_DECODE_SPA_EXTRA_TOOBIG`

    Invalid data: decode: SPA extra too large

  `FKO_ERROR_INVALID_DATA_DECODE_EXTRA_TOOBIG`

    Invalid data: decode: extra too large

  `FKO_ERROR_INVALID_DATA_DECODE_EXTRA_DECODEFAIL`

    Invalid data: decode: extra decode failed

  `FKO_ERROR_INVALID_DATA_DECODE_TIMEOUT_MISSING`

    Invalid data: decode: missing timeout

  `FKO_ERROR_INVALID_DATA_DECODE_TIMEOUT_TOOBIG`

    Invalid data: decode timeout value is too large

  `FKO_ERROR_INVALID_DATA_DECODE_TIMEOUT_VALIDFAIL`

    Invalid data: decode invalid timeout

  `FKO_ERROR_INVALID_DATA_DECODE_TIMEOUT_DECODEFAIL`

    Invalid data: decode: timeout decode failed

  `FKO_ERROR_INVALID_DATA_ENCODE_MESSAGE_TOOBIG`

    Invalid data: encode: message is too large

  `FKO_ERROR_INVALID_DATA_ENCODE_MSGLEN_VALIDFAIL`

    Invalid data: encode: invalid message length

  `FKO_ERROR_INVALID_DATA_ENCODE_DIGEST_VALIDFAIL`

    Invalid data: encode: invalid digest

  `FKO_ERROR_INVALID_DATA_ENCODE_DIGEST_TOOBIG`

    Invalid data: encode: digest is too large

  `FKO_ERROR_INVALID_DATA_ENCODE_NOTBASE64`

    Invalid data: encoded data is not Base64

  `FKO_ERROR_INVALID_DATA_ENCRYPT_MSGLEN_VALIDFAIL`

    Invalid data: encrypt: invalid message length

  `FKO_ERROR_INVALID_DATA_ENCRYPT_DIGESTLEN_VALIDFAIL`

    Invalid data: encrypt: invalid digest length

  `FKO_ERROR_INVALID_DATA_ENCRYPT_PTLEN_VALIDFAIL`

    Invalid data: encrypt: invalid plaintext length

  `FKO_ERROR_INVALID_DATA_ENCRYPT_RESULT_MSGLEN_VALIDFAIL`

    Invalid data: encrypt: invalid encrypt result message length

  `FKO_ERROR_INVALID_DATA_ENCRYPT_CIPHERLEN_DECODEFAIL`

    Invalid data: encrypt: decode cipher length failed

  `FKO_ERROR_INVALID_DATA_ENCRYPT_CIPHERLEN_VALIDFAIL`

    Invalid data: encrypt: invalid cipher length

  `FKO_ERROR_INVALID_DATA_ENCRYPT_DECRYPTED_MESSAGE_MISSING`

    Invalid data: encrypt: missing decrypted message

  `FKO_ERROR_INVALID_DATA_ENCRYPT_DECRYPTED_MSGLEN_VALIDFAIL`

    Invalid data: encrypt: invalid decrypted message length

  `FKO_ERROR_INVALID_DATA_ENCRYPT_TYPE_VALIDFAIL`

    Invalid data: encrypt: invalid encryption type

  `FKO_ERROR_INVALID_DATA_ENCRYPT_MODE_VALIDFAIL`

    Invalid data: encrypt: invalid encryption mode

  `FKO_ERROR_INVALID_DATA_ENCRYPT_TYPE_UNKNOWN`

    Invalid data: encrypt: unknown encryption type

  `FKO_ERROR_INVALID_DATA_FUNCS_NEW_ENCMSG_MISSING`

    Invalid data: missing encoded message

  `FKO_ERROR_INVALID_DATA_FUNCS_NEW_MSGLEN_VALIDFAIL`

    Invalid data: invalid message length from new

  `FKO_ERROR_INVALID_DATA_FUNCS_GEN_KEYLEN_VALIDFAIL`

    Invalid data: invalid key length from gen_keylen

  `FKO_ERROR_INVALID_DATA_FUNCS_GEN_HMACLEN_VALIDFAIL`

    Invalid data: gen_hmaclen failure

  `FKO_ERROR_INVALID_DATA_FUNCS_GEN_KEY_ENCODEFAIL`

    Invalid data: gen_key: encode failure

  `FKO_ERROR_INVALID_DATA_FUNCS_GEN_HMAC_ENCODEFAIL`

    Invalid data: gen_hmac: encode failure

  `FKO_ERROR_INVALID_DATA_FUNCS_SET_MSGLEN_VALIDFAIL`

    Invalid data: set_spa_data: invalid message length

  `FKO_ERROR_INVALID_DATA_HMAC_MSGLEN_VALIDFAIL`

    Invalid data: invalid HMAC msglen

  `FKO_ERROR_INVALID_DATA_HMAC_ENCMSGLEN_VALIDFAIL`

    Invalid data: invalid length for encrypted message

  `FKO_ERROR_INVALID_DATA_HMAC_COMPAREFAIL`

    Invalid data: HMAC comparison failed

  `FKO_ERROR_INVALID_DATA_HMAC_TYPE_VALIDFAIL`

    Invalid data: invalid HMAC type

  `FKO_ERROR_INVALID_DATA_HMAC_LEN_VALIDFAIL`

    Invalid data: invalid HMAC length

  `FKO_ERROR_INVALID_DATA_MESSAGE_PORT_MISSING`

    Invalid data: missing port

  `FKO_ERROR_INVALID_DATA_MESSAGE_TYPE_VALIDFAIL`

    Invalid data: invalid message type

  `FKO_ERROR_INVALID_DATA_MESSAGE_EMPTY`

    Invalid data: empty data message

  `FKO_ERROR_INVALID_DATA_MESSAGE_CMD_MISSING`

    Invalid data: missing command message

  `FKO_ERROR_INVALID_DATA_MESSAGE_ACCESS_MISSING`

    Invalid data: missing access message

  `FKO_ERROR_INVALID_DATA_MESSAGE_NAT_MISSING`

    Invalid data: missing NAT data

  `FKO_ERROR_INVALID_DATA_MESSAGE_PORTPROTO_MISSING`

    Invalid data: missing proto/port data

  `FKO_ERROR_INVALID_DATA_NAT_EMPTY`

    Invalid data: empty NAT value

  `FKO_ERROR_INVALID_DATA_RAND_LEN_VALIDFAIL`

    Invalid data: invalid random data length

  `FKO_ERROR_INVALID_DATA_SRVAUTH_MISSING`

    Invalid data: server auth missing

  `FKO_ERROR_INVALID_DATA_TIMESTAMP_VALIDFAIL`

    Invalid data: invalid timestamp value

  `FKO_ERROR_INVALID_DATA_USER_MISSING`

    Invalid data: missing user data

  `FKO_ERROR_INVALID_DATA_USER_FIRSTCHAR_VALIDFAIL`

    Invalid data: user first char not valid

  `FKO_ERROR_INVALID_DATA_USER_REMCHAR_VALIDFAIL`

    Invalid data: user remchar not valid

  `FKO_ERROR_INVALID_DATA_UTIL_STRTOL_LT_MIN`

    Invalid data: util conversion to long less than minimum

  `FKO_ERROR_INVALID_DATA_UTIL_STRTOL_GT_MAX`

    Invalid data: util conversion to long greater than maximum

  `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_ZERO_OUT_DATA`

    Could not zero out sensitive data

  `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 (multiple 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 (multiple 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

  `FKO_ERROR_INVALID_DATA_ENCRYPT_GPG_MESSAGE_VALIDFAIL`

    Invalid data: encrypt: invalid GPG-encrypt message

  `FKO_ERROR_INVALID_DATA_ENCRYPT_GPG_DIGEST_VALIDFAIL`

    Invalid data: encrypt: invalid GPG digest

  `FKO_ERROR_INVALID_DATA_ENCRYPT_GPG_MSGLEN_VALIDFAIL`

    Invalid data: encrypt: invalid GPG message length

  `FKO_ERROR_INVALID_DATA_ENCRYPT_GPG_RESULT_MSGLEN_VALIDFAIL`

    Invalid data: encrypt: invalid GPG result message length

  `FKO_ERROR_INVALID_DATA_ENCRYPT_GPG_CIPHER_DECODEFAIL`

    Invalid data: encrypt: GPG cipher failed

  `FKO_ERROR_INVALID_DATA_ENCRYPT_GPG_ENCODEDMSG_NULL`

    Invalid data: encrypt: GPG-encoded message is NULL

  `FKO_ERROR_INVALID_DATA_ENCRYPT_GPG_ENCODEDMSGLEN_VALIDFAIL`

    Invalid data: encrypt: invalid GPG-encrypted message length

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 description of the GPGME error.

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