C Platform Guide

Overview

The MetaMUI Crypto C library provides a pure C implementation of cryptographic algorithms. Build from source with make or CMake.

Installation

Build from source:

cd metamui-crypto-c
make

Or with CMake:

cd metamui-crypto-c
mkdir build && cd build
cmake ..
make

Running Tests

cd metamui-crypto-c
make test

Using in Your Project

After building, link against the library:

# Compile with shared library
gcc -o myapp main.c -I../metamui-crypto-c/include -L../metamui-crypto-c/lib -lmetamui-crypto

# Compile with static library
gcc -o myapp main.c -I../metamui-crypto-c/include ../metamui-crypto-c/lib/libmetamui-crypto.a

CMake Integration

# CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(MyProject)

# Add MetaMUI Crypto as a subdirectory
add_subdirectory(../metamui-crypto-c metamui-crypto-c)

add_executable(myapp main.c)
target_link_libraries(myapp metamui-crypto)

Usage Examples

Basic Hashing

#include <metamui/crypto.h>
#include <stdio.h>

int main() {
    // Initialize library
    metamui_crypto_init();

    // BLAKE3 hashing
    uint8_t data[] = "Hello, World!";
    uint8_t hash[32];

    metamui_blake3_hash(data, sizeof(data) - 1, hash, 32);

    printf("BLAKE3 Hash: ");
    for (int i = 0; i < 32; i++) {
        printf("%02x", hash[i]);
    }
    printf("\n");

    // Cleanup
    metamui_crypto_cleanup();
    return 0;
}

Post-Quantum Key Exchange (ML-KEM-768)

#include <metamui/algorithms/mlkem768.h>
#include <metamui/random.h>

int main() {
    metamui_crypto_init();

    // Generate keypair
    mlkem768_public_key pk;
    mlkem768_secret_key sk;
    mlkem768_keypair(&pk, &sk);

    // Encapsulation (sender)
    mlkem768_ciphertext ct;
    uint8_t shared_secret_sender[32];
    mlkem768_encapsulate(&ct, shared_secret_sender, &pk);

    // Decapsulation (receiver)
    uint8_t shared_secret_receiver[32];
    mlkem768_decapsulate(shared_secret_receiver, &ct, &sk);

    // Shared secrets now match
    // Use for symmetric encryption

    // Secure cleanup
    metamui_secure_zero(&sk, sizeof(sk));
    metamui_crypto_cleanup();
    return 0;
}

Authenticated Encryption (ChaCha20-Poly1305)

#include <metamui/algorithms/chacha20poly1305.h>

int main() {
    metamui_crypto_init();

    uint8_t key[32];
    uint8_t nonce[12];
    uint8_t plaintext[] = "Secret message";
    uint8_t ciphertext[sizeof(plaintext)];
    uint8_t tag[16];

    // Generate random key and nonce
    metamui_random_bytes(key, 32);
    metamui_random_bytes(nonce, 12);

    // Encrypt
    chacha20poly1305_encrypt(
        ciphertext, tag,
        plaintext, sizeof(plaintext),
        NULL, 0,  // No additional data
        nonce, key
    );

    // Decrypt
    uint8_t decrypted[sizeof(plaintext)];
    int result = chacha20poly1305_decrypt(
        decrypted,
        ciphertext, sizeof(ciphertext),
        tag,
        NULL, 0,
        nonce, key
    );

    if (result == 0) {
        printf("Decryption successful\n");
    }

    metamui_crypto_cleanup();
    return 0;
}

Memory Management

Secure Memory Handling

// Allocate secure memory
void* secure_mem = metamui_secure_alloc(1024);

// Use memory...

// Secure cleanup (overwrites with zeros)
metamui_secure_free(secure_mem, 1024);

// Zero sensitive stack variables
uint8_t secret_key[32];
// ... use secret_key ...
metamui_secure_zero(secret_key, sizeof(secret_key));

Memory Requirements

Algorithm Type Stack Usage Heap Usage
Hash Functions ~1 KB None
Symmetric Crypto ~2 KB None
ML-KEM-768 ~12 KB Optional
Dilithium3 ~60 KB Optional
Falcon-512 ~40 KB Required

Error Handling

// All functions return error codes
int result = metamui_blake3_hash(data, len, hash, hash_len);
if (result != METAMUI_SUCCESS) {
    switch (result) {
        case METAMUI_ERR_NULL_PTR:
            fprintf(stderr, "Null pointer error\n");
            break;
        case METAMUI_ERR_INVALID_LENGTH:
            fprintf(stderr, "Invalid length\n");
            break;
        // Handle other errors...
    }
}

Performance Optimization

Compiler Flags

# Optimize for speed
gcc -O3 -march=native -o myapp main.c -lmetamui-crypto

# Optimize for size
gcc -Os -o myapp main.c -lmetamui-crypto

# Enable AVX2/AVX512 (if supported)
gcc -O3 -mavx2 -o myapp main.c -lmetamui-crypto

Hardware Acceleration

// Check for hardware acceleration
if (metamui_has_hardware_aes()) {
    // Use hardware-accelerated AES
    metamui_aes256_hw_encrypt(plaintext, ciphertext, key);
} else {
    // Fall back to software implementation
    metamui_aes256_encrypt(plaintext, ciphertext, key);
}

Platform Support

Platform Architecture Minimum Version
Linux x86_64, ARM64 glibc 2.17+
macOS x86_64, Apple Silicon 10.15+
Windows x64 Windows 10
FreeBSD x86_64, ARM64 12.0+

Support

Platform Guides C# Guide