MetaMUI Crypto Primitives - Unified API Specification

Side-channel claim limit. Nothing on this page claims constant-time behaviour or side-channel resistance for any target: the side-channel harness covers nothing (finding A48) and no measurement exists. The Rust and C cores are designed for constant time and unmeasured; managed runtimes (JIT, GC, bounds checks) make no timing claim. Where this page names constant-time or side-channel techniques, in prose or in code, they are design intent or recommendations, not measured properties.

Overview

This document defines the unified API specification for MetaMUI Crypto Primitives across all 10 supported platforms. The API design prioritizes consistency, security, and ease of use while respecting platform-specific idioms.

Supported Platforms

TypeScript/JavaScript (NPM)
Python (PyPI)
Rust (Crates.io)
Swift (SPM)
Kotlin (Maven)
WebAssembly (WASM)
C (Native Library) - NEW
C# (.NET) - NEW
Go (Go Modules) - NEW
Java (Maven) - NEW

Core API Principles

1. Consistent Naming

Function names follow platform conventions (camelCase, snake_case, PascalCase)
Behavior and parameters remain consistent across platforms
Return types are predictable and documented

2. Security First

Constant-time behaviour and side-channel resistance: not claimed — unmeasured for every target (A48)
Secure memory handling with explicit cleanup
No implicit conversions that could leak information
Clear separation between public and secret data

3. Error Handling

Explicit error types for all failure modes
No silent failures or undefined behavior
Clear error messages with actionable information

Algorithm Categories

Hash Functions

SHA2 (224, 256, 384, 512)
SHA3 (224, 256, 384, 512)
BLAKE2 (b, s)
BLAKE3
Argon2 (i, d, id)
scrypt
bcrypt

Symmetric Encryption

AES (128, 192, 256) with modes: GCM, CTR, CBC
ChaCha20-Poly1305
XChaCha20-Poly1305
Camellia (128, 192, 256)
ARIA (128, 192, 256)
Serpent-256
Twofish-256

Asymmetric Cryptography

Ed25519
X25519
secp256k1
P-256, P-384, P-521
RSA (2048, 3072, 4096)

Post-Quantum Algorithms

KPQC Algorithms: ML-KEM-768, ML-DSA-65
Additional PQC: Kyber (512, 768, 1024), Dilithium (2, 3, 5)
Signatures: Falcon-512, SPHINCS+-256
Key Exchange: NTRU, SABER, FrodoKEM

Message Authentication

HMAC (SHA256, SHA512, BLAKE2b)
Poly1305
GMAC

Key Derivation

HKDF
PBKDF2
Argon2 KDF mode

Platform-Specific API Definitions

C API (libmetamui-crypto)

// Header: metamui_crypto.h

// Initialization and cleanup
int metamui_init(void);
void metamui_cleanup(void);

// Hash functions
typedef struct metamui_hash_ctx metamui_hash_ctx;

metamui_hash_ctx* metamui_hash_init(const char* algorithm);
int metamui_hash_update(metamui_hash_ctx* ctx, const uint8_t* data, size_t len);
int metamui_hash_final(metamui_hash_ctx* ctx, uint8_t* out, size_t* out_len);
void metamui_hash_free(metamui_hash_ctx* ctx);

// One-shot hashing
int metamui_hash(const char* algorithm, 
                 const uint8_t* data, size_t data_len,
                 uint8_t* out, size_t* out_len);

// Symmetric encryption
typedef struct metamui_cipher_ctx metamui_cipher_ctx;

metamui_cipher_ctx* metamui_cipher_init(const char* algorithm,
                                        const uint8_t* key, size_t key_len,
                                        const uint8_t* nonce, size_t nonce_len);
int metamui_cipher_encrypt(metamui_cipher_ctx* ctx,
                           const uint8_t* plaintext, size_t pt_len,
                           uint8_t* ciphertext, size_t* ct_len,
                           const uint8_t* aad, size_t aad_len);
int metamui_cipher_decrypt(metamui_cipher_ctx* ctx,
                           const uint8_t* ciphertext, size_t ct_len,
                           uint8_t* plaintext, size_t* pt_len,
                           const uint8_t* aad, size_t aad_len);
void metamui_cipher_free(metamui_cipher_ctx* ctx);

// Key generation
int metamui_keygen(const char* algorithm,
                   uint8_t* private_key, size_t* priv_len,
                   uint8_t* public_key, size_t* pub_len);

// Digital signatures
int metamui_sign(const char* algorithm,
                 const uint8_t* private_key, size_t priv_len,
                 const uint8_t* message, size_t msg_len,
                 uint8_t* signature, size_t* sig_len);

int metamui_verify(const char* algorithm,
                   const uint8_t* public_key, size_t pub_len,
                   const uint8_t* message, size_t msg_len,
                   const uint8_t* signature, size_t sig_len);

// Error handling
const char* metamui_error_string(int error_code);
int metamui_get_last_error(void);

// Memory utilities
void metamui_secure_zero(void* ptr, size_t len);

C# API (MetaMUI.Crypto)

namespace MetaMUI.Crypto
{
    // Hash functions
    public static class Hash
    {
        public static byte[] Compute(HashAlgorithm algorithm, byte[] data);
        public static byte[] Compute(HashAlgorithm algorithm, Stream stream);
        
        public static IHasher Create(HashAlgorithm algorithm);
    }
    
    public interface IHasher : IDisposable
    {
        void Update(byte[] data);
        void Update(byte[] data, int offset, int count);
        byte[] Final();
        void Reset();
    }
    
    // Symmetric encryption
    public static class Cipher
    {
        public static byte[] Encrypt(CipherAlgorithm algorithm, byte[] key, byte[] nonce, 
                                     byte[] plaintext, byte[] aad = null);
        public static byte[] Decrypt(CipherAlgorithm algorithm, byte[] key, byte[] nonce,
                                     byte[] ciphertext, byte[] aad = null);
        
        public static ICipher Create(CipherAlgorithm algorithm, byte[] key, byte[] nonce);
    }
    
    public interface ICipher : IDisposable
    {
        byte[] Encrypt(byte[] plaintext, byte[] aad = null);
        byte[] Decrypt(byte[] ciphertext, byte[] aad = null);
        void EncryptInPlace(byte[] buffer, int offset, int length, byte[] aad = null);
        void DecryptInPlace(byte[] buffer, int offset, int length, byte[] aad = null);
    }
    
    // Asymmetric cryptography
    public static class AsymmetricCrypto
    {
        public static KeyPair GenerateKeyPair(AsymmetricAlgorithm algorithm);
        
        public static byte[] Sign(AsymmetricAlgorithm algorithm, byte[] privateKey, byte[] message);
        public static bool Verify(AsymmetricAlgorithm algorithm, byte[] publicKey, 
                                  byte[] message, byte[] signature);
        
        public static byte[] Encrypt(AsymmetricAlgorithm algorithm, byte[] publicKey, byte[] plaintext);
        public static byte[] Decrypt(AsymmetricAlgorithm algorithm, byte[] privateKey, byte[] ciphertext);
    }
    
    public class KeyPair
    {
        public byte[] PrivateKey { get; }
        public byte[] PublicKey { get; }
        public AsymmetricAlgorithm Algorithm { get; }
        
        public void Dispose();
    }
    
    // Post-Quantum cryptography
    public static class PostQuantum
    {
        // KEM (Key Encapsulation Mechanism)
        public static class KEM
        {
            public static KEMKeyPair GenerateKeyPair(KEMAlgorithm algorithm);
            public static (byte[] ciphertext, byte[] sharedSecret) Encapsulate(
                KEMAlgorithm algorithm, byte[] publicKey);
            public static byte[] Decapsulate(KEMAlgorithm algorithm, byte[] privateKey, 
                                            byte[] ciphertext);
        }
        
        // Digital signatures
        public static class Signatures
        {
            public static PQCKeyPair GenerateKeyPair(PQCSignatureAlgorithm algorithm);
            public static byte[] Sign(PQCSignatureAlgorithm algorithm, byte[] privateKey, 
                                     byte[] message);
            public static bool Verify(PQCSignatureAlgorithm algorithm, byte[] publicKey,
                                     byte[] message, byte[] signature);
        }
    }
    
    // Key derivation
    public static class KeyDerivation
    {
        public static byte[] HKDF(HashAlgorithm hash, byte[] ikm, byte[] salt, 
                                  byte[] info, int length);
        public static byte[] PBKDF2(HashAlgorithm hash, byte[] password, byte[] salt,
                                   int iterations, int length);
        public static byte[] Argon2(Argon2Type type, byte[] password, byte[] salt,
                                   Argon2Parameters parameters);
    }
    
    // Secure memory
    public static class SecureMemory
    {
        public static void Zero(byte[] buffer);
        public static void Zero(byte[] buffer, int offset, int count);
        public static SecureBuffer Allocate(int size);
    }
    
    public sealed class SecureBuffer : IDisposable
    {
        public byte[] Data { get; }
        public int Length { get; }
        public void Dispose();
    }
}

Go API

package metamui

import (
    "errors"
    "io"
)

// Hash functions
type Hash interface {
    Write(p []byte) (n int, err error)
    Sum(b []byte) []byte
    Reset()
    Size() int
    BlockSize() int
}

func NewHash(algorithm HashAlgorithm) (Hash, error)
func ComputeHash(algorithm HashAlgorithm, data []byte) ([]byte, error)

// Symmetric encryption
type Cipher interface {
    Encrypt(plaintext, aad []byte) ([]byte, error)
    Decrypt(ciphertext, aad []byte) ([]byte, error)
    NonceSize() int
    KeySize() int
}

func NewCipher(algorithm CipherAlgorithm, key, nonce []byte) (Cipher, error)
func Encrypt(algorithm CipherAlgorithm, key, nonce, plaintext, aad []byte) ([]byte, error)
func Decrypt(algorithm CipherAlgorithm, key, nonce, ciphertext, aad []byte) ([]byte, error)

// Asymmetric cryptography
type KeyPair struct {
    PrivateKey []byte
    PublicKey  []byte
    Algorithm  AsymmetricAlgorithm
}

func GenerateKeyPair(algorithm AsymmetricAlgorithm) (*KeyPair, error)
func Sign(algorithm AsymmetricAlgorithm, privateKey, message []byte) ([]byte, error)
func Verify(algorithm AsymmetricAlgorithm, publicKey, message, signature []byte) (bool, error)

// Post-Quantum KEM
type KEMKeyPair struct {
    PrivateKey []byte
    PublicKey  []byte
    Algorithm  KEMAlgorithm
}

func GenerateKEMKeyPair(algorithm KEMAlgorithm) (*KEMKeyPair, error)
func Encapsulate(algorithm KEMAlgorithm, publicKey []byte) (ciphertext, sharedSecret []byte, err error)
func Decapsulate(algorithm KEMAlgorithm, privateKey, ciphertext []byte) ([]byte, error)

// Post-Quantum signatures
type PQCKeyPair struct {
    PrivateKey []byte
    PublicKey  []byte
    Algorithm  PQCSignatureAlgorithm
}

func GeneratePQCKeyPair(algorithm PQCSignatureAlgorithm) (*PQCKeyPair, error)
func SignPQC(algorithm PQCSignatureAlgorithm, privateKey, message []byte) ([]byte, error)
func VerifyPQC(algorithm PQCSignatureAlgorithm, publicKey, message, signature []byte) (bool, error)

// Key derivation
func HKDF(hash HashAlgorithm, ikm, salt, info []byte, length int) ([]byte, error)
func PBKDF2(hash HashAlgorithm, password, salt []byte, iterations, length int) ([]byte, error)
func Argon2(argonType Argon2Type, password, salt []byte, params *Argon2Parameters) ([]byte, error)

// MAC
type MAC interface {
    Write(p []byte) (n int, err error)
    Sum(b []byte) []byte
    Reset()
    Size() int
}

func NewMAC(algorithm MACAlgorithm, key []byte) (MAC, error)
func ComputeMAC(algorithm MACAlgorithm, key, message []byte) ([]byte, error)

// Secure memory
func SecureZero(b []byte)

// Algorithm enums
type HashAlgorithm int
type CipherAlgorithm int
type AsymmetricAlgorithm int
type KEMAlgorithm int
type PQCSignatureAlgorithm int
type MACAlgorithm int
type Argon2Type int

const (
    SHA256 HashAlgorithm = iota
    SHA512
    SHA3_256
    SHA3_512
    BLAKE2b
    BLAKE2s
    BLAKE3
    // ... other algorithms
)

// Error types
var (
    ErrInvalidAlgorithm = errors.New("invalid algorithm")
    ErrInvalidKey       = errors.New("invalid key")
    ErrInvalidNonce     = errors.New("invalid nonce")
    ErrDecryptionFailed = errors.New("decryption failed")
    ErrVerificationFailed = errors.New("verification failed")
)

Java API

package id.metamui.crypto;

import java.security.SecureRandom;
import java.util.Arrays;

// Core interfaces
public interface Disposable extends AutoCloseable {
    void dispose();
    @Override
    default void close() { dispose(); }
}

// Hash functions
public class Hash {
    public enum Algorithm {
        SHA256, SHA512, SHA3_256, SHA3_512,
        BLAKE2B, BLAKE2S, BLAKE3,
        ARGON2I, ARGON2D, ARGON2ID,
        SCRYPT, BCRYPT
    }
    
    public static byte[] compute(Algorithm algorithm, byte[] data) throws CryptoException;
    public static Hasher create(Algorithm algorithm) throws CryptoException;
    
    public interface Hasher extends Disposable {
        void update(byte[] data);
        void update(byte[] data, int offset, int length);
        byte[] finalizeHash();
        void reset();
    }
}

// Symmetric encryption
public class Cipher {
    public enum Algorithm {
        AES_128_GCM, AES_192_GCM, AES_256_GCM,
        AES_128_CTR, AES_192_CTR, AES_256_CTR,
        CHACHA20_POLY1305, XCHACHA20_POLY1305,
        CAMELLIA_128_GCM, CAMELLIA_192_GCM, CAMELLIA_256_GCM,
        ARIA_128_GCM, ARIA_192_GCM, ARIA_256_GCM,
        SERPENT_256_GCM, TWOFISH_256_GCM
    }
    
    public static byte[] encrypt(Algorithm algorithm, byte[] key, byte[] nonce,
                                 byte[] plaintext, byte[] aad) throws CryptoException;
    
    public static byte[] decrypt(Algorithm algorithm, byte[] key, byte[] nonce,
                                 byte[] ciphertext, byte[] aad) throws CryptoException;
    
    public static CipherInstance create(Algorithm algorithm, byte[] key, byte[] nonce) 
            throws CryptoException;
    
    public interface CipherInstance extends Disposable {
        byte[] encrypt(byte[] plaintext, byte[] aad) throws CryptoException;
        byte[] decrypt(byte[] ciphertext, byte[] aad) throws CryptoException;
        void encryptInPlace(byte[] buffer, int offset, int length, byte[] aad) 
                throws CryptoException;
        void decryptInPlace(byte[] buffer, int offset, int length, byte[] aad)
                throws CryptoException;
    }
}

// Asymmetric cryptography
public class AsymmetricCrypto {
    public enum Algorithm {
        ED25519, X25519, SECP256K1,
        P256, P384, P521,
        RSA2048, RSA3072, RSA4096
    }
    
    public static class KeyPair implements Disposable {
        private final byte[] privateKey;
        private final byte[] publicKey;
        private final Algorithm algorithm;
        
        public byte[] getPrivateKey() { return Arrays.copyOf(privateKey, privateKey.length); }
        public byte[] getPublicKey() { return Arrays.copyOf(publicKey, publicKey.length); }
        public Algorithm getAlgorithm() { return algorithm; }
        
        @Override
        public void dispose() {
            SecureMemory.zero(privateKey);
        }
    }
    
    public static KeyPair generateKeyPair(Algorithm algorithm) throws CryptoException;
    
    public static byte[] sign(Algorithm algorithm, byte[] privateKey, byte[] message)
            throws CryptoException;
    
    public static boolean verify(Algorithm algorithm, byte[] publicKey, 
                                 byte[] message, byte[] signature) throws CryptoException;
}

// Post-Quantum cryptography
public class PostQuantum {
    
    public static class KEM {
        public enum Algorithm {
            ML_KEM_768, KYBER_512, KYBER_768, KYBER_1024,
            NTRU, SABER, FRODOKEM
        }
        
        public static class KeyPair implements Disposable {
            private final byte[] privateKey;
            private final byte[] publicKey;
            private final Algorithm algorithm;
            
            // getters and dispose similar to AsymmetricCrypto.KeyPair
        }
        
        public static class EncapsulationResult {
            public final byte[] ciphertext;
            public final byte[] sharedSecret;
            
            public EncapsulationResult(byte[] ciphertext, byte[] sharedSecret) {
                this.ciphertext = ciphertext;
                this.sharedSecret = sharedSecret;
            }
        }
        
        public static KeyPair generateKeyPair(Algorithm algorithm) throws CryptoException;
        
        public static EncapsulationResult encapsulate(Algorithm algorithm, byte[] publicKey)
                throws CryptoException;
        
        public static byte[] decapsulate(Algorithm algorithm, byte[] privateKey, 
                                        byte[] ciphertext) throws CryptoException;
    }
    
    public static class Signatures {
        public enum Algorithm {
            ML_DSA_65, DILITHIUM_2, DILITHIUM_3, DILITHIUM_5,
            FALCON_512, SPHINCS_PLUS_256
        }
        
        public static class KeyPair implements Disposable {
            // Similar to KEM.KeyPair
        }
        
        public static KeyPair generateKeyPair(Algorithm algorithm) throws CryptoException;
        
        public static byte[] sign(Algorithm algorithm, byte[] privateKey, byte[] message)
                throws CryptoException;
        
        public static boolean verify(Algorithm algorithm, byte[] publicKey,
                                     byte[] message, byte[] signature) throws CryptoException;
    }
}

// Key derivation
public class KeyDerivation {
    
    public static byte[] hkdf(Hash.Algorithm hash, byte[] ikm, byte[] salt,
                              byte[] info, int length) throws CryptoException;
    
    public static byte[] pbkdf2(Hash.Algorithm hash, byte[] password, byte[] salt,
                                int iterations, int length) throws CryptoException;
    
    public enum Argon2Type {
        ARGON2I, ARGON2D, ARGON2ID
    }
    
    public static class Argon2Parameters {
        public final int memory;      // in KiB
        public final int iterations;
        public final int parallelism;
        public final int outputLength;
        
        public Argon2Parameters(int memory, int iterations, int parallelism, int outputLength) {
            this.memory = memory;
            this.iterations = iterations;
            this.parallelism = parallelism;
            this.outputLength = outputLength;
        }
    }
    
    public static byte[] argon2(Argon2Type type, byte[] password, byte[] salt,
                                Argon2Parameters params) throws CryptoException;
}

// MAC
public class MAC {
    public enum Algorithm {
        HMAC_SHA256, HMAC_SHA512, HMAC_BLAKE2B,
        POLY1305, GMAC
    }
    
    public static byte[] compute(Algorithm algorithm, byte[] key, byte[] message)
            throws CryptoException;
    
    public static MACInstance create(Algorithm algorithm, byte[] key) throws CryptoException;
    
    public interface MACInstance extends Disposable {
        void update(byte[] data);
        void update(byte[] data, int offset, int length);
        byte[] finalizeMAC();
        void reset();
    }
}

// Secure memory management
public class SecureMemory {
    public static void zero(byte[] buffer);
    public static void zero(byte[] buffer, int offset, int length);
    
    public static class SecureBuffer implements Disposable {
        private final byte[] data;
        
        public SecureBuffer(int size) {
            this.data = new byte[size];
        }
        
        public byte[] getData() { return data; }
        public int getLength() { return data.length; }
        
        @Override
        public void dispose() {
            zero(data);
        }
    }
}

// Exception handling
public class CryptoException extends Exception {
    public enum ErrorCode {
        INVALID_ALGORITHM,
        INVALID_KEY,
        INVALID_NONCE,
        INVALID_INPUT,
        DECRYPTION_FAILED,
        VERIFICATION_FAILED,
        INSUFFICIENT_MEMORY,
        OPERATION_FAILED
    }
    
    private final ErrorCode errorCode;
    
    public CryptoException(ErrorCode errorCode, String message) {
        super(message);
        this.errorCode = errorCode;
    }
    
    public CryptoException(ErrorCode errorCode, String message, Throwable cause) {
        super(message, cause);
        this.errorCode = errorCode;
    }
    
    public ErrorCode getErrorCode() { return errorCode; }
}

Cross-Platform Compatibility

Data Format Standards

All binary data uses big-endian byte ordering
Keys and signatures use standard formats (e.g., Ed25519 32-byte private key)
Encrypted data includes version byte for future compatibility
All strings are UTF-8 encoded

Test Vector Compatibility

Shared test vectors across all platforms
Automated cross-platform testing in CI/CD
Compatibility matrix maintained for each release

Version Management

Semantic versioning across all platforms
Synchronized releases for major versions
Backward compatibility for at least 2 major versions

Security Considerations

Memory Management

Explicit cleanup of sensitive data
Use of secure allocators where available
Protection against timing attacks
Stack clearing after cryptographic operations

Error Handling

No information leakage through error messages
Consistent error codes across platforms
Fail-fast approach for invalid inputs

Platform Security Features

Use of platform-specific security features (e.g., Keychain on iOS, Windows CNG)
Hardware acceleration where available
Secure random number generation using OS primitives

Performance Guidelines

Optimization Priorities

Correctness and security
API consistency
Performance optimization
Memory efficiency

Benchmarking

Standard benchmark suite across platforms
Performance regression testing
Platform-specific optimizations documented

Documentation Requirements

API Documentation

Complete documentation for every public function
Usage examples for common scenarios
Security warnings and best practices
Migration guides between versions

Platform-Specific Guides

Installation instructions
Build requirements
Platform-specific considerations
Integration examples

Licensing and Distribution

Package Distribution

Individual algorithm packages
Suite packages (PQC, KPQC, Recommended)
Installers with license validation
No public repository publication

License Enforcement

License key validation at runtime
Offline license verification support
License server integration
Usage telemetry (optional, with consent)

Implementation Timeline

Phase 1: Foundation (Months 1-3)

Core API implementation for Java
Basic test suite
Documentation framework

Phase 2: Expansion (Months 4-6)

C# and Go implementations
Cross-platform testing
Performance optimization

Phase 3: Completion (Months 7-9)

C library implementation
Hardware acceleration
Security audit

Phase 4: Polish (Months 10-12)

Documentation completion
Commercial features
Launch preparation

Conclusion

This unified API specification describes consistent cryptographic operations across all supported platforms while maintaining platform-specific idioms and best practices.