4nk/sdk_client
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update pairing.rs documentation

Browse Source
This commit is contained in:
Sosthene 2024-10-31 15:54:24 +01:00
parent 30d7ddcf1a
commit 124718a207
1 changed files with 54 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
tests/pairing.rs
View File

@ -25,63 +25,71 @@ wasm_bindgen_test_configure!(run_in_browser);
/// # Pairing Process Documentation between Alice and Bob /// # Pairing Process Documentation between Alice and Bob
/// ///
/// This test describes the secure pairing process between two devices, Alice and Bob, /// This test describes the secure pairing process between two devices, Alice and Bob.
/// across several steps, utilizing `process_cache` to store and exchange the process state ///
/// while mutually validating their commitments. Each stage is designed to establish a strong /// ## What's pairing?
/// validation between the two devices via secure exchanges of `prd` messages (updates and confirmations). /// Pairing is a process, and abide by the same rules than any other process. The goal of pairing
/// /// is to define an identity on the network as a set of devices (defined by their sp_address).
/// Being a process it is public and can be audited by anyone, and be used as one's proof of identity.
/// It also contains a session keypair that is updated as necessary. Since all devices are needed to
/// update the key in the process it can then be used to sign a proof that someone was indeed in control
/// of all the devices for some amount of time in a MFA setup.
/// It contains the following mandatory fields:
/// * `roles`: multiple devices represented as sp adresses linked together in the same member. It is recommended
/// to have one `owner` role with one member which is the actual identity and whose signatures are all
/// needed to modify anything in the process.
/// * `session_privkey`: a private key visible by all devices of the member defined in the process, but
/// not by other members. It *must* be changed at every update of the process. This key will be used
/// to sign documents and validate actions for other processes. It's valid as soon as the commitment
/// transaction for the process udpate is seen and it stays valid for _n_ blocks after the update being mined.
/// * `session_pubkey`: the x-only public key derived from the session private key. It's visible by everyone and
/// used for validation by any third party. Obviously it changes with the private key at any update.
/// * `parity`: the parity of the session_pubkey. We could use 33 bytes compressed public key format
/// but using 32 bytes publick key + parity allows for more standard serialization.
///
/// ## Detailed protocol
/// (Here Alice and Bob are used as a convention, but keep in mind they're not 2 different users, but
/// 2 devices belonging to the same user)
/// ## Step 0 - Preliminary step
/// 1. **Establishing a Shared Secret**: A shared secret is established to secure
/// communication between Alice and Bob (see `connect.rs`).
/// ## Step 1 - Pairing Preparation by Alice /// ## Step 1 - Pairing Preparation by Alice
/// 1. **Establishing a Shared Secret**: A shared secret is established via `connect.rs` to secure /// 1. **Pairing Status Check**: Alice verifies that it's not already paired.
/// communication between Alice and Bob. /// 2. **Adding Bob's Address**: Alice adds Bob’s address to her own, setting the base for creating
/// 2. **Pairing Status Check**: Alice verifies that the pairing is not already active.
/// 3. **Adding Bob's Address**: Alice adds Bob’s address to her own, setting the base for creating
/// a new `Member` object. /// a new `Member` object.
/// 4. **Initiating Pairing**: Alice initializes pairing using the transaction’s `commitment` and /// 3. **Creation of the pairing process**: Alice initializes pairing by creating a prd update that contains
/// the created member, which contains the list of devices. /// both its address and Bob's, and send it to Bob.
/// 5. **Updating `prd`**: Alice creates an update `prd`, stores this new state in
/// `alice_process_cache`, and sends the `prd` to Bob.
/// ///
/// ## Step 2 - Receiving and Confirming the `prd` by Bob /// ## Step 2 - Receiving and Confirming the `prd` by Bob
/// 1. **Receiving and Verifying**: Bob receives and decrypts the update `prd` message sent by Alice. /// 1. **Receiving and Verifying**: Bob receives and decrypts the update `prd` message sent by Alice.
/// 2. **Updating Process State**: Bob updates his process state using the `prd` data and stores /// 2. **Updating Process State**: Bob identifies the new process and store it, but it doesn't have access
/// this new state in `bob_process_cache`. /// to the actual data for now.
/// 3. **Creating and Sending `Prd Confirm`**: Bob creates a confirmation `prd`, which he then /// 3. **Creating and Sending `Prd Confirm`**: Bob creates a confirmation `prd`, which he then
/// sends to Alice to proceed with the pairing. /// sends to Alice to get the pcd containing the state for this new process.
/// ///
/// ## Step 3 - Confirmation of `Prd Confirm` by Alice /// ## Step 3 - Alice gets confirmation and answers with a pcd
/// 1. **Receiving and Verifying**: Alice receives the `Prd Confirm` sent by Bob. /// 1. **Receiving and Verifying**: Alice receives the `Prd Confirm` sent by Bob.
/// 2. **Creating Commitment**: Alice uses the received `prd` to generate a commitment based on the /// 2. **Sending PCD**: Alice having confirmation that Bob got the update proposal,
/// recorded process state. /// it now sends the actual data in a pcd.
/// 3. **Proof Generation**: Alice creates a proof using her private spend key and response to the /// 3. **User confirmation**: At this step we must get the approval of the user. If user confirms
/// commitment, which is then added to the `prd`. /// the pairing we create a prd response with a valid signature from Alice spend key and send
/// 4. **Updating `process_cache`**: Alice stores the new state in `alice_process_cache`. /// it to Bob.
/// 5. **Sending `Prd Response`**: Alice creates and sends a `Prd Response` to Bob, including ///
/// the commitment of the `pcd` which will validate the pairing.
///
/// ## Step 4 - Finalizing Pairing by Bob /// ## Step 4 - Finalizing Pairing by Bob
/// 1. **Receiving and Verifying `Prd Response` and `pcd`**: Bob receives Alice’s `Prd Response` /// 1. **Receiving and Verifying `pcd`**: Bob received the `pcd` and only now can tell what's the
/// and updates `bob_process_cache` with the new state. /// process was about.
/// 2. **Validating Pairing State**: Bob retrieves the latest process state and the state change /// 2. **Validating Pairing State**: Bob retrieves the latest process state and the state change
/// request, in this case, the pairing. /// request, in this case, the pairing. User is prompted for validation, and if confirmed a prd response
/// - He validates the current process state. /// is created and sent(see the **User confirmation** step for Alice).
/// - He decrypts the `pcd` to retrieve the request.
/// 3. **Verifying Roles and Addresses**: Bob extracts the roles associated with the state change,
/// retrieves the addresses of involved members, and displays them to the user to confirm pairing.
/// 4. **Adding Final Proof**: Upon user confirmation, Bob generates and adds his proof to the `prd`,
/// then records the final state in `bob_process_cache`.
/// ///
/// ## Creation of Pairing Transaction /// ## Commiting the process state
/// 1. **Creating the `commit_msg`**: A validation message (`commit_msg`) containing proofs from /// 1. **Creating the `commit_msg`**: The first device that got both validations creates the commit_msg that
/// both Alice and Bob is generated. /// contains a transaction paying a relay to generate the first outpoint to commit the state of the process,
/// 2. **Creating the Transaction**: A transaction containing the final commitment is created and /// the hash of the encrypted state of the process (relay must have access to roles though, either it is clear
/// shared between Alice and Bob. /// all along or it was provided with the encryption keys) and the proofs that all devices validated this state.
/// 3. **Device Pairing**: Using the transaction `txid` and the list of member addresses, the /// 2. **Actual commitment**: As soon as the relay validated the proofs it spends the outpoint and puts the hash of
/// pairing is officially initiated, validated by a new `Member` object grouping Alice and Bob’s /// the whole prd response (including pcd hash and all the proofs) in an OP_RETURN output. The process is now
/// addresses along with the transaction. /// public and can be used to prove identity for other processes.
///
/// ## Final Outcome
/// The pairing is now active between Alice and Bob, ensuring the mutual validation of their
/// respective identities and shared commitment to the validated `prd`.
#[wasm_bindgen_test] #[wasm_bindgen_test]
fn test_pairing() { fn test_pairing() {