From cb4fed36de81efac7c2fc0150f0159ea6ded81df Mon Sep 17 00:00:00 2001
From: jemimah2 <jemimah@elixxir.io>
Date: Tue, 9 Aug 2022 20:06:00 +0100
Subject: [PATCH] Update "cMix Client Keystore" doc
---
.../docs/guides/cmix-client-keystore.md | 20 +++++++++----------
1 file changed, 9 insertions(+), 11 deletions(-)
diff --git a/docusaurus-site/docs/guides/cmix-client-keystore.md b/docusaurus-site/docs/guides/cmix-client-keystore.md
index 0063fa3..368dda9 100644
--- a/docusaurus-site/docs/guides/cmix-client-keystore.md
+++ b/docusaurus-site/docs/guides/cmix-client-keystore.md
@@ -4,7 +4,7 @@ The cMix Client Keystore is a directory-backed encrypted key-value storage which
The keystore is initially populated by a small number of critical keys that define a client’s identity. It holds all the information necessary to send messages (transmission) as well as to receive messages (reception or message pickup) on the cMix network. The keystore is extended as needed to store key and state information for various subsystems (e.g., E2E messaging).
-## Handling the Client Keystore
+# Handling the Client Keystore
The Client Keystore requires a directory path where it will be initialized. A client must provide a path to a directory on a filesystem as well as a password that will be used to encrypt the contents of the directory. Once initialized, several encrypted files are generated at that path and used to store a variety of things that must persist across runs of the client.
@@ -12,19 +12,19 @@ The password used to encrypt the contents of the keystore must be provided by th
# Key Generation on Initialization
-The cMix client keystore must be initialized on first run. Initializing the keystore creates a series of keys for outbound (transmission) communication with the xx network. These transmission keys are then used to register and negotiate a key with each node on the network.
+The cMix Client Keystore must be initialized on first run. Initializing the keystore creates a series of keys for outbound (transmission) communication with the xx network. These transmission keys are then used to register and negotiate a key with each node on the network.
-The process generally takes 20~30 seconds on first run, but can take upwards of five minutes in rare cases. As a result, it is highly recommended in almost all cases to persist the initialized cMix client keystore across executions of the cMix client.
+The process generally takes 20~30 seconds on first run, but can take upwards of five minutes in rare cases. As a result, it is highly recommended in almost all cases to persist the initialized keystore across executions of the cMix client.
-### Client Identity
+## Client Identity
At first, only the base data for sending messages (transmission) and receiving messages (reception) are stored in the keystore. These two sets of data include:
1. **Transmission Identity**
- 1. **RSA Transmission Keys:** The transmission keys are a pair of RSA private/public keys used to register with the xx network for. The public key is signed by the client registrar, [*describe the function of the client registrar here? What is the significance of the signing?*].
+ 1. **RSA Transmission Keys:** The transmission keys are a pair of RSA private/public keys used to register with the xx network. The public key is signed by the client registrar, a temporary system run by the foundation to allow the registration of new clients to be disabled in the event of certain network attacks. In the future, this system will be replaced with an on-chain registrar which registers new users for a fee in xx coins.
2. **RSA Transmission ID:** This is a unique identifier used for sending messages over the network. It is generated using a salt and the RSA transmission public key.
2. **Legacy Reception Identity**
- 1. **RSA Reception Keys:** These are also used to register with the network. ~~The public key is signed by the client registrar.~~
+ 1. **RSA Reception Keys:** The [User Discovery](../technical-glossary#user-discovery-ud) system run by the xx foundation requires a signed reception identity for registration. While registration identities are generally intended to be fungible, for the xx messenger and xx foundation user discovery server, they are not and must be signed. This allows it to piggy back off of the protection mechanisms described in the *RSA Transmission Keys* section above.
2. **RSA Reception ID:** This is a unique identifier used by a cMix client to receive messages. It will typically poll this ID when looking for messages sent from other users. This ID is generated from a combination of a salt and the RSA reception public key.
## Other Critical Key Structures Stored in the Keystore
@@ -32,8 +32,6 @@ At first, only the base data for sending messages (transmission) and receiving m
While a small set of keys are stored on initial execution, that group grows as various modules are exercised. Here are some of the more important keys which are stored in the client Keystore. This is not an exhaustive list.
- **E2E keys:** When a cMix client requests or receives requests for an authenticated connection with another client, it uses its end-to-end (E2E) identity. This is a pair of Diffie-Helman (DH) keys.
- 1. **E2E DH Public Key:** The DH public key is used to verify the identity and ownership of messages sent. A user sends this key to a partner when requesting or receiving an authenticated connection.
- 2. **E2E DH Private Key:** The DH private key is used to decrypt messages received by a partner client. It ensures that only the intended recipient of a message can unlock it. The DH private key is generated using an E2E cryptographic group included in the network definition file (NDF).
-- cMix state data: [*Brief description of what the state data consists of*]
-- Network signatures: [*Brief description?; TransmissionRegistrationValidationsSignature, ReceptionRegistrationValidationsSignature; Relevance?*]
-- Node keypairs: [*Brief description*]
\ No newline at end of file
+- **cMix state data**: Due to the decentralized nature of the xx network and the cMix protocol, there is no central repository for the state of message picking for an individual reception ID. Instead, it is the client’s responsibility to build a picture of the network and track its own message pickup information. This data is stored in the keystore as the client runs. The bulk of the data and its handling can be found in the [/cmix/identity](https://git.xx.network/elixxir/client/-/tree/release/cmix/identity) package.
+- **Network signatures:** As described in the *Client Identity* section above, the Transmission Identity as well as the Legacy Reception Identity are signed by the Network Registrar. These signatures are stored in [/storage/user](https://git.xx.network/elixxir/client/-/tree/release/storage/user) as the `TransmissionRegistrationValidationsSignature`, and the `ReceptionRegistrationValidationsSignature`*.*
+- **Node keypairs:** Clients negotiate symmetric keys with every node in the network in order to receive the mixes the nodes are a part of. These keys are stored in the keystore in [/cmix/nodes](https://git.xx.network/elixxir/client/-/tree/release/cmix/nodes).
\ No newline at end of file
--
GitLab