Add JSDoc to Ratchet.js

Author: joebandenburg

src/Ratchet.js

@@ -31,12 +31,26 @@ const discontinuityBytes = new Uint8Array([0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0
     0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
     0xff]).buffer;
 
+/**
+ * A utility class for performing the Axolotl ratcheting.
+ *
+ * @param {Crypto} crypto
+ * @constructor
+ */
 function Ratchet(crypto) {
     const self = this;
 
     const hkdf = new HKDF(crypto);
 
-    self.deriveInitialRootAndChainKeys = co.wrap(function*(sessionVersion, agreements) {
+    /**
+     * Derive the main and sub ratchet states from the shared secrets derived from the handshake.
+     *
+     * @method
+     * @param {number} sessionVersion
+     * @param {Array.<ArrayBuffer>} agreements - an array of ArrayBuffers containing the shared secrets
+     * @return {Promise.<Object, Error>} the root and chain keys
+     */
+    this.deriveInitialRootKeyAndChain = co.wrap(function*(sessionVersion, agreements) {
         var secrets = [];
         if (sessionVersion >= 3) {
             secrets.push(discontinuityBytes);
@@ -52,7 +66,18 @@ function Ratchet(crypto) {
         };
     });
 
-    self.deriveNewRootAndChainKeys = co.wrap(function*(rootKey, theirEphemeralPublicKey, ourEphemeralPrivateKey) {
+    /**
+     * Derive the next main and sub ratchet states from the previous state.
+     * <p>
+     * This method "clicks" the Diffie-Hellman ratchet forwards.
+     *
+     * @method
+     * @param {ArrayBuffer} rootKey - the current root key
+     * @param {ArrayBuffer} theirEphemeralPublicKey - the receiving ephemeral/ratchet key
+     * @param {ArrayBuffer} ourEphemeralPrivateKey - our current ephemeral/ratchet key
+     * @return {Promise.<Object, Error>} the next root and chain keys
+     */
+    this.deriveNextRootKeyAndChain = co.wrap(function*(rootKey, theirEphemeralPublicKey, ourEphemeralPrivateKey) {
         var sharedSecret = yield crypto.calculateAgreement(theirEphemeralPublicKey, ourEphemeralPrivateKey);
         var derivedSecretBytes = yield hkdf.deriveSecretsWithSalt(sharedSecret, rootKey, whisperRatchet,
             ProtocolConstants.rootKeyByteCount + ProtocolConstants.chainKeyByteCount);
@@ -62,7 +87,29 @@ function Ratchet(crypto) {
         };
     });
 
-    self.deriveMessageKeys = co.wrap(function*(chainKey) {
+    //
+    /**
+     * Derive the next sub ratchet state from the previous state.
+     * <p>
+     * This method "clicks" the hash iteration ratchet forwards.
+     *
+     * @method
+     * @param {Chain} chain
+     * @return {Promise.<void, Error>}
+     */
+    this.clickSubRatchet = co.wrap(function*(chain) {
+        chain.index++;
+        chain.key = yield deriveNextChainKey(chain.key);
+    });
+
+    /**
+     * Derive the message keys from the chain key.
+     *
+     * @method
+     * @param {ArrayBuffer} chainKey
+     * @return {Promise.<object, Error>} an object containing the message keys.
+     */
+    this.deriveMessageKeys = co.wrap(function*(chainKey) {
         var messageKey = yield deriveMessageKey(chainKey);
         var keyMaterialBytes = yield hkdf.deriveSecrets(messageKey, whisperMessageKeys,
             ProtocolConstants.cipherKeyByteCount + ProtocolConstants.macKeyByteCount + ProtocolConstants.ivByteCount);
@@ -77,12 +124,6 @@ function Ratchet(crypto) {
         };
     });
 
-    // "clicks" the hash iteration ratchet forwards
-    self.clickSubRatchet = co.wrap(function*(chain) {
-        chain.index++;
-        chain.key = yield deriveNextChainKey(chain.key);
-    });
-
     var hmacByte = co.wrap(function*(key, byte) {
         return yield crypto.hmac(key, ArrayBufferUtils.fromByte(byte));
     });

src/Session.js

@@ -320,17 +320,23 @@ function Session(crypto, sessionStateList) {
      * @return {Promise.<Chain, Error>} the next chain for decryption
      */
     var clickMainRatchet = co.wrap(function*(sessionState, theirEphemeralPublicKey) {
-        var nextReceivingChain = yield ratchet.deriveNewRootAndChainKeys(sessionState.rootKey, theirEphemeralPublicKey,
-            sessionState.senderRatchetKeyPair.private);
+        var {
+            rootKey: theirRootKey,
+            chain: nextReceivingChain
+        } = yield ratchet.deriveNextRootKeyAndChain(sessionState.rootKey, theirEphemeralPublicKey,
+                sessionState.senderRatchetKeyPair.private);
         var ourNewEphemeralKeyPair = yield crypto.generateKeyPair();
-        var nextSendingChain = yield ratchet.deriveNewRootAndChainKeys(nextReceivingChain.rootKey,
-            theirEphemeralPublicKey, ourNewEphemeralKeyPair.private);
-        sessionState.rootKey = nextSendingChain.rootKey;
-        sessionState.addReceivingChain(theirEphemeralPublicKey, nextReceivingChain.chain);
+        var {
+            rootKey,
+            chain: nextSendingChain
+        } = yield ratchet.deriveNextRootKeyAndChain(theirRootKey,
+                theirEphemeralPublicKey, ourNewEphemeralKeyPair.private);
+        sessionState.rootKey = rootKey;
+        sessionState.addReceivingChain(theirEphemeralPublicKey, nextReceivingChain);
         sessionState.previousCounter = Math.max(sessionState.sendingChain.index - 1, 0);
-        sessionState.sendingChain = nextSendingChain.chain;
+        sessionState.sendingChain = nextSendingChain;
         sessionState.senderRatchetKeyPair = ourNewEphemeralKeyPair;
-        return nextReceivingChain.chain;
+        return nextReceivingChain;
     });
 
     Object.freeze(self);

src/SessionFactory.js

@@ -122,7 +122,7 @@ function SessionFactory(crypto, store) {
 
         var sessionState = yield initializeBobSession(bobParameters);
         sessionState.theirBaseKey = message.baseKey;
-        var { sessionStateList: sessionStateList } = yield getSessionStateListForIdentity(fromIdentity);
+        var { sessionStateList } = yield getSessionStateListForIdentity(fromIdentity);
         sessionStateList.addSessionState(sessionState);
         yield sessionStateList.save();
         yield store.putRemoteIdentity(fromIdentity, message.identityKey);
@@ -167,19 +167,25 @@ function SessionFactory(crypto, store) {
             agreements.push(crypto.calculateAgreement(parameters.theirOneTimePreKey,
                 parameters.ourBaseKeyPair.private));
         }
-        var receivingChain = yield ratchet.deriveInitialRootAndChainKeys(parameters.sessionVersion, yield agreements);
-        var sendingChain = yield ratchet.deriveNewRootAndChainKeys(receivingChain.rootKey, parameters.theirRatchetKey,
-            sendingRatchetKeyPair.private);
+        var {
+            rootKey: theirRootKey,
+            chain: receivingChain
+        } = yield ratchet.deriveInitialRootKeyAndChain(parameters.sessionVersion, yield agreements);
+        var {
+            rootKey,
+            chain: sendingChain
+        } = yield ratchet.deriveNextRootKeyAndChain(theirRootKey, parameters.theirRatchetKey,
+                sendingRatchetKeyPair.private);
 
         var sessionState = new SessionState({
             sessionVersion: parameters.sessionVersion,
             remoteIdentityKey: parameters.theirIdentityKey,
             localIdentityKey: parameters.ourIdentityKeyPair.public,
-            rootKey: sendingChain.rootKey,
-            sendingChain: sendingChain.chain,
+            rootKey: rootKey,
+            sendingChain: sendingChain,
             senderRatchetKeyPair: sendingRatchetKeyPair
         });
-        sessionState.addReceivingChain(parameters.theirRatchetKey, receivingChain.chain);
+        sessionState.addReceivingChain(parameters.theirRatchetKey, receivingChain);
         return sessionState;
     });
 
@@ -195,14 +201,17 @@ function SessionFactory(crypto, store) {
                 parameters.ourOneTimePreKeyPair.private));
         }
 
-        var sendingChain = yield ratchet.deriveInitialRootAndChainKeys(parameters.sessionVersion, yield agreements);
+        var {
+            rootKey,
+            chain: sendingChain
+        } = yield ratchet.deriveInitialRootKeyAndChain(parameters.sessionVersion, yield agreements);
 
         return new SessionState({
             sessionVersion: parameters.sessionVersion,
             remoteIdentityKey: parameters.theirIdentityKey,
             localIdentityKey: parameters.ourIdentityKeyPair.public,
-            rootKey: sendingChain.rootKey,
-            sendingChain: sendingChain.chain,
+            rootKey: rootKey,
+            sendingChain: sendingChain,
             senderRatchetKeyPair: parameters.ourRatchetKeyPair
         });
     });