### 3.6 Utility Functions ¶

This section describes the functions not covered elsewhere in this manual. These are utility functions that operate on the data in the fko context. All but `fko_spa_data_final` are called by other functions and are not normally explicitly called by the user. However, they can be, so they are listed here.

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_spa_data_final `(fko_ctx_t ctx, char *enc_key, int ken_len, char *hmac_key, int hmac_key_len);` ¶

  This function is the final step in creating a complete encrypted SPA data string suitable for transmission to an fwknop server. It does require all of the requisite SPA data fields be set, otherwise it will fail with an appropriate error code.

Function: `int` fko_decrypt_spa_data `(fko_ctx_t ctx, char *dec_key, int key_len);` ¶

  When given the correct key (password), this function decrypts, decodes, and parses the encrypted SPA data that was supplied to the context via the `fko_new_with_data` function that was also called without the key value. Once the data is decrypted, this function will also call `fko_decode_spa_data` to decode, parse, validate, and store the data fields in the context for later retrieval.

Function: `int` fko_encrypt_spa_data `(fko_ctx_t ctx, char *enc_key, int key_len);` ¶

  Encrypts the intermediate encoded SPA data stored in the context. This function will call `fko_encode` if necessary. It is normally not called directly as it is called from `fko_spa_data_final`.

Function: `int` fko_decode_spa_data `(fko_ctx_t ctx);` ¶

  This function performs the decoding, parsing, validation of the SPA data that was just decrypted. It is normally not called directly as it is called from `fko_decrypt_spa_data` (which is in turn called from `fko_new_with_data` if a password is supplied to it).

Function: `int` fko_encode_spa_data `(fko_ctx_t ctx);` ¶

  Performs the base64 encoding of those SPA data fields that need to be encoded, performs some data validation, and calls `fkp_set_spa_digest` to recompute the SPA message digest. It is normally not called directly as it is called from `fko_encrypt_spa_data` (which is in turn called from `fko_spa_data_final`).

GPG-specific utility functions:

Function: `int` fko_gpg_signature_id_match `(fko_ctx_t ctx, const char *id, unsigned char *id_match);` ¶

  Sets the value of the id_match variable to true (1) if the value of id matches the ID of the GPG signature associated with the current context. Otherwise, id_match is set to false (0). The return value is an FKO error status.

Function: `int` fko_gpg_signature_fpr_match `(fko_ctx_t ctx, const char *fpr, unsigned char *fpr_match);` ¶

  Sets the value of the fpr_match variable to true (1) if the value of fpr matches the fingerprint of the GPG signature associated with the current context. Otherwise, fpr_match is set to false (0). The return value is an FKO error status.