Skip to main content

​
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 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), 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.