Gateway Functions

#include <keychain/keychain_headers.h>

Overview

Gateway functions provide the core interface for Keychain operations including initialization, lifecycle management, and basic utility functions.

Initialization Functions

kc_gateway_init()

int kc_gateway_init(
    kc_settings_t** out_settings,
    const char* config_path,
    const int config_path_size
)

Initializes the Keychain library and creates settings object.

Parameters:

  • out_settings - Pointer to settings pointer (output)

  • config_path - Path to configuration file

  • config_path_size - Length of config path string

Returns: Error code (0 = success)

Example:

kc_settings_t* settings = NULL;
int result = kc_gateway_init(&settings, "keychain.cfg", 12);
if (result != 0) {
    // Handle initialization error
}

kc_gateway_construct()

int kc_gateway_construct(
    kc_gateway_t** out_gateway_ptr,
    const kc_settings_t* settings
)

Constructs a gateway instance with provided settings.

Parameters:

  • out_gateway_ptr - Pointer to gateway pointer (output)

  • settings - Settings object from init

Returns: Error code (0 = success)

kc_gateway_destruct()

int kc_gateway_destruct(kc_gateway_t** gateway_ptr)

Destructs a gateway instance and frees memory.

Parameters:

  • gateway_ptr - Pointer to gateway pointer (set to NULL on success)

Returns: Error code (0 = success)

kc_gateway_close()

void kc_gateway_close()

Cleans up static library resources. Call at application shutdown.

Returns: None (void function)

Utility Functions

kc_gateway_hash()

int kc_gateway_hash(
    char** out_hash_hex,
    int* out_hash_size,
    const char* input_data,
    const int input_data_size
)

Computes SHA-256 hash of input data.

Parameters:

  • out_hash_hex - Pointer to hash string pointer (output, caller must free)

  • out_hash_size - Pointer to hash string length (output)

  • input_data - Data to hash

  • input_data_size - Length of input data

Returns: Error code (0 = success)

Example:

char* hash_result = NULL;
int hash_size = 0;
int result = kc_gateway_hash(
    &hash_result, &hash_size, "test data", 9
);
if (result == 0) {
    printf("Hash: %s\n", hash_result);
    kc_common_delete_buffer(&hash_result);
}

kc_gateway_generate_signature_by_private_key()

int kc_gateway_generate_signature_by_private_key(
    char** out_signature_hex,
    int* out_signature_size,
    const char* cleartext,
    const int cleartext_size,
    const char* private_key_hex,
    const int private_key_size,
    tkc_signature_scheme algorithm
)

Generates a signature using an external private key.

Parameters:

  • out_signature_hex - Pointer to signature string pointer (output)

  • out_signature_size - Pointer to signature string length (output)

  • cleartext - Data to sign

  • cleartext_size - Length of cleartext

  • private_key_hex - Private key in hex format

  • private_key_size - Length of private key string

  • algorithm - Signature algorithm to use

Returns: Error code (0 = success)

kc_gateway_verify_raw_data()

int kc_gateway_verify_raw_data(
    bool* out_verified,
    const char* cleartext,
    const int cleartext_size,
    const char* public_key_hex,
    const int public_key_size,
    const char* signature_hex,
    const int signature_size,
    tkc_signature_scheme algorithm
)

Verifies a signature against a public key without persona/contact context.

Parameters:

  • out_verified - Pointer to verification flag (output, true = valid, false = invalid)

  • cleartext - Original signed data

  • cleartext_size - Length of cleartext

  • public_key_hex - Public key in hex format

  • public_key_size - Length of public key string

  • signature_hex - Signature in hex format

  • signature_size - Length of signature string

  • algorithm - Signature algorithm used

Returns: Error code (0 = success)

Cache Management

kc_gateway_force_update_cache()

int kc_gateway_force_update_cache(kc_gateway_t* gateway_ptr)

Forces an update of the PKI cache state.

Parameters:

  • gateway_ptr - Gateway instance

Returns: Error code (0 = success)

Monitor Lifecycle

kc_gateway_on_start()

int kc_gateway_on_start(kc_gateway_t* gateway_ptr)

Starts PKI monitoring services.

Parameters:

  • gateway_ptr - Gateway instance

Returns: Error code (0 = success)

kc_gateway_on_pause()

int kc_gateway_on_pause(kc_gateway_t* gateway_ptr)

Pauses PKI monitoring services.

Parameters:

  • gateway_ptr - Gateway instance

Returns: Error code (0 = success)

kc_gateway_on_resume()

int kc_gateway_on_resume(kc_gateway_t* gateway_ptr)

Resumes PKI monitoring services.

Parameters:

  • gateway_ptr - Gateway instance

Returns: Error code (0 = success)

kc_gateway_on_stop()

int kc_gateway_on_stop(kc_gateway_t* gateway_ptr)

Stops PKI monitoring services.

Parameters:

  • gateway_ptr - Gateway instance

Returns: Error code (0 = success)

Certificate Management

kc_gateway_renew_certificate()

int kc_gateway_renew_certificate(
    kc_gateway_t* gateway_ptr,
    kc_persona_t* persona_ptr
)

Manually renews a persona’s certificate.

Parameters:

  • gateway_ptr - Gateway instance

  • persona_ptr - Persona to renew

Returns: Error code (0 = success)

Status Checking

kc_gateway_mature_persona_exists()

int kc_gateway_mature_persona_exists(
    kc_gateway_t* gateway_ptr,
    bool* out_exists
)

Checks if any mature persona exists in the gateway.

Parameters:

  • gateway_ptr - Gateway instance

  • out_exists - Pointer to existence flag (output, true = exists, false = none)

Returns: Error code (0 = success)

Example: Complete Gateway Setup

#include <keychain/keychain_headers.h>
#include <stdio.h>
#include <stdlib.h>

int main() {
    // Initialize library
    kc_settings_t* settings = NULL;
    int result = kc_gateway_init(&settings, "keychain.cfg", 12);
    if (result != 0) {
        printf("Failed to initialize: %d\n", result);
        return 1;
    }

    // Create gateway
    kc_gateway_t* gateway = NULL;
    result = kc_gateway_construct(&gateway, settings);
    if (result != 0) {
        printf("Failed to create gateway: %d\n", result);
        kc_settings_destruct(&settings);
        return 1;
    }

    // Start monitoring
    result = kc_gateway_on_start(gateway);
    if (result != 0) {
        printf("Failed to start monitoring: %d\n", result);
        goto cleanup;
    }

    // Check for existing personas
    unsigned char has_personas = 0;
    result = kc_gateway_mature_persona_exists(gateway, &has_personas);
    if (result == 0) {
        printf("Mature personas exist: %s\n", has_personas ? "yes" : "no");
    }

    // Hash some data
    char* hash_result = NULL;
    int hash_size = 0;
    result = kc_gateway_hash(&hash_result, &hash_size, "test", 4);
    if (result == 0) {
        printf("Hash of 'test': %s\n", hash_result);
        kc_common_delete_buffer(&hash_result);
    }

    // Application logic here...

cleanup:
    // Stop monitoring
    kc_gateway_on_stop(gateway);

    // Cleanup
    kc_gateway_destruct(&gateway);
    kc_settings_destruct(&settings);
    kc_gateway_close();

    return 0;
}

Error Handling

int result = kc_gateway_construct(&gateway, settings);
if (result != 0) {
    // Get detailed error message
    char* error_message = NULL;
    int message_size = 0;
    kc_common_get_error_message(&error_message, &message_size, result);
    printf("Gateway construction failed: %s\n", error_message);
    kc_common_delete_buffer(&error_message);
}

See Also