---

3.4 Setting SPA Data

This section describes the functions used for setting the various SPA data fields and parameters. All of these functions return an integer representing the return status of the function. When succesfull, they will return FKO_SUCCESS. Otherwise, an error code value is returned.

Function: int fko_set_spa_digest_type (fko_ctx_t ctx, short digest_type); ¶

Set the message digest type. Valid values can be found in Digests of this manual. If a value other than the those that are supported is given, the function will return FKO_ERROR_INVALID_DATA. For example:

    rc = fko_set_digest_type(ctx, FKO_DIGEST_SHA1);

Function: int fko_set_spa_hmac_type (fko_ctx_t ctx, short hmac_type); ¶

Set the message hmac type. Valid values can be found in HMAC Digests of this manual. If a value other than the those that are supported is given, the function will return FKO_ERROR_INVALID_DATA. For example:

    rc = fko_set_hmac_type(ctx, FKO_HMAC_SHA256);

Function: int fko_set_spa_encryption_type (fko_ctx_t ctx, short encrypt_type); ¶

Set the encrytion algorithm to use when ecrypting the final SPA data. Valid values can be found in Encryption Algorithms of this manual. For example:

    rc = fko_set_encryption_type(ctx, FKO_ENCRYPTION_RIJNDAEL);

Function: int fko_set_rand_value (fko_ctx_t ctx, const char *val); ¶

Set the random value portion of the spa data to the given value (val). The given value must be a pointer to a 16-character decimal numeric string or NULL. If the value is NULL, the function generate a new random value. If a string value is provided, it must be a 16-character decimal string. Otherwise, the function will return FKO_ERROR_INVALID_DATA.

Function: int fko_set_username (fko_ctx_t ctx, const char *username); ¶

Set the username field of the SPA data. If username is NULL, libfko will first look for the environment variable SPOOF_USER and use its value if found. Otherwise, it will try to determine the username itself using various methods starting with cuser or getlogin, then fallback to the environment variables LOGNAME or USER. If none of those work, the function will return FKO_ERROR_USERNAME_UNKNOWN.

Function: int fko_set_timestamp (fko_ctx_t ctx, int offset); ¶

Sets the timestamp value of the SPA data to the current time plus the offset value.

Function: int fko_set_spa_message_type (fko_ctx_t ctx, short msg_type); ¶

Sets the message type for the SPA data. The choices for the spa_message_type are listed in SPA Messages. For example:

    rc = fko_set_spa_message_type(ctx, FKO_ACCESS_MSG);

Function: int fko_set_spa_message (fko_ctx_t ctx, const char *msg_string); ¶

Set the SPA message string to the given value. If this string does not conform to the required spa_nat_access format, the function will return FKO_ERROR_INVALID_DATA.

Function: int fko_set_spa_nat_access (fko_ctx_t ctx, const char *nat_access); ¶

Set the optional SPA nat access string to the given value. If this string does not conform to the required spa_nat_access format, the function will return FKO_ERROR_INVALID_DATA.

Function: int fko_set_spa_server_auth (fko_ctx_t ctx, const char *server_auth); ¶

Set the optional (very seldom used) SPA server auth feature to the given value. This parameter may become deprecated.

Function: int fko_set_spa_client_timeout (fko_ctx_t ctx, int timeout); ¶

Sets the SPA client timeout value. If the timeout is set to a value greater than 0, it is assumed the spa_message_type setting should be one of the “TIMEOUT” variants. This function will change the message_type to the appropriate setting if necessary. However, it is recommended you set the correct message_type ahead of time.

Function: int fko_set_spa_digest (fko_ctx_t ctx); ¶

Initiates a calculation (or recalculation) of the message digest hash for the current SPA data. If the required data fields are not set this function will return FKO_ERROR_MISSING_ENCODED_DATA. Note: It should not be necessary to call this function directly as it will be called automatically by other functions during normal processing (most notably fko_spa_data_final).

Function: int fko_set_spa_hmac (fko_ctx_t ctx, const char *hmac_key, const int hmac_key_len); ¶

Initiates a calculation (or recalculation) of the message HMAC for the current SPA data. Note: It should not be necessary to call this function directly as it will be called automatically by other functions during normal processing (most notably fko_spa_data_final).

Function: int fko_set_spa_data (fko_ctx_t ctx, char *enc_data); ¶

This function is used to place encrypted SPA data into a newly created empty context (i.e. with fko_new). In most cases, you would use fko_new_with_data so you wouldn’t have to take the extra step to use this function. However, some may find a reason to do it in this way.

GPG-specific functions:

Function: int fko_set_gpg_recipient (fko_ctx_t ctx, const char recipient); ¶

Sets the GPG key for the recipient. This would be the recipient’s public key used to encyrpt the SPA data. You can use the user name ("recip@the.dest.com") or the key ID ("5EXXXXCC"). At present, multiple recipients are not supported.

Function: int fko_set_gpg_signer (fko_ctx_t ctx, const char signer); ¶

Sets the GPG key for signing the data. This would be the sender’s key used to sign the SPA data. You can use the user name or key ID.

Function: int fko_set_gpg_home_dir (fko_ctx_t ctx, const char home_dir); ¶

Sets the GPG home directory for the current gpgme context. This allows for using alternate keyrings, gpg configurations, etc.

Function: int fko_set_gpg_signature_verify (fko_ctx_t ctx, unsigned char verify); ¶

Sets the verify GPG signature flag. When set to a true value, the GPG signature is extracted and checked for validity during the decryption/decoding phase. When set to false, no attempt is made to access or check the signature. This flag is set to true by default.

Function: int fko_set_gpg_ignore_verify_error (fko_ctx_t ctx, unsigned char ignore); ¶

Sets the ignore signature verify error flag. When set to a true value. Any signature verification errors are ignored (but still captured) and the decoding process will continue. The default value of this flag is false.

Function: int fko_set_gpg_exe (fko_ctx_t ctx, const char gpg_exe); ¶

Sets the path to the GPG executable that gpgme will use. By default, libfko forces gpgme to use gpg in case gpgme was compiled to use gpg2 as its default engine. You can use this function to override and set what GPG executable gpgme will use.

Note: On a libfko build without GPG support, the GPG-related functions above will simply return the FKO_ERROR_UNSUPPORTED_FEATURE error code.