Documentation should explain Session lifecycle

[dcposch]

Currently, the example in the README doesn't actually work:

var message = convertStringToBytes("Hello bob");
axol.encryptMessage("bob", message).then(function(ciphertext) {
    // Send ciphertext to alice
});

As far as I can tell, encryptMessage takes a Session, not a string. I think it would be useful to explain how to create sessions.

As far as I can tell, there are two scenarios in which you have to create a new Session. In both cases you're communicating with a new person for the first time.

Scenario 1: I want to send someone a message. I get one of their prekeys from the key exchange server. What exactly does the server give me? How do I create a Session now?

In other words, we should have an example that shows how to use createSessionFromPreKeyBundle.

Scenario 2: Someone else just sent me a message. It contains the ID of one of my prekeys (whichever one they used), their own prekey, and an encrypted payload. How do I decrypt their message?

In other words, we should have an example that shows how to use decryptPreKeyWhisperMessage.

While we're at it, we should describe what goes into a PreKeyBundle.

If I have time I'll try to send a PR with documentation improvements.

For anyone who's reading this and wants more details about how the protocol works, see:

• https://github.com/trevp/axolotl/wiki
• https://github.com/WhisperSystems/Signal-Android/wiki/ProtocolV2

[joebandenburg]

Yes, the documentation is indeed out of date. This would be great to fix. I think your suggestions are good.