Your First Keychain App

This quickstart guide will have you encrypting, decrypting, and signing data securely using a single cryptographic identity that work immediately without network dependencies or PKI maturation delays.

Prerequisites

Keychain Core installed
Basic programming knowledge

What You’ll Learn

Initialize the Keychain Gateway
Create your first persona (digital identity)
Encrypt and decrypt data for secure storage
Sign and verify documents for integrity

Step 1: Initialize Keychain

Every Keychain application starts by initializing the Gateway, which manages all cryptographic operations.

Python
C++
C

from keychain_python import Gateway, SecurityLevel

# Initialize with default configuration
settings = Gateway.init("~/.keychain/config/keychain.json")
gateway = Gateway(settings)

print("Keychain Gateway initialized")

#include "keychain/gateway/gateway.hpp"

namespace kc = keychain;

int main() {
    // Initialize with default configuration
    kc::settings settings;
    auto result = kc::gateway::init(settings, "~/.keychain/config/keychain.json");

    if (result != kc::code::success) {
        std::cerr << "Failed to initialize gateway" << std::endl;
        return 1;
    }

    kc::gateway gateway(settings);
    std::cout << "Keychain Gateway initialized" << std::endl;

    return 0;
}

#include "keychain/gateway/gateway.h"

int main() {
    kc_settings_t* settings = NULL;
    kc_gateway_t* gateway = NULL;

    // Initialize with default configuration
    const char* config_path = "~/.keychain/config/keychain.json";
    if (kc_gateway_init(&settings, config_path, strlen(config_path)) != KC_SUCCESS) {
        fprintf(stderr, "Failed to initialize gateway settings\n");
        return 1;
    }

    if (kc_gateway_construct(&gateway, settings) != KC_SUCCESS) {
        fprintf(stderr, "Failed to construct gateway\n");
        return 1;
    }

    printf("Keychain Gateway initialized\n");

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

    return 0;
}

Step 2: Create Your First Persona

A persona is your digital identity - think of it as a secure, user account with its own cryptographic keys. Creating a persona creates a private/public keypair stored locally and initiates broadcasting of your public keys to the network.

Python
C++
C

# Create a persona with medium security level
my_persona = gateway.create_persona("MyName", "quickstart", SecurityLevel.MEDIUM)

print(f"Created persona: {my_persona.name}")
print(f"Security level: {my_persona.security_level}")

// Create a persona with medium security level
auto my_persona = gateway.create_persona("MyName", "quickstart", kc::security_level::medium);

std::cout << "Created persona: " << my_persona.name() << std::endl;
std::cout << "Security level: medium" << std::endl;

kc_persona_t* my_persona = NULL;

// Create a persona with medium security level
if (kc_gateway_create_persona(gateway, &my_persona, "MyName", 6, "quickstart", 10,
                             KC_SECURITY_LEVEL_MEDIUM, true) != KC_SUCCESS) {
    fprintf(stderr, "Failed to create persona\n");
    return 1;
}

printf("Created persona: MyName\n");
printf("Persona created successfully\n");
printf("Security level: medium\n");

// Remember to clean up
kc_persona_destruct(&my_persona);

Step 3: Encrypt Data for Secure Storage

Now let’s encrypt some data using your persona’s keys. This encrypts data for secure storage or transmission.

Python
C++
C

from keychain_python import SerializedData

# Create some data to encrypt
secret_data = "This is my confidential information!"
data = SerializedData(secret_data)

# Encrypt for secure storage (self-encryption)
encrypted = my_persona.encrypt(data, [])  # Empty recipients = encrypt for self

print("Original data:", secret_data)
print("Data encrypted successfully")
print(f"Encrypted data type: {encrypted.data_type()}")
print("Ready for secure storage!")

// Create some data to encrypt
std::string secret_data = "This is my confidential information!";
kc::serialized_data data(secret_data);

// Encrypt for secure storage (self-encryption)
std::vector<kc::contact> recipients;  // Empty = encrypt for self
auto encrypted = my_persona.encrypt(data, recipients);

std::cout << "Original data: " << secret_data << std::endl;
std::cout << "Data encrypted successfully" << std::endl;
std::cout << "Encrypted data ready" << std::endl;
std::cout << "Ready for secure storage!" << std::endl;

kc_serialized_data_t* data = NULL;
kc_encrypted_data_t* encrypted = NULL;

// Create some data to encrypt
const char* secret_data = "This is my confidential information!";
if (kc_serialized_data_construct_from_utf8(&data, secret_data, strlen(secret_data)) != KC_SUCCESS) {
    fprintf(stderr, "Failed to create data\n");
    return 1;
}

// Encrypt for secure storage (self-encryption)
if (kc_gateway_encrypt(gateway, &encrypted, my_persona, data, NULL, 0) != KC_SUCCESS) {
    fprintf(stderr, "Failed to encrypt data\n");
    return 1;
}

printf("Original data: %s\n", secret_data);
printf("Data encrypted successfully\n");
printf("Encrypted data ready\n");
printf("Ready for secure storage!\n");

// Cleanup
kc_serialized_data_destruct(&data);

Step 4: Decrypt Your Data

Now let’s decrypt the data to verify the encryption worked correctly.

Python
C++
C

# Decrypt the data
decrypted = my_persona.decrypt(encrypted)
recovered_data = decrypted.utf8_string()

print("Decrypted data:", recovered_data)
print("Success! Original and decrypted data match:",
      secret_data == recovered_data)

// Decrypt the data
auto decrypted = my_persona.decrypt(encrypted);
std::string recovered_data = decrypted.utf8_string();

std::cout << "Decrypted data: " << recovered_data << std::endl;
std::cout << "Success! Original and decrypted data match: "
          << (secret_data == recovered_data ? "true" : "false") << std::endl;

kc_serialized_data_t* decrypted = NULL;

// Decrypt the data
if (kc_gateway_decrypt(gateway, &decrypted, my_persona, encrypted) != KC_SUCCESS) {
    fprintf(stderr, "Failed to decrypt data\n");
    return 1;
}

char* recovered_data = kc_serialized_data_utf8_string(decrypted);
printf("Decrypted data: %s\n", recovered_data);
printf("Success! Data match: %s\n",
       strcmp(secret_data, recovered_data) == 0 ? "true" : "false");

// Cleanup
free(recovered_data);
kc_serialized_data_destruct(&decrypted);
kc_encrypted_data_destruct(&encrypted);

Step 5: Sign and Verify a Document

Finally, let’s demonstrate digital signing for data integrity verification.

Python
C++
C

# Create a document to sign
document = "Important contract v1.0"
doc_data = SerializedData(document)

# Sign the document
signed_doc = my_persona.sign(doc_data, True)  # True = approval signature

print("Document signed:", document)

# Verify the signature
is_valid = gateway.verify(signed_doc)
verified_content = signed_doc.utf8_string()

print("Signature verification:", "VALID" if is_valid else "INVALID")
print("Verified content:", verified_content)

# Cleanup
Gateway.close()

// Create a document to sign
std::string document = "Important contract v1.0";
kc::serialized_data doc_data(document);

// Sign the document
auto signed_doc = my_persona.sign(doc_data, true);  // true = approval signature

std::cout << "Document signed: " << document << std::endl;

// Verify the signature
bool is_valid = gateway.verify(signed_doc);
std::string verified_content = signed_doc.utf8_string();

std::cout << "Signature verification: " << (is_valid ? "VALID" : "INVALID") << std::endl;
std::cout << "Verified content: " << verified_content << std::endl;

// Cleanup
kc::gateway::close();

kc_serialized_data_t* doc_data = NULL;
kc_verifiable_data_t* signed_doc = NULL;

// Create a document to sign
const char* document = "Important contract v1.0";
if (kc_serialized_data_construct_from_utf8(&doc_data, document, strlen(document)) != KC_SUCCESS) {
    fprintf(stderr, "Failed to create document data\n");
    return 1;
}

// Sign the document
if (kc_gateway_sign(gateway, &signed_doc, my_persona, doc_data, true, NULL, 0, NULL, 0) != KC_SUCCESS) {
    fprintf(stderr, "Failed to sign document\n");
    return 1;
}

printf("Document signed: %s\n", document);

// Verify the signature
bool is_valid = (kc_gateway_verify(gateway, signed_doc) == KC_SUCCESS);
char* verified_content = kc_verifiable_data_utf8_string(signed_doc);

printf("Signature verification: %s\n", is_valid ? "VALID" : "INVALID");
printf("Verified content: %s\n", verified_content);

// Final cleanup
free(verified_content);
kc_verifiable_data_destruct(&signed_doc);
kc_serialized_data_destruct(&doc_data);
kc_gateway_close();

Complete Example

Here’s the complete working example that demonstrates both encryption and signing:

Python
C++

#!/usr/bin/env python3
from keychain_python import Gateway, SecurityLevel, SerializedData

def main():
    # Step 1: Initialize
    settings = Gateway.init("~/.keychain/config/keychain.json")
    gateway = Gateway(settings)

    # Step 2: Create persona
    my_persona = gateway.create_persona("MyName", "quickstart", SecurityLevel.MEDIUM)

    # Step 3-4: Encrypt and decrypt
    secret_data = "This is my confidential information!"
    data = SerializedData(secret_data)
    encrypted = my_persona.encrypt(data, [])  # Self-encryption
    decrypted = my_persona.decrypt(encrypted)
    recovered_data = decrypted.utf8_string()

    # Step 5: Sign and verify
    document = "Important contract v1.0"
    doc_data = SerializedData(document)
    signed_doc = my_persona.sign(doc_data, True)
    is_valid = gateway.verify(signed_doc)
    verified_content = signed_doc.utf8_string()

    # Results
    print(f"Original data: {secret_data}")
    print(f"Decrypted data: {recovered_data}")
    print(f"Encryption match: {secret_data == recovered_data}")
    print(f"Signed document: {document}")
    print(f"Signature valid: {is_valid}")
    print(f"Verified content: {verified_content}")

    Gateway.close()

if __name__ == "__main__":
    main()

#include <iostream>
#include <vector>
#include "keychain/gateway/gateway.hpp"

namespace kc = keychain;

int main() {
    try {
        // Step 1: Initialize
        kc::settings settings;
        kc::gateway::init(settings, "~/.keychain/config/keychain.json");
        kc::gateway gateway(settings);

        // Step 2: Create persona
        auto my_persona = gateway.create_persona("MyName", "quickstart", kc::security_level::medium);

        // Step 3-4: Encrypt and decrypt
        std::string secret_data = "This is my confidential information!";
        kc::serialized_data data(secret_data);
        auto encrypted = my_persona.encrypt(data, {});  // Self-encryption
        auto decrypted = my_persona.decrypt(encrypted);
        std::string recovered_data = decrypted.utf8_string();

        // Step 5: Sign and verify
        std::string document = "Important contract v1.0";
        kc::serialized_data doc_data(document);
        auto signed_doc = my_persona.sign(doc_data, true);
        bool is_valid = gateway.verify(signed_doc);
        std::string verified_content = signed_doc.utf8_string();

        // Results
        std::cout << "Original data: " << secret_data << std::endl;
        std::cout << "Decrypted data: " << recovered_data << std::endl;
        std::cout << "Encryption match: " << (secret_data == recovered_data) << std::endl;
        std::cout << "Signed document: " << document << std::endl;
        std::cout << "Signature valid: " << is_valid << std::endl;
        std::cout << "Verified content: " << verified_content << std::endl;

        kc::gateway::close();
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
    return 0;
}

What’s Next?

Congratulations! You’ve successfully:

Initialized the Keychain Gateway
Created a digital identity (persona)
Encrypted data using secure keys
Decrypted data successfully

Continue Learning

Basic Encryption Patterns (coming soon) - Learn different encryption scenarios
Key Management (coming soon) - Understand security levels and key rotation
Managing Multiple Personas (coming soon) - Work with multiple identities
Secure Messaging (coming soon) - Encrypt messages between different personas

Key Concepts Learned

Concept	Description
Gateway	Central coordinator for all cryptographic operations and configuration management
Persona	Hardware-secured digital identity with its own keychain and cryptographic capabilities
SerializedData	Type-safe container for data with metadata about content type and encoding
Hardware Security	Private keys are generated and stored in secure hardware, never exposed in software

Concept

Description

Gateway

Central coordinator for all cryptographic operations and configuration management

Persona

Hardware-secured digital identity with its own keychain and cryptographic capabilities

SerializedData

Type-safe container for data with metadata about content type and encoding

Hardware Security

Private keys are generated and stored in secure hardware, never exposed in software

Security Notes

Your keys are secure: Private keys never leave the secure hardware enclave

Zero-knowledge: Even with access to your encrypted data, attackers cannot decrypt without your persona

Perfect forward secrecy: Each encryption operation uses fresh cryptographic material

Audit trail: All operations are logged for compliance and debugging