joebandenburg/libaxolotl-javascript

A JavaScript implementation of axolotl. Axolotl is a ratcheting forward secrecy protocol.

This project is an independent implementation of Axolotl in JavaScript. It is not endorsed by Open Whisper Systems.

Axolotl is a ratcheting forward secrecy protocol that works in synchronous and asynchronous messaging environments. The protocol overview is available here, and the details of the TextSecure wire format are available here.

Currently this implementation only supports version 3 of the protocol.

WARNING: This implementation has not yet been independently audited. That means you should probably not use it.

Installation

Node.js

Install using npm:

$ npm install axolotl

and import using "axolotl":

var axolotl = require("axolotl");

Browser

Install using bower:

$ bower install axolotl

and import using AMD:

require(["axolotl"], function(axolotl) {

});

or without:

window.axolotl(...)

Getting started

Dependencies

libaxolotl-javascript depends on traceur-runtime and protobuf.js and cryptographic primitives. These dependencies are not included in the distributed package. If you installed libaxolotl-javascript using npm then there is nothing more you need to do - npm will download these dependencies for you.

If you are using libaxolotl-javascript in the browser, you will have to provide the library's dependencies yourself. If you're using AMD, then simply provide the location of these dependencies in your AMD configuration. Otherwise, include the dependencies on the page before including axolotl.js.

The Store interface

You need to provide an implementation of the Store interface when instantiating Axolotl. This is an object that has the following methods.

Note that all methods may return a Promise if the operation is asynchronous.

getLocalIdentityKeyPair

getLocalIdentityKeyPair() → {KeyPair}

Get the local identity key pair created at install time. A key pair is a JavaScript object containing the keys public and private which correspond to the public and private keys, respectively. These keys are of type ArrayBuffer.

getLocalRegistrationId

getLocalRegistrationId() → {Number}

Get the local registration identifier created at install time.

getLocalSignedPreKeyPair

getLocalSignedPreKeyPair(signedPreKeyId) → {KeyPair}

Get the local signed pre-key pair associated with the signedPreKeyId.

Parameters

Name	Type	Description
signedPreKeyId	Number	The identifier of the signed pre-key.

getLocalPreKeyPair

getLocalPreKeyPair(preKeyId) → {KeyPair}

Get the local pre-key pair associated with the preKeyId.

Parameters

Name	Type	Description
preKeyId	Number	The identifier of the pre-key.

Using Axolotl

Start by instantiating Axolotl:

var axol = axolotl(store);

When your application is first installed, the client will likely need to register with the server. To do this, a number of data needs to be generated:

axol.generateIdentityKeyPair().then(...); // Generate our identity key
axol.generateRegistrationId().then(...); // Generate our registration id
axol.generatePreKeys(0, 100).then(...); // Generate the first set of our pre-keys to send to the server
axol.generateLastResortPreKey().then(...); // Generate our last restore pre-key to send to the server
axol.generateSignedPreKey(identityKeyPair, 1).then(...); // Generate our first signed pre-key to send to the server

Once registered, sending messages is very simple:

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

and on the receiving side:

// When receiving a ciphertext, decide what type it is from the container and then decrypt
axol.decryptPreKeyWhisperMessage("alice", ciphertext).then(function(plaintext) {
    console.log(plaintext); // "Hello bob"
});

See Axolotl.js for more detailed API documentation.

libaxolotl-javascript's Issues

Please correct the documentation:Verify an Ed25519 signature Parameters

https://github.com/joebandenburg/libaxolotl-javascript/blob/master/doc/crypto.md

Name Type Description
privateKey ArrayBuffer The 33 byte public half of the key used to produce the signature.

Should be publicKey

Please confirm if your code is correct below: Should it be a agreements.push or agreements.concat ?

SessionFactory line 151:

    if (parameters.sessionVersion >= 3 && parameters.theirOneTimePreKey) {
        agreements.push(crypto.calculateAgreement(parameters.theirOneTimePreKey,
            parameters.ourBaseKeyPair.private));
    }

Should it be a agreements.push or agreements.concat ?

Are you adding to the end of agreements or the beginning?

Please compare with other implementations.

You can eliminate the extra call to Messages.decodePreKeyWhisperMessage(preKeyWhisperMessageBytes)

You can eliminate the extra call to Messages.decodePreKeyWhisperMessage(preKeyWhisperMessageBytes)

Since Axolot.decryptPreKeyWhisperMessage now calls sessionFactory.createSessionFromPreKeyWhisperMessage(session, preKeyWhisperMessageBytes) directly

[question] debugging es6

@joebandenburg i like the modern code style. How do you debug without having to wade through garbled transpiled code?

reference Store implementation

I am working on using libaxolotl in my project Grd Me and as a beginner at JS, I feel uncertain about my Store implementation. I totally understand separating the store code from libaxolotl, as per #6, but would you be willing to submit a reference Store implementation that others can build off of?

Add test vectors

We should have some tests that use specific inputs and compare the output with known values derived from another working implementation. This will help prove that the implementation is correct and compatible with other implementations. This should be done both at the API level and the unit level.

A challenge for this testing approach is the need to use the correct cryptographic primitives, including Curve25519.

Support key exchange session initialisation

Not sure if this even makes sense without an SMS transport available. Need to investigate.

Documentation should explain Session lifecycle

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

handlePreKeyWhisperMessage does not return any results

Hi,
I'm trying to use axolotl to open an encrypted message and I believe I'm missing something. I have created a class that implements store interface with all the mandatory methods. The axolotl is used like this:

function LiteAxolotlStore() {
    this.db = new JsonDB('/tmp/whatsapp', true, true);
    this.identityKeyStore = new LiteIdentityKeyStore(this.db);

    // This is axol instance with mandatory methods
    this.axol = axolotl(this.identityKeyStore);

}

This class is called by another one later like this:

function AxolotlLayer() {
    this.store = new LiteAxolotlStore();
}

Then I use it to unencrypt and incoming pkmsg like this:

AxolotlLayer.prototype.handlePreKeyWhisperMessage = function(node, callback) {
    var context = this;
    var from = node.attribute('from');
    var data = node.child('enc').data();

      this.store.axol.decryptPreKeyWhisperMessage(from, data).then(function(plaintext, err) {
  
        if (err) {
            console.error("AXOLOTL: Decryption error!");
            console.error(err);
        } else {
            console.log("AXOLOTL: Decryption completed!");
            console.log(plaintext);

            if (node.child('enc').attribute('v') == 2) {
                plaintext = context.unpadV2Plaintext(plaintext);
            }

            // Execute callback to send the message
            callback(plaintext);
        }
    });
};

The problem is: nothing happens when I call decryptPreKeyWhisperMessage. It does not write anything to log, neither show any error messages. Can you tell me what am I missing? How can I debug decryptPreKeyWhisperMessage?

Why is it so hard to use in a browser ?

I can't install it.

I tried npm in the repository folder - it returns:

I tried with bower and it installed it, but I can't install traceur proparly.
Any tips or advice ? it realy shouldn't be that hard...

Serializing Session object

Hello Joe,

I've been working on integrating end-to-end encryption in our node-whatsapi project. I'm using your implementation of axolotl and this works great! I'm at the point that it's able to send encrypted messages that can be decrypted by an official WhatsApp client (App). So far so good.

As part of the implementation I've created a Keystore as required by the javascript-axolotl lib. We're using SQLite for persisting the data. In order to do this I have to serialize some objects (KeyPairs, Session, etc). Currently I'm looking into the best way of serializing the Session object to be able to store (and recorver) from SQLite. I hoped that I could use the protobuf definition for LocalStorageProtocols as supplied in the TexSecure code (just like you did with the WhisperTextProtocols), but the Session object in javascript-axolotl seems to differ from the protobuf definition. Is this intentionally?

Do you have any pointers on how you would proceed with serializing the Session object?

Best regards,

Tom van der Geer

Support protocol version 2

It would be good to be interoperable with older clients. Although it would be worth finding out if there are many version 2 clients out there before starting on this.

Please check SessionFactory->createSessionFromPreKeyBundle() line 74

Hi,
var sessionStateList = new SessionStateList((serialisedState) => { return store.putSession(toIdentity, serialisedState); });

you never initialize serialisedState prior to this call.
I've been trying to figure out what exactly you are doing here?

Handle simultaneous session initiation

Other clients handle the case where both parties attempt to initiate sessions simultaneously.

This will require good test coverage. See SimultaneousInitiateTests.java from libaxolotl-android for ideas.

To support this we may need to store previous sessions and try using them to decrypt messages. It also probably means the API needs to be changed to make it more convenient for the user.

Missing STORE methods ?

Hi,
I've seen the more detailed Read-me, but the following is still unclear:
axol.generateIdentityKeyPair().then(...); // Generate our identity key axol.generateRegistrationId().then(...); // Generate our registration id axol.generatePreKeys(0, 100).then(...); // Generate the first set of our pre-keys to send to the server axol.generateLastResortPreKey().then(...); // Generate our last restore pre-key to send to the server axol.generateSignedPreKey(identityKeyPair, 1).then(...); // Generate our first signed pre-key to send to the server
Where do you perform local storage of these?

I believe your STORE should implement local storage of these as well, else where will the equivalent Store.getXXX variants for these methods pick data from?