Keychain Element Functions

#include <keychain/keychain_headers.h>

Overview

Keychain element functions work with individual cryptographic key elements within a keychain. Each element represents a specific key pair within a keychain’s lifecycle and includes the public key, associated DIDs, cryptographic proofs, and status information.

A keychain_element is comprised of the public key and metadata about the public key, providing detailed key management, usage tracking, and lifecycle operations.

Object Lifecycle Functions

kc_keychain_element_construct_from_copy()

int kc_keychain_element_construct_from_copy(
    kc_keychain_element_t** out_keychain_element_ptr,
    const kc_keychain_element_t* rhs_keychain_element_ptr
)

Creates a deep copy of an existing keychain element.

Parameters:

  • out_keychain_element_ptr - Pointer to keychain element pointer (output, caller must free)

  • rhs_keychain_element_ptr - The keychain element object to be copied

Returns: Error code (0 = success)

Example:

kc_keychain_element_t* original_element = NULL;
kc_keychain_element_t* copied_element = NULL;

// ... get original_element from somewhere ...

int result = kc_keychain_element_construct_from_copy(&copied_element, original_element);
if (result == 0) {
    // Use copied_element...
    kc_keychain_element_destruct(&copied_element);
}

kc_keychain_element_destruct()

int kc_keychain_element_destruct(kc_keychain_element_t** keychain_element_ptr)

Destructs a keychain element object and frees its resources.

Parameters:

  • keychain_element_ptr - Pointer to keychain element pointer (set to NULL on success)

Returns: Error code (0 = success)

Example:

kc_keychain_element_t* element = NULL;
// ... get element from somewhere ...
int result = kc_keychain_element_destruct(&element);
if (result == 0) {
    // element is now NULL
    printf("Keychain element destructed successfully\n");
}

Comparison Functions

kc_keychain_element_equals()

int kc_keychain_element_equals(
    const kc_keychain_element_t* lhs_keychain_element_ptr,
    bool* out_is_equal,
    const kc_keychain_element_t* rhs_keychain_element_ptr
)

Tests equality of two keychain elements by comparing their fields.

Parameters:

  • lhs_keychain_element_ptr - The left-hand side keychain element for comparison

  • out_is_equal - Pointer to boolean result (output)

  • rhs_keychain_element_ptr - The right-hand side keychain element for comparison

Returns: Error code (0 = success)

Example:

kc_keychain_element_t* element1 = NULL;
kc_keychain_element_t* element2 = NULL;
bool are_equal = false;

// ... get elements from somewhere ...

int result = kc_keychain_element_equals(element1, &are_equal, element2);
if (result == 0) {
    if (are_equal) {
        printf("Elements are equal\n");
    } else {
        printf("Elements are different\n");
    }
}

Property Access Functions

kc_keychain_element_public_key()

int kc_keychain_element_public_key(
    const kc_keychain_element_t* keychain_element_ptr,
    char** out_str,
    unsigned int* out_size
)

Gets the public key in hex-encoded DER format.

Parameters:

  • keychain_element_ptr - The keychain element object

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

  • out_size - Pointer to size variable (output)

Returns: Error code (0 = success)

Example:

kc_keychain_element_t* element = NULL;
char* public_key = NULL;
unsigned int key_size = 0;

// ... get element from somewhere ...

int result = kc_keychain_element_public_key(element, &public_key, &key_size);
if (result == 0) {
    printf("Public key: %.*s\n", key_size, public_key);
    free(public_key);
}

kc_keychain_element_proof()

int kc_keychain_element_proof(
    const kc_keychain_element_t* keychain_element_ptr,
    char** out_str,
    unsigned int* out_size
)

Gets the proof text that provides evidence of the element’s validity.

Parameters:

  • keychain_element_ptr - The keychain element object

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

  • out_size - Pointer to size variable (output)

Returns: Error code (0 = success)

Example:

kc_keychain_element_t* element = NULL;
char* proof = NULL;
unsigned int proof_size = 0;

// ... get element from somewhere ...

int result = kc_keychain_element_proof(element, &proof, &proof_size);
if (result == 0) {
    printf("Proof: %.*s\n", proof_size, proof);
    free(proof);
}

kc_keychain_element_dids()

int kc_keychain_element_dids(
    const kc_keychain_element_t* keychain_element_ptr,
    kc_keychain_did_t*** out_dids,
    unsigned int* out_array_size
)

Gets the array of DIDs associated with this keychain element.

Parameters:

  • keychain_element_ptr - The keychain element object

  • out_dids - Pointer to DID array pointer (output, caller must free)

  • out_array_size - Pointer to array size variable (output)

Returns: Error code (0 = success)

Example:

kc_keychain_element_t* element = NULL;
kc_keychain_did_t** dids = NULL;
unsigned int num_dids = 0;

// ... get element from somewhere ...

int result = kc_keychain_element_dids(element, &dids, &num_dids);
if (result == 0) {
    printf("Element has %u DIDs\n", num_dids);

    // Clean up DIDs array
    for (unsigned int i = 0; i < num_dids; i++) {
        kc_keychain_did_destruct(&dids[i]);
    }
    free(dids);
}

kc_keychain_element_index()

int kc_keychain_element_index(
    const kc_keychain_element_t* keychain_element_ptr,
    unsigned int* out_index
)

Gets the zero-based index of this element’s position in the keychain.

Parameters:

  • keychain_element_ptr - The keychain element object

  • out_index - Pointer to index variable (output)

Returns: Error code (0 = success)

Example:

kc_keychain_element_t* element = NULL;
unsigned int index = 0;

// ... get element from somewhere ...

int result = kc_keychain_element_index(element, &index);
if (result == 0) {
    printf("Element index: %u\n", index);
}

kc_keychain_element_algorithm()

int kc_keychain_element_algorithm(
    const kc_keychain_element_t* keychain_element_ptr,
    unsigned int* out_algorithm
)

Gets the cryptographic algorithm used by this element. The result should be cast to a signature_scheme or encryption_scheme value depending on the keychain type.

Parameters:

  • keychain_element_ptr - The keychain element object

  • out_algorithm - Pointer to algorithm variable (output)

Returns: Error code (0 = success)

Example:

kc_keychain_element_t* element = NULL;
unsigned int algorithm = 0;

// ... get element from somewhere ...

int result = kc_keychain_element_algorithm(element, &algorithm);
if (result == 0) {
    printf("Algorithm ID: %u\n", algorithm);
    // Cast to appropriate enum based on keychain type:
    // signature_scheme sig_scheme = (signature_scheme)algorithm;
    // encryption_scheme enc_scheme = (encryption_scheme)algorithm;
}

Usage Example

#include <keychain/keychain_headers.h>

int main() {
    kc_settings_t* settings = NULL;
    kc_gateway_t* gateway = NULL;
    kc_keychain_t* keychain = NULL;
    kc_keychain_element_t** elements = NULL;
    unsigned int num_elements = 0;

    // Initialize and get keychain
    int result = kc_gateway_init(&settings, "keychain.cfg", 12);
    if (result != 0) return result;

    result = kc_gateway_construct(&gateway, settings);
    if (result != 0) goto cleanup;

    // Get a keychain and its elements
    // ... get keychain from persona or contact ...

    result = kc_keychain_elements(keychain, &elements, &num_elements);
    if (result != 0) goto cleanup;

    // Process each element
    for (unsigned int i = 0; i < num_elements; i++) {
        char* public_key = NULL;
        unsigned int key_size = 0;
        unsigned int index = 0;

        // Get element information
        result = kc_keychain_element_public_key(elements[i], &public_key, &key_size);
        if (result == 0) {
            result = kc_keychain_element_index(elements[i], &index);
            if (result == 0) {
                printf("Element %u: %.*s\n", index, key_size, public_key);
            }
            free(public_key);
        }
    }

cleanup:
    // Clean up elements
    if (elements) {
        for (unsigned int i = 0; i < num_elements; i++) {
            kc_keychain_element_destruct(&elements[i]);
        }
        free(elements);
    }

    kc_keychain_destruct(&keychain);
    kc_gateway_destruct(&gateway);
    kc_settings_destruct(&settings);

    return result;
}

See Also