### 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_message` 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.