> For the complete documentation index, see [llms.txt](https://wiki.4thtech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.4thtech.io/products/encryptor/how-it-works.md).

# How Encryptor works

How Encryptor holds your encryption key and lets apps compute shared secrets with it.

{% hint style="info" %}
**Status: Production-ready, stable.** Encryptor is supported; no new features are planned. Last update: 18 Apr 2024 (version 0.1.0).
{% endhint %}

Encryptor lets two people share a secret without ever sending it. This page explains the idea and the states Encryptor can be in.

## Your encryption key

When you create an Encryptor, the extension generates a random key pair with the ethers library. The key comes from a recovery phrase, which the extension shows once on its "Seed words" screen. The key pair is separate from your Web3 wallet account.

* The **private key** stays in the extension. Apps never receive it.
* The **public key** can be shared. An app asks Encryptor for it (`getPublicKey`) and can publish it on the blockchain for others to read. In OCC v1 this is the Users contract, via the SDK's `storePublicKey`.

## The shared secret

Encryption between two users uses ECDH (Elliptic-Curve Diffie-Hellman). Each side combines its own private key with the other side's public key and gets the **same shared secret**. Nobody has to send that secret to the other person.

1. The sender's app reads the receiver's public key from the blockchain.
2. The app asks Encryptor to compute the shared secret (`computeSharedSecretKey`) with that public key.
3. The app uses the secret to derive an AES-256-GCM key and encrypts the content.
4. The receiver does the same with the sender's public key and gets the same secret, so they can decrypt.

```mermaid
sequenceDiagram
    participant App as App (BlockMail or BlockChat)
    participant Chain as Users contract (OCC v1)
    participant Enc as Encryptor extension
    App->>Chain: Read receiver public key
    Chain-->>App: Receiver public key
    App->>Enc: computeSharedSecretKey(receiver public key)
    Note over Enc: Combines your private key with the receiver public key
    Enc-->>App: Shared secret
    Note over App: Encrypts with AES-256-GCM using the shared secret
    Note over Enc: Private key never leaves the extension
```

*Figure: How an app encrypts for another user, with the private key kept inside Encryptor.*

Be clear about what crosses the boundary: the app receives the **shared secret** for that pair of users, not your private key.

## Encryption options in OCC v1

Encryptor serves one of three options in OCC v1. See the [OCC v1 encryption page](https://wiki.4thtech.io/protocols/occ-v1/encryption.md) for detail.

```mermaid
flowchart TD
    A[Encryption options] --> B[Custom encryption]
    A --> C[AES with a random or imported key]
    A --> D[AES with ECDH]
    B --> B1["Integrator's own implementation"]
    C --> C1["Key is generated or imported by the app"]
    D --> D1["Encryptor computes the shared secret"]
    D --> D2["Public key published on the Users contract"]
```

*Figure: The three OCC v1 encryption options; Encryptor serves the AES with ECDH option.*

## States

Encryptor is always in one of these situations. Apps read them through the SDK.

```mermaid
stateDiagram-v2
    [*] --> NotInstalled
    NotInstalled --> NotInitialized: Install the extension
    NotInitialized --> Unlocked: Create or restore a key
    Unlocked --> Locked: Logout, or browser session ends
    Locked --> Unlocked: Unlock with your password
```

*Figure: Encryptor states, from not installed to unlocked, and back to locked.*

| Situation                   | Extension state | SDK check                    |
| --------------------------- | --------------- | ---------------------------- |
| Extension missing           | (no reply)      | `isInstalled()` is `false`   |
| No key created yet          | `not-generated` | `isInitialized()` is `false` |
| Key exists, password needed | `locked`        | `isLocked()` is `true`       |
| Ready                       | `unlocked`      | `isUnlocked()` is `true`     |

Next: [Install Encryptor](https://wiki.4thtech.io/products/encryptor/install.md).
