Skip to main content

​
Encryption

VecLabs encrypts all vectors and metadata client-side using AES-256-GCM before any data leaves the SDK. This page covers the technical implementation.

​
Algorithm: AES-256-GCM

AES-256-GCM (Advanced Encryption Standard, 256-bit key, Galois/Counter Mode) is an authenticated encryption algorithm. It provides:
  • Confidentiality - ciphertext is computationally indistinguishable from random without the key
  • Integrity - a 128-bit authentication tag detects any tampering with the ciphertext
  • Authenticity - the tag proves the data was encrypted by someone with the key
GCM mode is parallelizable and hardware-accelerated on modern CPUs (AES-NI instructions). It’s the same algorithm used by HTTPS (TLS 1.3), Signal, WhatsApp, and iMessage.

​
Key derivation

The encryption key is derived from your Solana wallet keypair using PBKDF2-SHA256: 
wallet_keypair (ed25519 private key, 32 bytes)
      │
      ▼
PBKDF2-SHA256(
  password = wallet_secret_key_bytes,
  salt = "veclabs-v1" + collection_id,
  iterations = 100_000,
  key_length = 32
)
      │
      ▼
AES-256 key (32 bytes)
Properties of this approach:
  • Deterministic - same wallet always produces the same key for a given collection
  • Collection-isolated - different collections use different derived keys
  • Versioned - the “veclabs-v1” prefix allows future key derivation upgrades

​
Encryption per record

Each vector record is encrypted individually: 
plaintext = serialize(vector_values + metadata)
nonce = random_bytes(12)  # 96-bit GCM nonce, unique per encryption
ciphertext, auth_tag = AES_256_GCM_encrypt(key, nonce, plaintext)
stored = nonce + ciphertext + auth_tag
A fresh random nonce is generated for every encryption operation. Nonce reuse with the same key would be a security vulnerability - generating a new one each time eliminates this risk.

​
What is encrypted

Everything in a vector record is encrypted together:
  • The vector values (f32 array)
  • The metadata (arbitrary JSON)
  • The vector ID is NOT encrypted - it’s hashed into the Merkle tree

​
Source code

The encryption implementation is in the open-source Rust core: crates/solvec-core/src/encryption.rs It is tested with 5 unit tests including roundtrip, wrong key failure, and empty input edge cases.