{"id":36985656,"url":"https://github.com/cachekit-io/cachekit-core","last_synced_at":"2026-01-13T23:03:01.873Z","repository":{"id":327728871,"uuid":"1107963755","full_name":"cachekit-io/cachekit-core","owner":"cachekit-io","description":"LZ4 compression, xxHash3 integrity, AES-256-GCM encryption for byte payloads","archived":false,"fork":false,"pushed_at":"2025-12-18T01:59:42.000Z","size":157,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T19:44:38.883Z","etag":null,"topics":["aes-gcm","compression","cryptography","encryption","lz4","rust"],"latest_commit_sha":null,"homepage":"https://docs.rs/cachekit-core","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cachekit-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-01T21:00:06.000Z","updated_at":"2026-01-10T02:56:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cachekit-io/cachekit-core","commit_stats":null,"previous_names":["cachekit-io/cachekit-core"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cachekit-io/cachekit-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cachekit-io%2Fcachekit-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cachekit-io%2Fcachekit-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cachekit-io%2Fcachekit-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cachekit-io%2Fcachekit-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cachekit-io","download_url":"https://codeload.github.com/cachekit-io/cachekit-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cachekit-io%2Fcachekit-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28405148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aes-gcm","compression","cryptography","encryption","lz4","rust"],"created_at":"2026-01-13T23:02:59.754Z","updated_at":"2026-01-13T23:03:01.868Z","avatar_url":"https://github.com/cachekit-io.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cachekit-core\n\n\u003cdiv align=\"center\"\u003e\n\n**LZ4 compression, xxHash3 integrity, AES-256-GCM encryption — for arbitrary byte payloads.**\n\n[![Crates.io](https://img.shields.io/crates/v/cachekit-core.svg)](https://crates.io/crates/cachekit-core)\n[![Documentation](https://docs.rs/cachekit-core/badge.svg)](https://docs.rs/cachekit-core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![MSRV](https://img.shields.io/badge/MSRV-1.85-blue.svg)](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0.html)\n\n[Features](#features) · [Quick Start](#quick-start) · [FFI](#c-ffi) · [Security](#security) · [Architecture](#architecture)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\n`cachekit-core` transforms byte payloads: compress them, verify their integrity, encrypt them. Bytes in, bytes out.\n\n| Component | What it does |\n|:----------|:-------------|\n| **ByteStorage** | `\u0026[u8]` → LZ4 compress → xxHash3 checksum → `Vec\u003cu8\u003e` envelope |\n| **Encryption** | `\u0026[u8]` → AES-256-GCM encrypt → `Vec\u003cu8\u003e` ciphertext |\n| **Key Derivation** | Master key → HKDF-SHA256 → derived key per tenant/domain |\n\n\u003e [!TIP]\n\u003e For Redis caching with Python decorators, see [`cachekit`](https://github.com/cachekit-io/cachekit).\n\n---\n\n## Features\n\n| Feature | Description | Default |\n|:--------|:------------|:-------:|\n| `compression` | LZ4 compression via [`lz4_flex`](https://crates.io/crates/lz4_flex) | ✅ |\n| `checksum` | [`xxhash-rust`](https://crates.io/crates/xxhash-rust) integrity verification | ✅ |\n| `encryption` | AES-256-GCM via [`ring`](https://crates.io/crates/ring) + HKDF-SHA256 | ❌ |\n| `ffi` | C header generation | ❌ |\n\n```toml\n# Cargo.toml - defaults only\n[dependencies]\ncachekit-core = \"0.1\"\n\n# With encryption\n[dependencies]\ncachekit-core = { version = \"0.1\", features = [\"encryption\"] }\n\n# For C FFI development\n[dependencies]\ncachekit-core = { version = \"0.1\", features = [\"ffi\", \"encryption\"] }\n```\n\n---\n\n## Quick Start\n\n### Basic Storage (Compress + Checksum)\n\n```rust\nuse cachekit_core::ByteStorage;\n\n// Create storage with default format\nlet storage = ByteStorage::new(None);\n\n// Store data (compresses + checksums automatically)\nlet data = b\"Hello, cachekit!\";\nlet envelope = storage.store(data, None)?;\n\n// Retrieve data (decompresses + verifies checksum)\nlet (retrieved, format) = storage.retrieve(\u0026envelope)?;\nassert_eq!(data.as_slice(), retrieved.as_slice());\n```\n\n### With Encryption (Zero-Knowledge)\n\n```rust\nuse cachekit_core::{ByteStorage, ZeroKnowledgeEncryptor, derive_domain_key};\n\n// Derive tenant-isolated key from master secret\nlet master_key = [0u8; 32]; // Use secure key in production!\nlet tenant_key = derive_domain_key(\n    \u0026master_key,\n    \"cache\",           // domain separation\n    b\"tenant-12345\",   // tenant isolation\n)?;\n\n// Encrypt sensitive data\nlet encryptor = ZeroKnowledgeEncryptor::new();\nlet plaintext = b\"sensitive user data\";\nlet aad = b\"tenant-12345\"; // Additional authenticated data\n\nlet ciphertext = encryptor.encrypt_aes_gcm(plaintext, \u0026tenant_key, aad)?;\n\n// Decrypt (fails if AAD doesn't match)\nlet decrypted = encryptor.decrypt_aes_gcm(\u0026ciphertext, \u0026tenant_key, aad)?;\nassert_eq!(plaintext.as_slice(), decrypted.as_slice());\n```\n\n\u003e [!IMPORTANT]\n\u003e **Key Management**: Never hardcode keys. Use environment variables or a secrets manager. The `CACHEKIT_MASTER_KEY` environment variable is the recommended approach.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull Pipeline: Compress → Encrypt → Store\u003c/strong\u003e\u003c/summary\u003e\n\n```rust\nuse cachekit_core::{ByteStorage, ZeroKnowledgeEncryptor, derive_domain_key};\n\nfn cache_sensitive_data(\n    data: \u0026[u8],\n    master_key: \u0026[u8],\n    tenant_id: \u0026str,\n) -\u003e Result\u003cVec\u003cu8\u003e, Box\u003cdyn std::error::Error\u003e\u003e {\n    // Step 1: Compress + checksum\n    let storage = ByteStorage::new(None);\n    let compressed = storage.store(data, None)?;\n\n    // Step 2: Derive tenant key\n    let tenant_key = derive_domain_key(master_key, \"cache\", tenant_id.as_bytes())?;\n\n    // Step 3: Encrypt compressed envelope\n    let encryptor = ZeroKnowledgeEncryptor::new();\n    let ciphertext = encryptor.encrypt_aes_gcm(\n        \u0026compressed,\n        \u0026tenant_key,\n        tenant_id.as_bytes(),\n    )?;\n\n    Ok(ciphertext)\n}\n```\n\n\u003c/details\u003e\n\n---\n\n## C FFI\n\nBuild with FFI feature to generate `include/cachekit.h`:\n\n```bash\ncargo build --release --features ffi\n```\n\nThis produces:\n- `target/release/libcachekit_core.{so,dylib,dll}` — Shared library\n- `include/cachekit.h` — C header file\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eExample C Usage\u003c/strong\u003e\u003c/summary\u003e\n\n```c\n#include \"cachekit.h\"\n#include \u003cstdio.h\u003e\n\nint main() {\n    // Create storage handle\n    CachekitByteStorage* storage = cachekit_byte_storage_new(NULL);\n\n    // Store data\n    const uint8_t data[] = \"Hello from C!\";\n    uint8_t* envelope = NULL;\n    size_t envelope_len = 0;\n\n    CachekitError err = cachekit_byte_storage_store(\n        storage, data, sizeof(data) - 1, NULL, \u0026envelope, \u0026envelope_len\n    );\n\n    if (err != CACHEKIT_OK) {\n        printf(\"Store failed: %d\\n\", err);\n        return 1;\n    }\n\n    // Retrieve data\n    uint8_t* retrieved = NULL;\n    size_t retrieved_len = 0;\n\n    err = cachekit_byte_storage_retrieve(\n        storage, envelope, envelope_len, \u0026retrieved, \u0026retrieved_len\n    );\n\n    // Cleanup\n    cachekit_byte_storage_free(storage);\n    cachekit_free_buffer(envelope);\n    cachekit_free_buffer(retrieved);\n\n    return 0;\n}\n```\n\n**Compile:**\n```bash\ngcc -o example example.c -L target/release -lcachekit_core -I include\n```\n\n\u003c/details\u003e\n\n---\n\n## Security\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                     Security Architecture                        │\n├─────────────────────────────────────────────────────────────────┤\n│                                                                  │\n│  Master Key ──┬──► HKDF-SHA256 ──► Tenant Key A                 │\n│               │                                                  │\n│               ├──► HKDF-SHA256 ──► Tenant Key B                 │\n│               │                                                  │\n│               └──► HKDF-SHA256 ──► Tenant Key N                 │\n│                                                                  │\n│  Each tenant key provides:                                       │\n│  • Cryptographic isolation (compromise one ≠ compromise all)    │\n│  • Domain separation (cache vs auth vs sessions)                │\n│  • Forward secrecy with key rotation                            │\n│                                                                  │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n| Property | Implementation |\n|:---------|:---------------|\n| **Encryption** | AES-256-GCM (AEAD) via [`ring`](https://crates.io/crates/ring) |\n| **Key Derivation** | HKDF-SHA256 (RFC 5869) via [`hkdf`](https://crates.io/crates/hkdf) |\n| **Integrity** | [`xxhash-rust`](https://crates.io/crates/xxhash-rust) (xxHash3-64) |\n| **Nonce Safety** | Counter-based + random IV (no reuse) |\n| **Memory Safety** | [`zeroize`](https://crates.io/crates/zeroize) on drop for all key material |\n| **Timing Safety** | Constant-time comparisons via [`ring`](https://crates.io/crates/ring) |\n\n\u003e [!WARNING]\n\u003e **Nonce Counter**: Each `ZeroKnowledgeEncryptor` instance supports 2³² encryptions before requiring rotation. The FFI layer returns `CACHEKIT_ROTATION_NEEDED` at 2³¹ operations as an early warning.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDecompression Bomb Protection\u003c/strong\u003e\u003c/summary\u003e\n\nAll decompression operations enforce:\n\n| Limit | Value | Purpose |\n|:------|:------|:--------|\n| Max uncompressed size | 512 MB | Memory exhaustion prevention |\n| Max compressed size | 512 MB | Input validation |\n| Max compression ratio | 1000x | Decompression bomb detection |\n\nMalicious payloads claiming `original_size: 500GB` with 100 bytes of data are rejected **before** decompression.\n\n\u003c/details\u003e\n\n---\n\n## Architecture\n\n```\ncachekit-core/\n├── src/\n│   ├── lib.rs              # Public API exports\n│   ├── byte_storage.rs     # LZ4 + xxHash3 storage envelope\n│   ├── metrics.rs          # Operation timing \u0026 statistics\n│   │\n│   ├── encryption/         # (feature = \"encryption\")\n│   │   ├── mod.rs          # Module exports\n│   │   ├── core.rs         # AES-256-GCM implementation\n│   │   ├── key_derivation.rs # HKDF-SHA256 + tenant isolation\n│   │   └── key_rotation.rs # Graceful key rotation support\n│   │\n│   └── ffi/                # (feature = \"ffi\")\n│       ├── mod.rs          # FFI exports\n│       ├── error.rs        # C-compatible error codes\n│       ├── handles.rs      # Opaque handle management\n│       ├── byte_storage.rs # ByteStorage FFI bindings\n│       └── encryption.rs   # Encryption FFI bindings\n│\n├── include/\n│   └── cachekit.h          # Generated C header\n│\n├── fuzz/                   # Fuzzing targets (16 targets)\n│   └── fuzz_targets/\n│\n└── tests/                  # Integration \u0026 property tests\n```\n\n---\n\n## Performance\n\nBenchmarks on Apple M2 Max (64KB payload, compressible data):\n\n| Operation | Throughput | Notes |\n|:----------|:-----------|:------|\n| LZ4 compress | ~15 GB/s | Highly compressible data |\n| LZ4 decompress | ~37 GB/s | |\n| xxHash3-64 | ~36 GB/s | 19x faster than Blake3 |\n| AES-256-GCM encrypt | ~6 GB/s | ARM Crypto Extensions |\n| AES-256-GCM decrypt | ~6 GB/s | ARM Crypto Extensions |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e1KB payload (per-call overhead visible)\u003c/strong\u003e\u003c/summary\u003e\n\n| Operation | Throughput |\n|:----------|:-----------|\n| LZ4 compress | ~2 GB/s |\n| LZ4 decompress | ~14 GB/s |\n| xxHash3-64 | ~10 GB/s |\n| AES-256-GCM encrypt | ~3.6 GB/s |\n| AES-256-GCM decrypt | ~4.4 GB/s |\n\n\u003c/details\u003e\n\n\u003e [!TIP]\n\u003e Hardware acceleration is auto-detected. ARM64 uses ARM Crypto Extensions; x86-64 uses AES-NI.\n\n---\n\n## Testing\n\n```bash\n# Run all tests\ncargo test --all-features\n\n# Run with specific feature\ncargo test --features encryption\n\n# Property-based tests\ncargo test --all-features -- --include-ignored proptest\n\n# Fuzzing (requires cargo-fuzz)\ncd fuzz \u0026\u0026 cargo fuzz run byte_storage_corrupted_envelope\n```\n\nSee [`fuzz/README.md`](fuzz/README.md) for comprehensive fuzzing documentation.\n\n---\n\n## Minimum Supported Rust Version\n\nThis crate requires **Rust 1.85** or later (Edition 2024).\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[Documentation](https://docs.rs/cachekit-core)** · **[Crates.io](https://crates.io/crates/cachekit-core)** · **[GitHub](https://github.com/cachekit-io/cachekit-core)**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcachekit-io%2Fcachekit-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcachekit-io%2Fcachekit-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcachekit-io%2Fcachekit-core/lists"}