Gateway Persona Operations

#include <keychain/keychain_headers.h>

Overview

Gateway persona functions provide basic identity management operations through the Keychain Core C API. These functions work with personas, which are locally created and maintained cryptographic identities.

Persona Creation Functions

kc_gateway_create_persona()

int kc_gateway_create_persona(
    kc_gateway_t* gateway_ptr,
    kc_persona_t** out_persona,
    const char* name,
    const unsigned int name_size,
    const char* sub_name,
    const unsigned int subname_size,
    const kc_security_level security_level,
    const bool auto_renew
)

Creates a new persona with specified configuration.

Parameters:

  • gateway_ptr - Gateway instance

  • out_persona - Pointer to persona pointer (output, caller must free)

  • name - Persona name (unique identifier)

  • name_size - Length of persona name

  • sub_name - Persona subname

  • subname_size - Length of subname

  • security_level - Security level (see kc_security_level enum)

  • auto_renew - Enable automatic certificate renewal

Returns: Error code (0 = success)

Example:

kc_persona_t* alice_legal = NULL;
int result = kc_gateway_create_persona(gateway, &alice_legal,
                                      "alice", 5,
                                      "legal", 5,
                                      KC_SECURITY_LEVEL_HIGH,
                                      true); // Enable auto-renewal
if (result == 0) {
    printf("Created persona: alice.legal\n");

    // Use the persona...

    // Always clean up
    kc_persona_destruct(&alice_legal);
} else {
    printf("Failed to create persona: %d\n", result);
}

Persona Retrieval Functions

kc_gateway_retrieve_personas()

int kc_gateway_retrieve_personas(
    kc_gateway_t* gateway_ptr,
    kc_persona_t*** out_personas,
    unsigned int* out_count
)

Retrieves all persona objects from the gateway.

Parameters:

  • gateway_ptr - Gateway instance

  • out_personas - Pointer to persona array pointer (output, caller must free)

  • out_count - Pointer to array count (output)

Returns: Error code (0 = success)

Example:

kc_persona_t** personas = NULL;
unsigned int persona_count = 0;

int result = kc_gateway_retrieve_personas(gateway, &personas, &persona_count);
if (result == 0) {
    printf("Retrieved %u persona objects\n", persona_count);

    // Process each persona
    for (unsigned int i = 0; i < persona_count; i++) {
        // Use personas[i]...

        // Clean up individual persona
        kc_persona_destruct(&personas[i]);
    }

    // Clean up array
    kc_common_delete_ptr_array_shallow((void***)&personas);
} else {
    printf("Failed to retrieve personas: %d\n", result);
}

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)

Example:

kc_persona_t* alice = NULL;
int result = kc_gateway_retrieve_personas(gateway, &personas, &count);
if (result == 0 && count > 0) {
    // Renew the first persona's certificate
    result = kc_gateway_renew_certificate(gateway, personas[0]);
    if (result == 0) {
        printf("Certificate renewed successfully\n");
    } else {
        printf("Certificate renewal failed: %d\n", result);
    }

    // Cleanup
    for (unsigned int i = 0; i < count; i++) {
        kc_persona_destruct(&personas[i]);
    }
    kc_common_delete_ptr_array_shallow((void***)&personas);
}

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:

bool has_personas = false;
int result = kc_gateway_mature_persona_exists(gateway, &has_personas);
if (result == 0) {
    printf("Mature personas exist: %s\n", has_personas ? "yes" : "no");
} else {
    printf("Failed to check persona existence: %d\n", result);
}

Example: Basic Persona Management

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

void demonstrate_basic_persona_management(kc_gateway_t* gateway) {
    // Check if any personas exist
    bool has_personas = false;
    int result = kc_gateway_mature_persona_exists(gateway, &has_personas);
    if (result == 0) {
        printf("Existing mature personas: %s\n", has_personas ? "yes" : "no");
    }

    // Create a new persona if none exist
    if (!has_personas) {
        kc_persona_t* new_persona = NULL;
        result = kc_gateway_create_persona(gateway, &new_persona,
                                          "testuser", 8,
                                          "default", 7,
                                          KC_SECURITY_LEVEL_MEDIUM,
                                          true);
        if (result == 0) {
            printf("Created new persona: testuser.default\n");

            // The persona is now managed by the gateway
            // We can clean up our reference
            kc_persona_destruct(&new_persona);
        } else {
            printf("Failed to create persona: %d\n", result);
        }
    }

    // Retrieve all personas
    kc_persona_t** personas = NULL;
    unsigned int persona_count = 0;
    result = kc_gateway_retrieve_personas(gateway, &personas, &persona_count);
    if (result == 0) {
        printf("Found %u personas\n", persona_count);

        // Cleanup
        for (unsigned int i = 0; i < persona_count; i++) {
            kc_persona_destruct(&personas[i]);
        }
        kc_common_delete_ptr_array_shallow((void***)&personas);
    }
}

Memory Management

All persona objects returned by gateway functions must be properly freed:

  • Use kc_persona_destruct() to free individual persona objects

  • Use kc_common_delete_ptr_array_shallow() to free persona arrays

  • Always check function return codes before using output parameters

Security Considerations

  • Choose appropriate security levels based on your use case

  • Enable auto-renewal for production personas to avoid expiration

  • Monitor persona maturity status before performing cryptographic operations

See Also