rev.3 complete & more details
This commit is contained in:
79
architecture/1. Elements.md
Normal file
79
architecture/1. Elements.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# ZKL Architecture
|
||||
|
||||
This file describes modules and submodules present in zk-Lokomotive's platform and web applications.
|
||||
|
||||
Yigid BALABAN, <fyb@fybx.dev>
|
||||
|
||||
Revision 1
|
||||
20/09/2024
|
||||
|
||||
## 1. Elements
|
||||
|
||||
Our architecture consists of 3 layers, middle one being the platform and the edges being the users.
|
||||
|
||||
Figure: zk-Lokomotive Module Legend
|
||||
![[zkl module legend light.png]]
|
||||
|
||||
### Difference between installations
|
||||
|
||||
We offer enterprise-level solutions where the platform is full on-chain for an unmatched privacy potential. With the use of a decentralised "CCIR", we provide identity proving and account management in blockchain, removing any centralised layers where data can be tampered with.
|
||||
|
||||
See "Appendix A" for the enterprise module legend.
|
||||
|
||||
### Modules
|
||||
|
||||
The infrastructure consists of 3 modules, with the JavaScript/Svelte web application consisting of 4 submodules. Here's the breakdown of each module:
|
||||
|
||||
#### JavaScript/Svelte web application (client)
|
||||
|
||||
The client is the user-facing module of zk-Lokomotive, allowing people to send and receive files using the accounts they "create" through linking their wallet accounts.
|
||||
|
||||
##### Submodule: aus
|
||||
|
||||
This submodule provides the functionality of communicating with distributed file chains and/or decentralised networks like IPFS. In our current implementation (see "crypto sysarch", revision 3) we are utilising Arweave.
|
||||
|
||||
##### Submodule: roadhog
|
||||
|
||||
This submodule interfaces with the several blockchain networks utilised in our platform to perform specific objectives by calling or querying smart contracts, Solana programs, etc.
|
||||
|
||||
##### Submodule: crypto
|
||||
|
||||
This submodule performs cryptographic applications. In our current implementation we support elliptic curve integrated encryption scheme through [ecies/rs-wasm](https://github.com/ecies/rs-wasm) package which consumes the Rust crate [eciesrs](https://docs.rs/crate/ecies/0.1.2).
|
||||
|
||||
##### Submodule: kds
|
||||
|
||||
This submodule generates pseudo-random mnemonics using [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) that are then derived to elliptic curve keypairs.
|
||||
|
||||
#### Platform-level: CCIR
|
||||
|
||||
Cross-Chain Identity Registry, or CCIR for short is the address book of zk-Lokomotive users, linking their wallet addresses to their elliptic public keys. On CCIR, the wallet user can only add or modify information about themselves after proving that they own the private key to that wallet account (simply, authenticating), but everyone is allowed to do queries from a public EC key to the wallet address, or from a wallet address to the public EC key.
|
||||
|
||||
The CCIR holds the following information:
|
||||
```json
|
||||
{
|
||||
"wallet_addresses": [
|
||||
{ "address": "0x123...", "network": "ethereum" }
|
||||
],
|
||||
"userPublicKey": "0x123...",
|
||||
"main_wallet_address": "0x123..."
|
||||
}
|
||||
```
|
||||
|
||||
#### Platform-level: Arweave
|
||||
|
||||
Following our current (rev.3) architecture, we are using Arweave for a decentralised file storage solution.
|
||||
|
||||
#### Platform-level: Inbox
|
||||
|
||||
Inboxes are on-chain and network-specific implementations which the client calls using the submodule roadhog when querying for incoming files, or sending a file.
|
||||
|
||||
The inbox can be logically defined as:
|
||||
```ocaml
|
||||
type message = { q_e: string; e_plink: string; uPK: string; }
|
||||
let inbox : message StringMap.t ref = ref StringMap.empty
|
||||
```
|
||||
|
||||
### Appendix A
|
||||
|
||||
Figure: zk-Lokomotive Enterprise Deployment Module Legend
|
||||
![[zkl enterprise module legend light.png]]
|
||||
68
architecture/2. Cryptographic Activities.md
Normal file
68
architecture/2. Cryptographic Activities.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user