> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prem.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Encryption

> Learn about the end-to-end encryption architecture that protects your data.

Prem API  uses **end-to-end encryption** (E2EE) to ensure your data remains private and secure. All encryption happens client-side, meaning your plaintext data never leaves your device unencrypted — not even we can read it.

## Zero-Knowledge Architecture

Our platform is built on a **zero-knowledge** principle:

<CardGroup cols={2}>
  <Card title="Client-Side Encryption" icon="laptop">
    All data is encrypted on your device before transmission
  </Card>

  <Card title="No Plaintext Access" icon="eye-slash">
    Servers only see encrypted data, never your actual data
  </Card>

  <Card title="You Control the Keys" icon="key">
    Encryption keys are generated and stored only on your side
  </Card>

  <Card title="Post-Quantum Security" icon="atom">
    Protected against both current and future quantum computing threats
  </Card>
</CardGroup>

## How It Works

The encryption architecture uses a **two-server model** for defense in depth:

```mermaid theme={"system"}
flowchart LR
    subgraph Client["Your Device"]
        A[Plaintext Data] --> B[Encryption]
        B --> C[Encrypted Data]
        K[Your Keys] --> B
        H[Encrypted Response] --> I[Decryption]
        K --> I
        I --> J[Plaintext Response]
    end
    
    subgraph Proxy["Prem API Gateway"]
        D[Encrypted Data Only]
    end
    
    subgraph Enclave["Prem API  Enclave"]
        E[Decrypt]
        F[Process]
        G[Encrypt Response]
        E --> F --> G
    end
    
    C --> D
    D --> E
    G --> D
    D --> H
```

### Prem API Gateway vs Prem API Enclave

| Component            | What It Sees        | Purpose                                                                  |
| -------------------- | ------------------- | ------------------------------------------------------------------------ |
| **Prem API Gateway** | Only encrypted data | Stores and routes encrypted data, never sees plaintext                   |
| **Prem API Enclave** | Decrypted data      | Decrypts, processes requests, encrypts responses in isolated environment |

<Note>
  The **Prem API Gateway** acts as a secure gateway that **never has access to your plaintext data**. It simply forwards encrypted payloads to the Prem API Enclave. Even if the proxy were compromised, attackers would only see encrypted data.
</Note>

The **Prem API  Enclave** runs in a **Trusted Execution Environment (TEE)** — an isolated, hardware-protected environment where:

* Decryption happens in a secure environment
* Processing occurs completely isolated
* Responses are encrypted before leaving
* Even server operators cannot access the plaintext, no operator access mechanism exists in the images

### Key Types

* **KEK (Key Encryption Key)** — Your master key (32 bytes) that protects all other keys. Never leaves your device unencrypted.
* **DEK (Data Encryption Key)** — Unique key for each file (32 bytes). Each file gets its own key for isolation.
* **RAG DEK** — Persistent Key (32 bytes) used for encrypted document search operations.
* **CONNECTOR DEK** - Persistent Key (32 bytes) used for decrypting connectors in the enclave.
* **KID (Key Identifier)** — Derived from your KEK to identify your keys on the server without revealing the KEK itself.

<Note>
  Your master key (KEK) never leaves your device unencrypted. File keys (DEKs) are wrapped with your KEK before transmission, and the RAG DEK is also wrapped with your KEK when stored on the server. For RAG operations, both the file DEKs and RAG DEK are encrypted with a temporary shared secret from XWing key exchange before being sent to the enclave.
</Note>

## Cryptographic Algorithms

Prem API  uses modern, battle-tested cryptographic algorithms:

| Algorithm              | Type       | Purpose                                       |
| ---------------------- | ---------- | --------------------------------------------- |
| **XChaCha20-Poly1305** | AEAD       | Encrypts all your data with authentication    |
| **AES-KWP**            | Key Wrap   | Securely wraps file keys with your master key |
| **XWing**              | Hybrid KEM | Post-quantum secure key exchange              |

### Post-Quantum Security with XWing

**XWing** is a hybrid key encapsulation mechanism that combines two algorithms for maximum security:

```mermaid theme={"system"}
flowchart LR
    subgraph XWing["XWing Hybrid KEM"]
        A["ML-KEM768 (Post-Quantum)"] --> C["Combined Shared Secret"]
        B["X25519 (Classical)"] --> C
    end

    C --> D["XChaCha20-Poly1305 Encryption"]
```

* **ML-KEM768 (Kyber)** — NIST-standardized quantum-resistant algorithm
* **X25519** — Battle-tested elliptic curve algorithm

This hybrid approach ensures your data is protected against both current attacks and future quantum computers. Even if one algorithm is broken, the other maintains security.

<Warning>
  Quantum computers, when sufficiently powerful, will be able to break traditional encryption like RSA and standard elliptic curves. XWing protects against "Harvest Now, Decrypt Later" attacks where adversaries store encrypted data today to decrypt it when quantum computers mature.
</Warning>

## File Encryption

Every file you upload goes through a secure encryption process:

```mermaid theme={"system"}
flowchart TD
    A[Original File] --> B[Generate Random File Key]
    B --> C[Encrypt File Content]
    B --> D[Encrypt Metadata]
    C --> E[Encrypted File]
    D --> F[Encrypted Metadata]
    
    G[Your Master Key] --> H[Wrap File Key]
    B --> H
    H --> I[Wrapped File Key]
    
    E --> J[Upload to Server]
    F --> J
    I --> J
```

### Encryption Process

<Steps>
  <Step title="Generate File Key">
    A unique random 32-byte key is created for this specific file
  </Step>

  <Step title="Encrypt Content & Metadata">
    File content and metadata (filename, type) are encrypted with XChaCha20-Poly1305
  </Step>

  <Step title="Wrap File Key">
    The file key is encrypted with your master key using AES-KWP
  </Step>

  <Step title="Upload">
    Only encrypted data and wrapped keys are sent to the server
  </Step>
</Steps>

### Decryption Process

When you retrieve a file:

1. **Download** encrypted file and wrapped key from server
2. **Unwrap** the file key using your master key
3. **Decrypt** the file content and metadata

## RAG Encryption

For encrypted document search, Prem API  uses a **secure key exchange scheme** that enables AI-powered search while maintaining privacy:

```mermaid theme={"system"}
flowchart TD
    subgraph Client["Your Device"]
        A[XWing Key Exchange] --> B[Generate Shared Secret]
        
        C[File Key DEK] --> D[Encrypt with Shared Secret]
        D --> E[Encrypted File Key]
        
        F[RAG Key] --> G[Encrypt with Shared Secret]
        G --> H[Encrypted RAG Key]
        
        B --> D
        B --> G
    end
    
    subgraph Enclave["Prem API  Enclave"]
        I[Decrypt with Shared Secret]
        J[Decrypt File Key]
        K[Decrypt RAG Key]
        L[Decrypt File Content]
        M[Build Search Index]
        
        I --> J
        I --> K
        J --> L
        K --> M
        L --> M
    end
    
    E --> I
    H --> I
```

### How RAG Search Works

<Steps>
  <Step title="Key Exchange">
    When you index files for search:

    * XWing key exchange establishes a shared secret with the enclave
    * File key (DEK) is encrypted with the shared secret
    * RAG key is encrypted with the shared secret
    * Both encrypted keys are sent to the enclave
  </Step>

  <Step title="Search Query">
    When you search:

    * Your query is encrypted on your device
    * A new XWing key exchange is established
    * Encrypted query is sent to the enclave
  </Step>

  <Step title="Secure Processing">
    Inside the secure enclave:

    * Shared secret decrypts the RAG key and file keys
    * Relevant documents are decrypted using their file keys
    * Documents are searched in isolation
    * Results are encrypted before leaving
  </Step>

  <Step title="Results">
    Encrypted results are sent back to your device and decrypted locally
  </Step>
</Steps>

<Note>
  The Prem API Gateway never sees your search queries or document contents. All processing happens in the isolated Prem API Enclave.
</Note>

## Secure Key Exchange

For chat completions and tool operations, secure communication is established using **XWing key exchange**:

```mermaid theme={"system"}
sequenceDiagram
    participant Client as Your Device
    participant Enclave as Prem API Enclave
    participant Proxy as Prem API Gateway
    
    Note over Client,Enclave: 1. Key Exchange
    Client->>Enclave: Request public key
    Enclave-->>Client: Public key
    
    Note over Client: 2. Generate Session Key
    Client->>Client: Create shared secret using XWing
    
    Note over Client: 3. Encrypt & Send
    Client->>Client: Encrypt request
    Client->>Proxy: Send encrypted data
    Note over Proxy: Only sees encrypted bytes
    Proxy->>Enclave: Forward encrypted payload
    
    Note over Enclave: 4. Process Securely
    Enclave->>Enclave: Decrypt and process
    Enclave->>Enclave: Encrypt response
    
    Enclave-->>Proxy: Encrypted response
    Proxy-->>Client: Forward encrypted response
    
    Client->>Client: Decrypt response
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Secure Your Master Key" icon="vault">
    Your master key (KEK) is critical. Store it securely with proper backups.
  </Card>

  <Card title="Regular Backups" icon="cloud-arrow-up">
    Backup your keys to multiple secure locations. A lost master key means permanent data loss.
  </Card>

  <Card title="Never Share Keys" icon="ban">
    Your encryption keys should never be shared or transmitted in plaintext.
  </Card>

  <Card title="Verify Integrity" icon="shield-check">
    The system automatically verifies data integrity. Pay attention to any authentication errors.
  </Card>
</CardGroup>