C API Enumerations

#include <keychain/keychain_headers.h>

Overview

The Keychain Core C API defines several enumerations that specify algorithm choices, data types, security levels, and other configuration options. This page documents all enums available in the C API.

Security and Algorithm Enums

kc_security_level

Persona security level determines the parameters of the private and public keys generated during persona creation.

typedef enum {
    KC_SECURITY_LEVEL_UNKNOWN_LEVEL = 0,
    KC_SECURITY_LEVEL_LIGHTWEIGHT = 1,
    KC_SECURITY_LEVEL_LOW = 2,
    KC_SECURITY_LEVEL_MEDIUM = 3,
    KC_SECURITY_LEVEL_HIGH = 4,
    KC_SECURITY_LEVEL_VERY_HIGH = 5
} kc_security_level;

Values:

  • KC_SECURITY_LEVEL_UNKNOWN_LEVEL - Unspecified security level

  • KC_SECURITY_LEVEL_LIGHTWEIGHT - Minimal security (fastest operations)

  • KC_SECURITY_LEVEL_LOW - Basic security level

  • KC_SECURITY_LEVEL_MEDIUM - Standard security level (recommended for most use cases)

  • KC_SECURITY_LEVEL_HIGH - Enhanced security level

  • KC_SECURITY_LEVEL_VERY_HIGH - Maximum security level (slower operations)

Usage:

// Create a persona with high security
kc_persona_t* secure_persona = NULL;
int result = kc_gateway_create_persona(gateway, &secure_persona,
                                      "alice", 5, "secure", 6,
                                      KC_SECURITY_LEVEL_HIGH, true);

kc_keychain_type

Keychain type specifies whether the keychain is used for encryption or signing operations.

typedef enum {
    KC_KEYCHAIN_TYPE_ENCRYPT = 0,
    KC_KEYCHAIN_TYPE_SIGN = 1
} kc_keychain_type;

Values:

  • KC_KEYCHAIN_TYPE_ENCRYPT - Encryption keychain (contains encryption keys)

  • KC_KEYCHAIN_TYPE_SIGN - Signing keychain (contains signing keys)

Usage:

// Get encryption keys from a persona
kc_keychain_element_t** encryption_keys = NULL;
unsigned int key_count = 0;
int result = kc_persona_keychain(persona, &encryption_keys, &key_count,
                                KC_KEYCHAIN_TYPE_ENCRYPT);

TKCrypt Enumerations

The following enums are defined in the TKCrypt library and used throughout the Keychain API:

tkc_encryption_scheme

Public-key encryption algorithm specification.

typedef enum {
    TKC_ENCRYPTION_SCHEME_UNKNOWN = 0,
    // ECIES variants
    TKC_ENCRYPTION_SCHEME_ECIES_P256_AES_128_GCM_SHA256 = 1,
    TKC_ENCRYPTION_SCHEME_ECIES_P256_AES_256_GCM_SHA256 = 2,
    TKC_ENCRYPTION_SCHEME_ECIES_P384_AES_128_GCM_SHA384 = 3,
    TKC_ENCRYPTION_SCHEME_ECIES_P384_AES_256_GCM_SHA384 = 4,
    TKC_ENCRYPTION_SCHEME_ECIES_P521_AES_128_GCM_SHA512 = 5,
    TKC_ENCRYPTION_SCHEME_ECIES_P521_AES_256_GCM_SHA512 = 6,
    // RSA variants
    TKC_ENCRYPTION_SCHEME_RSA_1024_OAEP_SHA1 = 10,
    TKC_ENCRYPTION_SCHEME_RSA_1024_OAEP_SHA256 = 11,
    TKC_ENCRYPTION_SCHEME_RSA_2048_OAEP_SHA1 = 12,
    TKC_ENCRYPTION_SCHEME_RSA_2048_OAEP_SHA256 = 13,
    TKC_ENCRYPTION_SCHEME_RSA_3072_OAEP_SHA256 = 14,
    TKC_ENCRYPTION_SCHEME_RSA_4096_OAEP_SHA256 = 15,
    // Additional ECIES and other variants...
} tkc_encryption_scheme;

Common Values:

  • TKC_ENCRYPTION_SCHEME_ECIES_P256_AES_256_GCM_SHA256 - ECIES with P-256 curve and AES-256-GCM

  • TKC_ENCRYPTION_SCHEME_RSA_2048_OAEP_SHA256 - RSA-2048 with OAEP padding and SHA-256

  • TKC_ENCRYPTION_SCHEME_RSA_3072_OAEP_SHA256 - RSA-3072 with OAEP padding and SHA-256

tkc_signature_scheme

Public-key signing algorithm specification.

typedef enum {
    TKC_SIGNATURE_SCHEME_UNKNOWN = 0,
    // ECDSA variants
    TKC_SIGNATURE_SCHEME_ECDSA_P256_SHA256 = 1,
    TKC_SIGNATURE_SCHEME_ECDSA_P384_SHA384 = 2,
    TKC_SIGNATURE_SCHEME_ECDSA_P521_SHA512 = 3,
    // EdDSA variants
    TKC_SIGNATURE_SCHEME_EDDSA_ED25519 = 10,
    TKC_SIGNATURE_SCHEME_EDDSA_ED448 = 11,
    // RSA PSS variants
    TKC_SIGNATURE_SCHEME_RSA_2048_PSS_SHA256 = 20,
    TKC_SIGNATURE_SCHEME_RSA_3072_PSS_SHA256 = 21,
    TKC_SIGNATURE_SCHEME_RSA_4096_PSS_SHA256 = 22,
    // Additional variants...
} tkc_signature_scheme;

Common Values:

  • TKC_SIGNATURE_SCHEME_ECDSA_P256_SHA256 - ECDSA with P-256 curve and SHA-256

  • TKC_SIGNATURE_SCHEME_EDDSA_ED25519 - EdDSA with Ed25519 curve

  • TKC_SIGNATURE_SCHEME_RSA_2048_PSS_SHA256 - RSA-2048 with PSS padding and SHA-256

Usage:

// Generate signature with specific algorithm
char* signature = NULL;
unsigned int sig_size = 0;
int result = kc_gateway_generate_signature_by_private_key(
    &signature, &sig_size,
    "data to sign", 12,
    private_key_hex, key_size,
    TKC_SIGNATURE_SCHEME_ECDSA_P256_SHA256);

tkc_cipher

Symmetric cipher specification for data encryption.

typedef enum {
    TKC_CIPHER_UNKNOWN = 0,
    // AES variants
    TKC_CIPHER_AES_128_CBC = 1,
    TKC_CIPHER_AES_128_GCM = 2,
    TKC_CIPHER_AES_256_CBC = 3,
    TKC_CIPHER_AES_256_GCM = 4,
    // ChaCha20 variants
    TKC_CIPHER_CHACHA20_POLY1305 = 10,
    // 3DES variants
    TKC_CIPHER_3DES_EDE_CBC = 20,
    // Additional ciphers...
} tkc_cipher;

Common Values:

  • TKC_CIPHER_AES_256_GCM - AES-256 in GCM mode (recommended)

  • TKC_CIPHER_AES_128_GCM - AES-128 in GCM mode

  • TKC_CIPHER_CHACHA20_POLY1305 - ChaCha20-Poly1305 AEAD cipher

tkc_data_type

Data type metadata for serialized data.

typedef enum {
    TKC_DATA_TYPE_BINARY = 0,
    TKC_DATA_TYPE_UTF8_STRING = 1,
    TKC_DATA_TYPE_INT32 = 2,
    TKC_DATA_TYPE_INT64 = 3,
    TKC_DATA_TYPE_UINT32 = 4,
    TKC_DATA_TYPE_UINT64 = 5,
    TKC_DATA_TYPE_BOOLEAN = 6,
    TKC_DATA_TYPE_FLOAT32 = 7,
    TKC_DATA_TYPE_FLOAT64 = 8,
    TKC_DATA_TYPE_DID = 20,
    TKC_DATA_TYPE_VERIFIABLE_DATA = 21,
    TKC_DATA_TYPE_CREDENTIAL = 22,
    TKC_DATA_TYPE_TRANSACTION = 23,
    TKC_DATA_TYPE_ENCRYPTED_DATA = 24,
    // Additional types...
} tkc_data_type;

Common Values:

  • TKC_DATA_TYPE_UTF8_STRING - UTF-8 encoded text

  • TKC_DATA_TYPE_BINARY - Binary data

  • TKC_DATA_TYPE_VERIFIABLE_DATA - Signed/verifiable data

  • TKC_DATA_TYPE_ENCRYPTED_DATA - Encrypted data objects

Usage:

// Create serialized data with specific type
kc_serialized_data_t* data = NULL;
int result = kc_serialized_data_construct_from_string(&data,
    "Hello, world!", 13, TKC_DATA_TYPE_UTF8_STRING);

tkc_serialization_format

String serialization format for data exchange.

typedef enum {
    TKC_SERIALIZATION_FORMAT_XML = 0,
    TKC_SERIALIZATION_FORMAT_PROTOBUF = 1,
    TKC_SERIALIZATION_FORMAT_JSON = 2
} tkc_serialization_format;

Values:

  • TKC_SERIALIZATION_FORMAT_XML - XML format

  • TKC_SERIALIZATION_FORMAT_JSON - JSON format (recommended for web applications)

  • TKC_SERIALIZATION_FORMAT_PROTOBUF - Protocol Buffers format (efficient binary)

tkc_character_encoding

Character encoding specification for text data.

typedef enum {
    TKC_CHARACTER_ENCODING_UTF8 = 0,
    TKC_CHARACTER_ENCODING_UTF16 = 1,
    TKC_CHARACTER_ENCODING_BINARY = 2,
    TKC_CHARACTER_ENCODING_ASCII = 3,
    TKC_CHARACTER_ENCODING_UTF32 = 4,
    TKC_CHARACTER_ENCODING_ISO_8859_1 = 10,
    TKC_CHARACTER_ENCODING_ISO_8859_2 = 11,
    // Additional encodings...
} tkc_character_encoding;

Common Values:

  • TKC_CHARACTER_ENCODING_UTF8 - UTF-8 encoding (recommended)

  • TKC_CHARACTER_ENCODING_ASCII - ASCII encoding

  • TKC_CHARACTER_ENCODING_BINARY - Binary data (not text)

DID Lifecycle Enums

tkc_did_lifecycle_status

DID lifecycle status tracked in the database.

typedef enum {
    TKC_DID_LIFECYCLE_STATUS_UNINITIALIZED = 0,
    TKC_DID_LIFECYCLE_STATUS_KEY_PAIR_CREATED = 1,
    TKC_DID_LIFECYCLE_STATUS_ACQUIRING_RESOURCES = 2,
    TKC_DID_LIFECYCLE_STATUS_BROADCASTED = 3,
    TKC_DID_LIFECYCLE_STATUS_CONFIRMING_PKI = 4,
    TKC_DID_LIFECYCLE_STATUS_CONFIRMED = 5,
    TKC_DID_LIFECYCLE_STATUS_RENEWAL_IMMINENT = 6,
    TKC_DID_LIFECYCLE_STATUS_EXPIRED = 7
} tkc_did_lifecycle_status;

Values:

  • TKC_DID_LIFECYCLE_STATUS_UNINITIALIZED - DID not yet created

  • TKC_DID_LIFECYCLE_STATUS_KEY_PAIR_CREATED - Keys generated

  • TKC_DID_LIFECYCLE_STATUS_ACQUIRING_RESOURCES - Getting blockchain resources

  • TKC_DID_LIFECYCLE_STATUS_BROADCASTED - DID published to network

  • TKC_DID_LIFECYCLE_STATUS_CONFIRMING_PKI - Waiting for PKI confirmation

  • TKC_DID_LIFECYCLE_STATUS_CONFIRMED - DID is active and usable

  • TKC_DID_LIFECYCLE_STATUS_RENEWAL_IMMINENT - DID needs renewal soon

  • TKC_DID_LIFECYCLE_STATUS_EXPIRED - DID has expired

tkc_consensus_algorithm

Consensus algorithm used in ledger consensus protocols.

typedef enum {
    TKC_CONSENSUS_ALGORITHM_NONE = 0,
    TKC_CONSENSUS_ALGORITHM_ONE_PHASE_COMMIT = 1,
    TKC_CONSENSUS_ALGORITHM_TWO_PHASE_COMMIT = 2,
    TKC_CONSENSUS_ALGORITHM_THREE_PHASE_COMMIT = 3
} tkc_consensus_algorithm;

Values:

  • TKC_CONSENSUS_ALGORITHM_NONE - No consensus required

  • TKC_CONSENSUS_ALGORITHM_ONE_PHASE_COMMIT - Simple commit protocol

  • TKC_CONSENSUS_ALGORITHM_TWO_PHASE_COMMIT - Standard 2PC protocol

  • TKC_CONSENSUS_ALGORITHM_THREE_PHASE_COMMIT - Enhanced 3PC protocol

Example: Working with Enums

// Example function demonstrating enum usage
void demonstrate_enum_usage() {
    // Security level selection
    kc_security_level sec_level;
    bool high_security_required = true;

    if (high_security_required) {
        sec_level = KC_SECURITY_LEVEL_HIGH;
    } else {
        sec_level = KC_SECURITY_LEVEL_MEDIUM;
    }

    printf("Selected security level: %d\n", sec_level);

    // Algorithm selection based on requirements
    tkc_encryption_scheme enc_scheme;
    tkc_signature_scheme sig_scheme;

    bool need_high_performance = false;
    if (need_high_performance) {
        enc_scheme = TKC_ENCRYPTION_SCHEME_ECIES_P256_AES_256_GCM_SHA256;
        sig_scheme = TKC_SIGNATURE_SCHEME_ECDSA_P256_SHA256;
    } else {
        enc_scheme = TKC_ENCRYPTION_SCHEME_RSA_3072_OAEP_SHA256;
        sig_scheme = TKC_SIGNATURE_SCHEME_RSA_3072_PSS_SHA256;
    }

    printf("Encryption scheme: %d\n", enc_scheme);
    printf("Signature scheme: %d\n", sig_scheme);

    // Data type for serialization
    tkc_data_type data_type = TKC_DATA_TYPE_UTF8_STRING;
    tkc_serialization_format format = TKC_SERIALIZATION_FORMAT_JSON;

    printf("Data will be serialized as type %d in format %d\n", data_type, format);
}

Enum Conversion Utilities

// Example utility functions for enum handling
const char* security_level_to_string(kc_security_level level) {
    switch (level) {
        case KC_SECURITY_LEVEL_LIGHTWEIGHT: return "LIGHTWEIGHT";
        case KC_SECURITY_LEVEL_LOW: return "LOW";
        case KC_SECURITY_LEVEL_MEDIUM: return "MEDIUM";
        case KC_SECURITY_LEVEL_HIGH: return "HIGH";
        case KC_SECURITY_LEVEL_VERY_HIGH: return "VERY_HIGH";
        default: return "UNKNOWN";
    }
}

const char* keychain_type_to_string(kc_keychain_type type) {
    switch (type) {
        case KC_KEYCHAIN_TYPE_ENCRYPT: return "ENCRYPT";
        case KC_KEYCHAIN_TYPE_SIGN: return "SIGN";
        default: return "UNKNOWN";
    }
}

const char* did_status_to_string(tkc_did_lifecycle_status status) {
    switch (status) {
        case TKC_DID_LIFECYCLE_STATUS_UNINITIALIZED: return "UNINITIALIZED";
        case TKC_DID_LIFECYCLE_STATUS_KEY_PAIR_CREATED: return "KEY_PAIR_CREATED";
        case TKC_DID_LIFECYCLE_STATUS_ACQUIRING_RESOURCES: return "ACQUIRING_RESOURCES";
        case TKC_DID_LIFECYCLE_STATUS_BROADCASTED: return "BROADCASTED";
        case TKC_DID_LIFECYCLE_STATUS_CONFIRMING_PKI: return "CONFIRMING_PKI";
        case TKC_DID_LIFECYCLE_STATUS_CONFIRMED: return "CONFIRMED";
        case TKC_DID_LIFECYCLE_STATUS_RENEWAL_IMMINENT: return "RENEWAL_IMMINENT";
        case TKC_DID_LIFECYCLE_STATUS_EXPIRED: return "EXPIRED";
        default: return "UNKNOWN";
    }
}

Best Practices

  • Security Levels: Use KC_SECURITY_LEVEL_MEDIUM or higher for production systems

  • Algorithms: Prefer ECDSA/ECIES algorithms for better performance and smaller key sizes

  • Data Types: Always specify appropriate data types when creating serialized data

  • Validation: Check enum values are within valid ranges before using them

  • Documentation: Document which algorithms your application supports

See Also

Note: Additional algorithm guides are being developed.