This page describes the sequences in which the various messages are passed around by Murmeli. Each of these message types are described in the message types page. All of this won't be of any interest to the users of Murmeli, because they won't see any of these details, but it may be of interest to developers, and to any crypto specialists who want to help out reviewing the design of the system.
There are a few general use cases which we will go through here. Most of these are triggered by some action by the user of Murmeli, indicated by the abstract person icon.
Hopefully this scenario does not happen very often, because it only occurs when a contact request is rejected. But it's the shortest and simplest sequence which doesn't require any other sequences, so it's a good place to start. It starts with the person on the left asking Murmeli to request contact with a new friend.
The contact request message is by necessity sent unencrypted, and contains various bits of information to identify the requester, plus the requester's public key. In this scenario the receiver of the request decides not to accept the request and therefore throws away all the request information. The response then also must be sent unencrypted, and contains just the minimum of information required (just the rejecter's id).
For simplicity's sake, the details of queueing and retrying the sending of these messages is not detailed here, nor is the saving, retrieval and deletion of the messages using the database.
This is the more usual flow for contact establishment - the request is sent as before, but this time the recipient is happy to accept the request.
When the receiver of the request accepts contact, the requester's information is stored in the database and their public key is added to the keyring. This then allows the contact acceptance message to be sent encrypted and signed back to the requester. When the requester receives the acceptance message, they also update their database with the user's details, and add the public key to their keyring too.
At the end of this exchange, the two users have established contact with each other, and have each other's public keys so they can exchange encrypted and signed messages to each other. However, the keys have not yet been verified, so the users see each other with status "untrusted".
Comparing the key signatures is an important step in verifying the identities of one's contacts, but it cannot be done using Murmeli message sequences because that wouldn't provide any reliable verification. Instead, a separate channel has to be used, such as a telephone call, to exchange the key signature words.
This scenario covers the notification messages send between trusted friends (after key verification has taken place) to inform each other that they are online. When one user comes online, the Murmeli client attempts to send a notification to each of its trusted friends.
When the ping is successfully sent, both the sender and recipient of the message know that the other is online, so they both update the status of the partner (and themselves) as now known to be online. Furthermore the receiver replies to the notification (because it was a 'ping') with its own status notification message (this time a 'pong').
The 'pong' message includes the hash of the current profile, and when this hash is compared in this example, the Murmeli client realises that something in the profile must have changed. Therefore it automatically sends an information request message to get the full profile details. This in turn triggers an information response message including all the profile information, including the avatar picture. This is then unpacked by Murmeli and stored in the database, ready to be viewed.
Of course, if the profile hash matches the one already stored, then no information request or response messages are sent. And it's also possible that both profiles are out-of-date (or both missing), in which case at least 8 messages will be sent (2 sets of these four-message chains).
Previously the profile hash was also calculated and sent with each 'ping', but this has now been removed, so that only 'pongs' include the profile hash. Another change is that robots no longer send any 'pongs' when they receive 'pings', to reduce the unnecessary traffic. The robot profile doesn't contain any useful information anyway, and successful sending of a 'ping' is sufficient to know whether the robot is online or not.
This is the case when a user wants to send a message to one of their contacts, and luckily that contact is currently online. This means that the message can be sent directly. The recipient doesn't need to answer, so the sequence has only one message.
This is the case when a user wants to send a message to one of their contacts, but that contact is currently not available. Murmeli first tries to send it directly, but this fails, and the message stays in the outbox. Then, Murmeli looks to see if any of its other, trusted friends are online, and if so, it sends a signed relay message to that friend.
The relay, shown in the middle, receives the message and checks the signature. It can't read the message though, because it's encrypted and only the final recipient has the corresponding key. So the message is saved in the outbox and queued for sending later. Note that the original sender also still has the same message in their outbox too.
In this example, the original sender goes temporarily offline, and the intended recipient comes online. The relay then succeeds in sending the message to the final recipient, who decrypts it and saves it in their inbox. The relay has now finished with the message and so can delete it.
Finally, the original sender comes back online, and resumes trying to send its message. This time it succeeds, and so the message is removed from the outbox. However, the recipient checks the hash and realises that this particular message has already been received, so it can safely discard this additional copy.
Note that for the users of Murmeli, it was not obvious that the message should be relayed, and in particular the relaying user was not informed that anything had taken place. The recipient can see that a message was received, but is only told from whom the message was sent, not the relay path it took. It remains an open question whether the sender is told that the message has been successfully sent, because the sender has no way to know whether the relay has sent its copy.
The mechanism described above for establishing contacts has the significant weakness that it relies on unencrypted introduction messages and therefore opens the door to potential unwanted spam. If such unverified, unencrypted messages are accepted, then anyone can send one. So it would be nice if Murmeli offered an alternative mechanism using signed introductions or "referrals".
In this example, one Murmeli user identifies that two of their contacts do not know each other yet, and chooses to introduce them to each other. Because they are trusted friends, these introductions, or "contact referrals" can be securely signed and encrypted, making it a better way to exchange public keys.
When the first Murmeli user chooses to refer two of their contacts to each other, two messages (both signed and encrypted) are sent, including the corresponding public keys and an introduction message. These appear to the recipients in their messages view in a similar way to the contact request messages described above, and can be accepted or rejected.
In the example shown here, one of the recipients chooses to accept the request, and adds the supplied public key to the keyring. They also send a (signed and encrypted) contact response message to the new contactee, but this message is not yet processed. Only at some later interval does this Murmeli user choose to accept the contact referral message, thereby also adding the supplied key to their keyring, and can then verify the signed contact response. Here another contact response is sent in reply, and then both users are synchronized with each other. The keyrings are complete, the keys having been securely exchanged, and the database profiles are set up. Each user still has the other listed as "untrusted", however, because the key signatures haven't been verified (see "Key verification" above). One could argue that this key signature verification is unnecessary using this signed referral mechanism but it is still a useful confirmation and so it is still required.