> ## 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 make sure that your data stays private and secure. All encryption occurs on your device. Your plaintext data does not leave your device without encryption. Prem cannot read your data.

## Zero-Knowledge Architecture

The platform operates on a **zero-knowledge** principle:

<CardGroup cols={2}>
  <Card title="Client-Side Encryption" icon="laptop">
    Your device encrypts all data before transmission
  </Card>

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

  <Card title="You Control the Keys" icon="key">
    You generate the encryption keys, and you store them only on your side
  </Card>

  <Card title="Post-Quantum Security" icon="atom">
    The encryption protects your data against current threats 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. It never sees plaintext                            |
| **Prem API Enclave** | Decrypted data      | Decrypts requests, processes them, and encrypts responses in an isolated environment |

<Note>
  The **Prem API Gateway** is a secure gateway that **never has access to your plaintext data**. It only sends encrypted payloads forward to the Prem API Enclave. If an attacker gets control of the Prem API Gateway, the attacker sees only encrypted data.
</Note>

The **Prem API Enclave** operates in a **Trusted Execution Environment (TEE)**. A TEE is an isolated environment with hardware protection. In the TEE:

* Decryption occurs in a secure environment
* Processing occurs in full isolation
* The enclave encrypts the responses before the responses leave
* Server operators cannot access the plaintext, because no operator access mechanism exists in the images

### Key Types

* **Key Encryption Key (KEK)**: Your master key (32 bytes). It protects all other keys. It does not leave your device without encryption.
* **Data Encryption Key (DEK)**: A unique key for each file (32 bytes). Each file gets its own key for isolation.
* **RAG DEK**: A persistent key (32 bytes). The system uses it for encrypted document search operations.
* **CONNECTOR DEK** - A persistent key (32 bytes). The enclave uses it to decrypt connectors.
* **KID (Key Identifier)**: The system derives the KID from your KEK. The KID identifies your keys on the server and does not show the KEK.

<Note>
  Your master key (KEK) does not leave your device without encryption. The SDK wraps the file keys (DEKs) with your KEK before transmission. The server stores the RAG DEK wrapped with your KEK. For RAG operations, the SDK encrypts the file DEKs and the RAG DEK with a temporary shared secret from the XWing key exchange. Then the SDK sends these keys to the enclave.
</Note>

## Cryptographic Algorithms

Prem API uses modern, proven cryptographic algorithms:

| Algorithm              | Type       | Purpose                                           |
| ---------------------- | ---------- | ------------------------------------------------- |
| **XChaCha20-Poly1305** | AEAD       | Encrypts all your data with authentication        |
| **AES-KWP**            | Key Wrap   | Securely wraps the 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. It 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)**: A NIST-standardized quantum-resistant algorithm
* **X25519**: A proven elliptic curve algorithm

This hybrid method makes sure that your data is safe against current attacks and future quantum computers. If an attacker breaks one algorithm, the other algorithm keeps your data secure.

<Info>
  Sufficiently powerful quantum computers will break traditional encryption, for example RSA and standard elliptic curves. XWing protects against "Harvest Now, Decrypt Later" attacks. In these attacks, adversaries store encrypted data today. They decrypt the data when quantum computers become powerful.
</Info>

## File Encryption

Each file that 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 the file key">
    The SDK creates a unique random 32-byte key for this specific file
  </Step>

  <Step title="Encrypt the content and metadata">
    The SDK encrypts the file content and the metadata (filename, type) with XChaCha20-Poly1305
  </Step>

  <Step title="Wrap the file key">
    The SDK encrypts the file key with your master key. It uses AES-KWP
  </Step>

  <Step title="Upload the encrypted data">
    The SDK sends only encrypted data and wrapped keys to the server
  </Step>
</Steps>

### Decryption Process

When you get a file:

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

## RAG Encryption

For encrypted document search, Prem API uses a **secure key exchange scheme**. This scheme permits AI-powered search and keeps your data private:

```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:

    * The XWing key exchange establishes a shared secret with the enclave
    * The SDK encrypts the file key (DEK) with the shared secret
    * The SDK encrypts the RAG key with the shared secret
    * The SDK sends both encrypted keys to the enclave
  </Step>

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

    * The SDK encrypts your query on your device
    * The SDK establishes a new XWing key exchange
    * The SDK sends the encrypted query to the enclave
  </Step>

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

    * The shared secret decrypts the RAG key and the file keys
    * The enclave decrypts the applicable documents with their file keys
    * The enclave searches the documents in isolation
    * The enclave encrypts the results before the results leave
  </Step>

  <Step title="Results">
    The enclave sends the encrypted results back to your device. Your device decrypts the results locally
  </Step>
</Steps>

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

## Secure Key Exchange

For chat completions and tool operations, the SDK establishes secure communication with the **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">
    Store your master key (KEK) securely and keep backups. The KEK is critical.
  </Card>

  <Card title="Regular Backups" icon="cloud-arrow-up">
    Make backups of your keys in multiple secure locations. If you lose your master key, you lose your data permanently.
  </Card>

  <Card title="Never Share Keys" icon="ban">
    Do not share your encryption keys. Do not transmit them in plaintext.
  </Card>

  <Card title="Verify Integrity" icon="shield-check">
    The system verifies data integrity automatically. Examine all authentication errors.
  </Card>
</CardGroup>