68 lines
2.8 KiB
Markdown
68 lines
2.8 KiB
Markdown
# ZKL Architecture
|
|
|
|
This file describes the cryptographic activities that take place in zk-Lokomotive's platform and web applications.
|
|
|
|
Yigid BALABAN, <fyb@fybx.dev>
|
|
|
|
Revision 3
|
|
20/09/2024
|
|
|
|
## 2. Cryptographic Activities
|
|
|
|
## System Elements
|
|
|
|
The system elements are/will be described and discussed in the ZKL System Architecture document. This section is to provide a reminder/reference.
|
|
|
|
### 1. Key Derivation Service
|
|
|
|
The Key Derivation Service (or KDS for short) provides
|
|
1. a deterministic secp256k1 keypair generator from BIP-39 mnemonics,
|
|
2. a pseudo-random BIP-39 mnemonic generator through web-bip-39 package.
|
|
|
|
### 2. Cross-chain Identity Registry
|
|
|
|
The Cross-chain Identity Registry (or CCIR for short) provides a method to look up identities and their corresponding public keys.
|
|
|
|
### 3. Encrypted File Storage
|
|
|
|
The Encrypted File Storage is a distributed storage solution that allows the recipient to retrieve payloads that were uploaded for them.
|
|
|
|
### 4. Client
|
|
|
|
The client (the sender) generates the encrypted payload to be sent to the reciever, whose public key is retrieved via the CCIR. The workflow of sending an encrypted file for a recipient is described in the next section.
|
|
|
|
## Workflows
|
|
|
|
### Definitions
|
|
$Q_{r}:\text{Recipient's public key on curve secp256k1}$
|
|
$G:\text{The generator point on curve secp256k1}$
|
|
$Z:\text{A symmetric key derived for the file to be sent, the shared secret}$
|
|
$F_c:\text{The file contents, in plaintext}$
|
|
$F_m:\text{File's metadata, name, etc}$
|
|
$F:\text{The intermediate file format, ready to be encrypted}$
|
|
$F_{c}:\text{The file contents, in ciphertext}$
|
|
$IV:\text{The initialization vector required for AES-GCM-256}$
|
|
$P:\text{The payload, what is sent to the recipient}$
|
|
|
|
The $F$, intermediate file format is as follows:
|
|
|
|
| Bytes | \[0]..4 | \[4]..1024 | \[1024]...1024+len($F_c$) |
|
|
| ------------------- | --------------- | -------------------- | ------------------------- |
|
|
| **Content** | Length of $F_m$ | $F_m$ | $F_c$ |
|
|
| **Length in bytes** | 4 bytes | 1020 (255 * 4 bytes) | variable |
|
|
|
|
### Workflow: Sending a file
|
|
|
|
1. The $Q_{r}$ is retrieved from the CCIR.
|
|
2. An ephemeral keypair is generated, $Q_{e}$ and $d_{e}$.
|
|
3. The shared secret which will be used in symmetric encryption is computed from $Z=d_{e}\times Q_{r}$.
|
|
5. File intermediate $F$ is encrypted using AES-GCM-256 with encryption key $Z$, and a randomly generated initialization vector, $IV$.
|
|
7. The payload $P$ is created by concatenating $Q_{e},\;IV,\;\text{MAC},\;F_{e}$.
|
|
8. The payload is uploaded to the EFS.
|
|
|
|
> [!info] Reminder
|
|
> The MAC in the payload $P$ at step 7 is a result of using AES-GCM-256, which is selected in ECIES implementation in the Rust crate we consume through ecies/rs-wasm package.
|
|
|
|
### Workflow: Receiving a file
|
|
|
|
TBE |