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.
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);
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);
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);
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
.
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
orgetlogin
, then fallback to the environment variables LOGNAME or USER. If none of those work, the function will returnFKO_ERROR_USERNAME_UNKNOWN
.
Sets the timestamp value of the SPA data to the current time plus the offset value.
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);
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 returnFKO_ERROR_INVALID_DATA
.
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 returnFKO_ERROR_INVALID_DATA
.
Set the optional (very seldom used) SPA server auth feature to the given value. This parameter may become deprecated.
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 themessage_type
to the appropriate setting if necessary. However, it is recommended you set the correctmessage_type
ahead of time.
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 notablyfko_spa_data_final
).
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
).
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 usefko_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.
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.
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.
Sets the GPG home directory for the current gpgme context. This allows for using alternate keyrings, gpg configurations, etc.
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.
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.
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.