---

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.