package join

Get desktop application:
View/edit binary Protocol Buffers messages

Initial message sent by ED after nomination and user confirmation that RPH is identical on both devices. When creating this message, after confirmation by the user: 1. Stop displaying RPH and notify the user that the device join process is in progress. 2. Begin a transaction (scope `NEW_DEVICE_SYNC`, precondition: none) on the D2M connection. This transaction is to be held until the connection to ND drops or until a `Registered` message was received. While the transaction is being held, no `Reflected` and no end-to-end encrypted message coming from the chat server is allowed to be processed! If the D2M connection is lost, the established connection must also be closed, aborting any running steps of this protocol. 3. Send the `Begin` message and continue with the steps for creating `EssentialData`. When receiving this message: 1. If `Begin` has been received before, close the connection and abort these steps. 2. Stop displaying RPH and notify the user that the device join process is in progress.

Used in: EdToNd

(message has no fields)

Root message envelope for messages from the existing device (ED) to the new device (ND).

• oneof content

  The enveloped message

  • Begin begin = 1

  • common.BlobData blob_data = 2

    A Blob that is referenced as part of `EssentialData`. When receiving this variant: 1. If `EssentialData` has been received before, close the connection and abort these steps. 2. Store the Blob data temporarily or permanently and store its associated Blob ID in the device's database.

  • EssentialData essential_data = 3

Essential data ND needs to be able to participate in the device group. Note: The transmitted used nonces are hashed with HMAC-SHA256 using the identity as _key_. When creating this message: 1. Gather all blobs referenced for the user's profile picture, contact profile pictures, etc. and send them as `common.BlobData` before this message. 2. Send the gathered `EssentialData`. When receiving this message: 1. If `EssentialData` has been received before, close the connection and abort these steps. 2. If any Blob ID is missing from the previously received set of `common.BlobData`, close the connection and abort these steps. 3. Store the data in the device's database. 4. Generate a random D2M Device ID and a random CSP Device ID and store both in the device's database. 5. Establish a D2M connection by connecting to the provided mediator server. 6. Wait until the `ServerInfo` has been received on the D2M connection. Validate that the provided `DeviceSlotState` is `NEW`. Otherwise, close both the D2M connection (normally) and the connection to ED and abort these steps. 7. Send a `Registered` message to ED. 8. Ask the user whether conversation history data should be requested from ND: 1. If the user does not want to request conversation history data, wait until all buffered data on the connection has been written. Then, close the connection and abort these steps. 2. If the user wants to request conversation history data from ED, leave the connection running and start the History Exchange Protocol.

Used in: EdToNd

• optional EssentialData.IdentityData identity_data = 2

• optional sync.ThreemaWorkCredentials work_credentials = 12

  Threema Work credentials Required for a Threema Work app. Must not be present in a Threema consumer app.

• optional EssentialData.DeviceGroupData device_group_data = 3

• optional sync.UserProfile user_profile = 4

  User's profile

• optional sync.Settings settings = 5

  Shared settings

• optional sync.MdmParameters mdm_parameters = 6

  MDM parameters

• repeated EssentialData.AugmentedContact contacts = 7

• repeated EssentialData.AugmentedGroup groups = 8

• repeated EssentialData.AugmentedDistributionList distribution_lists = 9

• repeated bytes csp_hashed_nonces = 10

  Hashed nonces that were used for CSP messages.

• repeated bytes d2d_hashed_nonces = 11

  Hashed nonces thate were used for D2D messages.

Contacts

Used in: EssentialData

• optional sync.Contact contact = 1

  The contact's data.

• optional uint64 last_update_at = 2

  Unix-ish timestamp in milliseconds when the conversation with this contact was last updated. Optional if no conversation exists for this contact.

Distribution lists

Used in: EssentialData

• optional sync.DistributionList distribution_list = 1

  The distribution list's data.

• uint64 last_update_at = 2

  Unix-ish timestamp in milliseconds when the conversation of this distribution list was last updated.

Groups

Used in: EssentialData

• optional sync.Group group = 1

  The group's data.

• uint64 last_update_at = 2

  Unix-ish timestamp in milliseconds when the conversation with this group was last updated.

Device group data

Used in: EssentialData

• bytes dgk = 1

  The device group key (32 bytes)

User's identity data

Used in: EssentialData

• string identity = 1

  The user's Threema ID

• bytes ck = 2

  The permanent client key associated to the Threema ID (32 bytes)

• bytes csp_device_cookie = 3

  The device cookie used by the device group for the Threema ID (16 bytes)

• string csp_server_group = 4

  The CSP server group associated to the Threema ID (1 byte)

Root message envelope for messages from the new device (ND) to the existing device (ED).

• oneof content

  The enveloped message

  • Registered registered = 1

Lets ED know that ND has received all essential data and successfully registered itself on the mediator server. When receiving this message: 1. Commit the transaction on the D2M connection. From this point on, processing `Reflected` and end-to-end encrypted message coming from the chat server is allowed again. 2. Wait for ND to either close the connection or for ND to request conversation history data. Any further messages from ND will move into the History Exchange Protocol.

Used in: NdToEd

(message has no fields)