---

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.