> ## Documentation Index > Fetch the complete documentation index at: https://docs.koalavault.ai/llms.txt > Use this file to discover all available pages before exploring further. # CryptoTensors > This document explains the principles and mechanisms behind CryptoTensors: file format, metadata schema, cryptography, and the end-to-end (de)serialization workflow. ## Overview CryptoTensors is a **file format** that aims to provide strong confidentiality and controlled access for proprietary LLM weights while preserving the usability and efficiency of the Safetensors ecosystem. CryptoTensors File Format ## High-Level Design **Philosophy:** CryptoTensors chooses to **extend** [Safetensors](https://huggingface.co/docs/safetensors/index) rather than inventing a new format. Since Saftenosrs is one of the most popular and widely used tensor serialization formats for LLMs, it is a natural choice to extend and be compatible with it to leverage the existing ecosystem, tools, and frameworks. **Cryptography Design:** * CryptoTensors uses a **header/body split strategy** similar to Safetensors. The header remains plaintext (for tensor names, shapes, dtypes) to retain discovery and loading optimizations; the body holds the encrypted tensor payloads. * CryptoTensors uses a **two-level encryption** strategy per tensor: * Per-tensor DEK encryption. Each selected tensor is encrypted with a randomly generated Data Encryption Key (DEK) and a unique IV (e.g., AES-GCM). This ensures ciphertext uniqueness and mitigates IV/key reuse. * DEK wrapping. Each DEK is wrapped (encrypted) under a master key whose release is governed by the embedded policies (via KBS or local keying). * The **integrity protection** of the model is achieved by a chain of signatures: the authenticity of the header is protected by a digital signature, combined with the two-level encryption strategy and AES-GCM's inherent integrity protection. Overall, CryptoTensors provides the integrity protection for the entire file. * The file format is **self-contained**, which means that the cryptographic metadata, policy references, and key source descriptors are embedded in the file itself. This allows for automated, policy-compliant decryption via KBS across diverse environments and licensing models. ## Format Overview CryptoTensors piggybacks on Safetensors’ `__metadata__` to introduce four signed metadata fields: * `__crypto_keys__` — JWK-encoded metadata for encryption and signing keys (e.g., `kid`, `jku`, `x5c`), with URI-style sources: `file://`, `https://`, `kbs://`. Includes `version` for forward compatibility. * `__encryption__` — Per-tensor encryption records enabling *partial encryption*. For each encrypted tensor: IV (`iv`), AEAD tag (`tag`), and the **wrapped** data-encryption key (`wrapped_key`) with its own IV/tag (`key_iv`, `key_tag`). Values are Base64-encoded. * `__policy__` — Access-control policies in **Rego** (Open Policy Agent). Split into `local` (validated by the loader against the execution environment) and `remote` (enforced by KBS for key release). * `__signature__` — Base64 signature over the entire header; verified by both loader and KBS to prevent tampering and to authenticate origin. For the tensor data, CryptoTensors uses the same format as Safetensors, which is a binary format that is compatible with the existing ecosystem, tools, and frameworks. Since the IVs/tags of encrypted tensors are stored in the header (not inline with tensor bytes), so the **memory layout of encrypted tensors is identical** to unencrypted ones; no offset recomputation is needed. This preserves mmap-friendly loading and compatibility with Safetensors tooling. ## Serialization (Exporting Model) Workflow At authoring time, the serializer: 1. **Collects configuration:** AEAD algorithm (e.g., AES-GCM-256), master key, signature algorithm (e.g., Ed25519), the list of tensors to encrypt, and deployment policies. 2. **For each selected tensor:** generate a random DEK → encrypt the tensor with DEK → **wrap** the DEK with the master key. 3. **Prepare metadata:** Assemble `__crypto_keys__`, `__encryption__`, `__policy__`, then build a temporary header and **digitally sign** it; embed the signature in `__signature__`. 4. **Write tensor data:** Write encrypted tensor bytes as the file body. After serialization, the file is safe to distribute (e.g., on public hubs); the master key must be delivered only to authorized parties. ## Deserialization (Loading Model) Workflow Given a local file: 1. **Detect encryption:** Parse the header; if `__crypto_keys__` is absent, treat as standard Safetensors. Otherwise, enter the CryptoTensors path. 2. **Verify header integrity:** Retrieve the signing key from the header’s key sources; reconstruct the header (excluding `__signature__`) and verify the signature. 3. **Evaluate local policy:** Check the `local` policy against system measurements (e.g., device identifiers, attestation). 4. **Obtain master key:** Resolve key source metadata; if remote, establish a secure channel to KBS (e.g., [KoalaVault Server](https://www.koalavault.ai)), send the header and measurements; KBS verifies header integrity and `remote` policy before releasing the key. 5. **Unwrap DEKs & decrypt on demand:** When the runtime first accesses an encrypted tensor: unwrap its DEK using the master key; decrypt the tensor; optionally cache plaintext for subsequent accesses. Lazy decryption pairs with lazy loading so only touched tensors are decrypted. After deserialization, the model is ready to be used and can be treated as a standard Safetensors model. ## Compatibility * CryptoTensors remains structurally compatible with Safetensors (header visible, offsets stable), preserving lazy loading and partial deserialization—critical for large-model inference.