Merge pull request #175 from openpgpjs/async-api

Async api

src/openpgp.js

@@ -37,21 +37,40 @@ var armor = require('./encoding/armor.js'),
   config = require('./config'),
   message = require('./message.js'),
   cleartext = require('./cleartext.js'),
-  key = require('./key.js');
+  key = require('./key.js'),
+  AsyncProxy = require('./worker/async_proxy.js');
 
+var asyncProxy; // instance of the asyncproxy
+
+/**
+ * Set the path for the web worker script and create an instance of the async proxy
+ * @param {String} path relative path to the worker scripts
+ */
+function initWorker(path) {
+  asyncProxy = new AsyncProxy(path);
+}
 
 /**
  * Encrypts message text with keys
  * @param  {Array<module:key~Key>}  keys array of keys, used to encrypt the message
  * @param  {String} text message as native JavaScript string
+ * @param  {function} callback (optional) callback(error, result) for async style
  * @return {String}      encrypted ASCII armored message
  * @static
  */
-function encryptMessage(keys, text) {
-  var msg = message.fromText(text);
-  msg = msg.encrypt(keys);
-  var armored = armor.encode(enums.armor.message, msg.packets.write());
-  return armored;
+function encryptMessage(keys, text, callback) {
+  if (useWorker(callback)) {
+    asyncProxy.encryptMessage(keys, text, callback);
+    return;
+  }
+
+  return execute(function() {
+    var msg, armored;
+    msg = message.fromText(text);
+    msg = msg.encrypt(keys);
+    armored = armor.encode(enums.armor.message, msg.packets.write());
+    return armored;
+  }, callback);
 }
 
 /**
@@ -59,80 +78,121 @@ function encryptMessage(keys, text) {
  * @param  {Array<module:key~Key>}  publicKeys array of keys, used to encrypt the message
  * @param  {module:key~Key}    privateKey private key with decrypted secret key data for signing
  * @param  {String} text       message as native JavaScript string
+ * @param  {function} callback (optional) callback(error, result) for async style
  * @return {String}            encrypted ASCII armored message
  * @static
  */
-function signAndEncryptMessage(publicKeys, privateKey, text) {
-  var msg = message.fromText(text);
-  msg = msg.sign([privateKey]);
-  msg = msg.encrypt(publicKeys);
-  var armored = armor.encode(enums.armor.message, msg.packets.write());
-  return armored;
+function signAndEncryptMessage(publicKeys, privateKey, text, callback) {
+  if (useWorker(callback)) {
+    asyncProxy.signAndEncryptMessage(publicKeys, privateKey, text, callback);
+    return;
+  }
+
+  return execute(function() {
+    var msg, armored;
+    msg = message.fromText(text);
+    msg = msg.sign([privateKey]);
+    msg = msg.encrypt(publicKeys);
+    armored = armor.encode(enums.armor.message, msg.packets.write());
+    return armored;
+  }, callback);
 }
 
 /**
  * Decrypts message
  * @param  {module:key~Key}     privateKey private key with decrypted secret key data
- * @param  {module:message~Message} message    the message object with the encrypted data
+ * @param  {module:message~Message} msg    the message object with the encrypted data
+ * @param  {function} callback (optional) callback(error, result) for async style
  * @return {(String|null)}        decrypted message as as native JavaScript string
  *                              or null if no literal data found
  * @static
  */
-function decryptMessage(privateKey, message) {
-  message = message.decrypt(privateKey);
-  return message.getText();
+function decryptMessage(privateKey, msg, callback) {
+  if (useWorker(callback)) {
+    asyncProxy.decryptMessage(privateKey, msg, callback);
+    return;
+  }
+
+  return execute(function() {
+    msg = msg.decrypt(privateKey);
+    return msg.getText();
+  }, callback);
 }
 
 /**
  * Decrypts message and verifies signatures
  * @param  {module:key~Key}     privateKey private key with decrypted secret key data
  * @param  {Array<module:key~Key>}   publicKeys public keys to verify signatures
- * @param  {module:message~Message} message    the message object with signed and encrypted data
+ * @param  {module:message~Message} msg    the message object with signed and encrypted data
+ * @param  {function} callback (optional) callback(error, result) for async style
  * @return {{text: String, signatures: Array<{keyid: module:type/keyid, valid: Boolean}>}}
  *                              decrypted message as as native JavaScript string
  *                              with verified signatures or null if no literal data found
  * @static
  */
-function decryptAndVerifyMessage(privateKey, publicKeys, message) {
-  var result = {};
-  message = message.decrypt(privateKey);
-  result.text = message.getText();
-  if (result.text) {
-    result.signatures = message.verify(publicKeys);
-    return result;
+function decryptAndVerifyMessage(privateKey, publicKeys, msg, callback) {
+  if (useWorker(callback)) {
+    asyncProxy.decryptAndVerifyMessage(privateKey, publicKeys, msg, callback);
+    return;
   }
-  return null;
+
+  return execute(function() {
+    var result = {};
+    msg = msg.decrypt(privateKey);
+    result.text = msg.getText();
+    if (result.text) {
+      result.signatures = msg.verify(publicKeys);
+      return result;
+    }
+    return null;
+  }, callback);
 }
 
 /**
  * Signs a cleartext message
  * @param  {Array<module:key~Key>}  privateKeys private key with decrypted secret key data to sign cleartext
  * @param  {String} text        cleartext
+ * @param  {function} callback (optional) callback(error, result) for async style
  * @return {String}             ASCII armored message
  * @static
  */
-function signClearMessage(privateKeys, text) {
-  var cleartextMessage = new cleartext.CleartextMessage(text);
-  cleartextMessage.sign(privateKeys);
-  return cleartextMessage.armor();
+function signClearMessage(privateKeys, text, callback) {
+  if (useWorker(callback)) {
+    asyncProxy.signClearMessage(privateKeys, text, callback);
+    return;
+  }
+
+  return execute(function() {
+    var cleartextMessage = new cleartext.CleartextMessage(text);
+    cleartextMessage.sign(privateKeys);
+    return cleartextMessage.armor();
+  }, callback);
 }
 
 /**
  * Verifies signatures of cleartext signed message
  * @param  {Array<module:key~Key>}            publicKeys public keys to verify signatures
- * @param  {module:cleartext~CleartextMessage} message    cleartext message object with signatures
+ * @param  {module:cleartext~CleartextMessage} msg    cleartext message object with signatures
+ * @param  {function} callback (optional) callback(error, result) for async style
  * @return {{text: String, signatures: Array<{keyid: module:type/keyid, valid: Boolean}>}}
  *                                       cleartext with status of verified signatures
  * @static
  */
-function verifyClearSignedMessage(publicKeys, message) {
-  var result = {};
-  if (!(message instanceof cleartext.CleartextMessage)) {
-    throw new Error('Parameter [message] needs to be of type CleartextMessage.');
+function verifyClearSignedMessage(publicKeys, msg, callback) {
+  if (useWorker(callback)) {
+    asyncProxy.verifyClearSignedMessage(publicKeys, msg, callback);
+    return;
   }
-  result.text = message.getText();
-  result.signatures = message.verify(publicKeys);
-  return result;
+
+  return execute(function() {
+    var result = {};
+    if (!(msg instanceof cleartext.CleartextMessage)) {
+      throw new Error('Parameter [message] needs to be of type CleartextMessage.');
+    }
+    result.text = msg.getText();
+    result.signatures = msg.verify(publicKeys);
+    return result;
+  }, callback);
 }
 
 /**
@@ -143,18 +203,71 @@ function verifyClearSignedMessage(publicKeys, message) {
  * @param {Integer} numBits    number of bits for the key creation. (should be 1024+, generally)
  * @param {String}  userId     assumes already in form of "User Name <username@email.com>"
  * @param {String}  passphrase The passphrase used to encrypt the resulting private key
+ * @param  {function} callback (optional) callback(error, result) for async style
  * @return {Object} {key: Array<module:key~Key>, privateKeyArmored: Array<String>, publicKeyArmored: Array<String>}
  * @static
  */
-function generateKeyPair(keyType, numBits, userId, passphrase) {
-  var result = {};
-  var newKey = key.generate(keyType, numBits, userId, passphrase);
-  result.key = newKey;
-  result.privateKeyArmored = newKey.armor();
-  result.publicKeyArmored = newKey.toPublic().armor();
+function generateKeyPair(keyType, numBits, userId, passphrase, callback) {
+  if (useWorker(callback)) {
+    asyncProxy.generateKeyPair(keyType, numBits, userId, passphrase, callback);
+    return;
+  }
+
+  return execute(function() {
+    var result = {};
+    var newKey = key.generate(keyType, numBits, userId, passphrase);
+    result.key = newKey;
+    result.privateKeyArmored = newKey.armor();
+    result.publicKeyArmored = newKey.toPublic().armor();
+    return result;
+  }, callback);
+}
+
+//
+// helper functions
+//
+
+/**
+ * Are we in a browser and do we support worker?
+ */
+function useWorker(callback) {
+  if (typeof window === 'undefined' || !window.Worker || typeof callback !== 'function') {
+    return false;
+  }
+
+  if (!asyncProxy) {
+    throw new Error('You need to set the worker path!');
+  }
+
+  return true;
+}
+
+/**
+ * Command pattern that handles async calls gracefully
+ */
+function execute(cmd, callback) {
+  var result;
+
+  try {
+    result = cmd();
+  } catch (err) {
+    if (callback) {
+      callback(err);
+      return;
+    }
+
+    throw err;
+  }
+
+  if (callback) {
+    callback(null, result);
+    return;
+  }
+
   return result;
 }
 
+exports.initWorker = initWorker;
 exports.encryptMessage = encryptMessage;
 exports.signAndEncryptMessage = signAndEncryptMessage;
 exports.decryptMessage = decryptMessage;

src/worker/worker.js

@@ -17,7 +17,7 @@
 
 window = {}; // to make UMD bundles work
 
-importScripts('openpgp.js');
+importScripts('openpgp.min.js');
 
 var MIN_SIZE_RANDOM_BUFFER = 40000;
 var MAX_SIZE_RANDOM_BUFFER = 60000;