The cMix Client Keystore is a directory-backed encrypted key-value storage which contains cryptographic keys and state data. It is implemented by wrapping the EKV library.

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

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.

The password used to encrypt the contents of the keystore must be provided by the user or stored securely using secure storage, for example by using the Android or iOS Keychain APIs.

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

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
  2. Legacy Reception Identity

Other Critical Key Structures Stored in the Keystore

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.