Documentation and cleanups

README.md

@@ -1,25 +1,62 @@
 OpenPGP.js [![Build Status](https://travis-ci.org/openpgpjs/openpgpjs.svg?branch=master)](https://travis-ci.org/openpgpjs/openpgpjs)
 ==========
  
-[OpenPGP.js](http://openpgpjs.org/) is a Javascript implementation of the OpenPGP protocol. This is defined in [RFC 4880](http://tools.ietf.org/html/rfc4880).
+[OpenPGP.js](http://openpgpjs.org/) is a JavaScript implementation of the OpenPGP protocol. This is defined in [RFC 4880](http://tools.ietf.org/html/rfc4880).
 
 [![Saucelabs Test Status](https://saucelabs.com/browser-matrix/openpgpjs.svg)](https://saucelabs.com/u/openpgpjs)
  
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
+**Table of Contents**
 
-### Platform support
+- [OpenPGP.js](#openpgpjs)
+    - [Platform Support](#platform-support)
+    - [Performance](#performance)
+    - [Getting started](#getting-started)
+        - [Npm](#npm)
+        - [Bower](#bower)
+    - [Examples](#examples)
+        - [Set up](#set-up)
+        - [Encrypt and decrypt *Uint8Array* data with a password](#encrypt-and-decrypt-uint8array-data-with-a-password)
+        - [Encrypt and decrypt *String* data with PGP keys](#encrypt-and-decrypt-string-data-with-pgp-keys)
+        - [Generate new key pair](#generate-new-key-pair)
+        - [Lookup public key on HKP server](#lookup-public-key-on-hkp-server)
+        - [Upload public key to HKP server](#upload-public-key-to-hkp-server)
+        - [Sign and verify cleartext messages](#sign-and-verify-cleartext-messages)
+        - [Create and verify *detached* signatures](#create-and-verify-detached-signatures)
+    - [Documentation](#documentation)
+    - [Security Audit](#security-audit)
+    - [Security recommendations](#security-recommendations)
+    - [Development](#development)
+    - [How do I get involved?](#how-do-i-get-involved)
+    - [License](#license)
+    - [Resources](#resources)
 
-* OpenPGP.js v2.x is written in ES6 but is transpiled to ES5 using [Babel](https://babeljs.io/) to run in most environments. We support node.js v0.12+ and browsers that implement [window.crypto.getRandomValues](http://caniuse.com/#feat=getrandomvalues).
+<!-- markdown-toc end -->
 
-* The api uses ES6 promises which are available in [most modern browsers](http://caniuse.com/#feat=promises). If you need to support browsers that do not support Promises, fear not! There is a [polyfill](https://github.com/jakearchibald/es6-promise), which is included in our build. So no action required on your part!
+### Platform Support
 
-* For the OpenPGP HTTP Key Server (HKP) client the new [fetch api](http://caniuse.com/#feat=fetch) is used. There is a polyfill for both [browsers](https://github.com/github/fetch) and [node.js](https://github.com/bitinn/node-fetch) runtimes. The node module is included as a dependency if you install via npm, but we do not include the browser polyfill in our build. So you'll need to include it in your app if you intend to use the HKP client.
+* OpenPGP.js v3.x is written in ES7 but is transpiled to ES5 using [Babel](https://babeljs.io/) to run in most environments. We support Node.js v8+ and browsers that implement [window.crypto.getRandomValues](http://caniuse.com/#feat=getrandomvalues).
 
+* The API uses the Async/Await syntax introduced in ES7 to return Promise objects. Async functions are available in [most modern browsers](https://caniuse.com/#feat=async-functions). If you need to support older browsers, fear not! We use [core-js](https://github.com/zloirock/core-js) to polyfill new features so that no action is required on your part!
+
+* For the OpenPGP HTTP Key Server (HKP) client the new [fetch API](http://caniuse.com/#feat=fetch) is used. The module is polyfilled for [browsers](https://github.com/github/fetch) and is included as a dependency for [Node.js](https://github.com/bitinn/node-fetch) runtimes.
 
 ### Performance
 
+* Version 3.0.0 of the library introduces support for public-key cryptography using [elliptic curves](https://wiki.gnupg.org/ECC). We use native implementations on browsers and Node.js when available or [Elliptic](https://github.com/indutny/elliptic) when otherwise. Elliptic curve cryptography provides stronger security per bits of key, which allows for much faster operations. Currently the following curves are supported: ("Yes*" means "when available")
+
+>| Curve      | Encryption | Signature | Elliptic | NodeCrypto | WebCrypto |
+>|:---------- |:----------:|:---------:|:--------:|:----------:|:---------:|
+>| p256       | ECDH       | ECDSA     | Yes      | Yes*       | Yes*      |
+>| p384       | ECDH       | ECDSA     | Yes      | Yes*       | Yes*      |
+>| p521       | ECDH       | ECDSA     | Yes      | Yes*       | Yes*      |
+>| secp256k1  | ECDH       | ECDSA     | Yes      | Yes*       | No        |
+>| curve25519 | ECDH       | N/A       | Yes      | No         | No        |
+>| ed25519    | N/A        | EdDSA     | Yes      | No         | No        |
+
 * Version 2.x of the library has been built from the ground up with Uint8Arrays. This allows for much better performance and memory usage than strings.
 
-* If the user's browser supports [native WebCrypto](http://caniuse.com/#feat=cryptography) via the `window.crypto.subtle` api, this will be used. Under node.js the native [crypto module](https://nodejs.org/api/crypto.html#crypto_crypto) is used. This can be deactivated by setting `openpgp.config.use_native = false`.
+* If the user's browser supports [native WebCrypto](http://caniuse.com/#feat=cryptography) via the `window.crypto.subtle` API, this will be used. Under Node.js the native [crypto module](https://nodejs.org/API/crypto.html#crypto_crypto) is used. This can be deactivated by setting `openpgp.config.use_native = false`.
 
 * The library implements the [IETF proposal](https://tools.ietf.org/html/draft-ford-openpgp-format-00) for authenticated encryption [using native AES-GCM](https://github.com/openpgpjs/openpgpjs/pull/430). This makes symmetric encryption about 30x faster on supported platforms. Since the specification has not been finalized and other OpenPGP implementations haven't adopted it yet, the feature is currently behind a flag. You can activate it by setting `openpgp.config.aead_protect = true`. **Note: activating this setting can break compatibility with other OpenPGP implementations, so be careful if that's one of your requirements.**
 
@@ -41,7 +78,7 @@ Or just fetch a minified build under [dist](https://github.com/openpgpjs/openpgp
 
 ### Examples
 
-Here are some examples of how to use the v2.x api. For more elaborate examples and working code, please check out the [public api unit tests](https://github.com/openpgpjs/openpgpjs/blob/master/test/general/openpgp.js). If you're upgrading from v1.x it might help to check out the [documentation](https://github.com/openpgpjs/openpgpjs#documentation).
+Here are some examples of how to use the v2.x+ API. For more elaborate examples and working code, please check out the [public API unit tests](https://github.com/openpgpjs/openpgpjs/blob/master/test/general/openpgp.js). If you're upgrading from v1.x it might help to check out the [documentation](https://github.com/openpgpjs/openpgpjs#documentation).
 
 #### Set up
 
@@ -131,7 +168,7 @@ ECC keys:
 ```js
 var options = {
     userIds: [{ name:'Jon Smith', email:'jon@example.com' }], // multiple user IDs
-    curve: "curve25519",                                      // ECC curve (curve25519, p256, p384, p521, or secp256k1)
+    curve: "ed25519",                                         // ECC curve (curve25519, p256, p384, p521, or secp256k1)
     passphrase: 'super long and hard to guess secret'         // protects the private key
 };
 ```
@@ -267,6 +304,10 @@ To create your own build of the library, just run the following command after cl
 
     npm install && npm test
 
+For debugging browser errors, you can open `test/unittests.html` in a browser or, after running the following command, open [`http://localhost:3000/test/unittests.html`](http://localhost:3000/test/unittests.html):
+
+    grunt browsertest
+
 ### How do I get involved?
 
 You want to help, great! Go ahead and fork our repo, make your changes and send us a pull request.

src/config/config.js

@@ -16,16 +16,8 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 /**
- * This object contains configuration values.
+ * This object contains global configuration values.
  * @requires enums
- * @property {Integer} prefer_hash_algorithm
- * @property {Integer} encryption_cipher
- * @property {Integer} compression
- * @property {Boolean} show_version
- * @property {Boolean} show_comment
- * @property {Boolean} integrity_protect
- * @property {String} keyserver
- * @property {Boolean} debug If enabled, debug messages will be printed
  * @module config/config
  */
 
@@ -34,24 +26,56 @@
 import enums from '../enums.js';
 
 export default {
+  /** @property {Integer} prefer_hash_algorithm Default hash algorithm {@link module:enums.hash} */
   prefer_hash_algorithm: enums.hash.sha256,
+  /** @property {Integer} encryption_cipher Default encryption cipher {@link module:enums.symmetric} */
   encryption_cipher: enums.symmetric.aes256,
+  /** @property {Integer} compression Default compression algorithm {@link module:enums.compression} */
   compression: enums.compression.zip,
-  aead_protect: false, // use Authenticated Encryption with Additional Data (AEAD) protection for symmetric encryption (NOT INTEROPERABLE WITH OTHER OPENPGP IMPLEMENTATIONS)
+
-  integrity_protect: true, // use integrity protection for symmetric encryption
+  /**
-  ignore_mdc_error: false, // fail on decrypt if message is not integrity protected
+   * Use Authenticated Encryption with Additional Data (AEAD) protection for symmetric encryption.
-  checksum_required: false, // do not throw error when armor is missing a checksum
+   * **NOT INTEROPERABLE WITH OTHER OPENPGP IMPLEMENTATIONS**
-  verify_expired_keys: true, // allow signature verification with expired keys
+   * @property {Boolean} aead_protect
+   */
+  aead_protect:             false,
+  /** Use integrity protection for symmetric encryption
+   * @property {Boolean} integrity_protect */
+  integrity_protect:        true,
+  /** @property {Boolean} ignore_mdc_error Fail on decrypt if message is not integrity protected */
+  ignore_mdc_error:         false,
+  /** @property {Boolean} checksum_required Do not throw error when armor is missing a checksum */
+  checksum_required:        false,
+  /** @property {Boolean} verify_expired_keys Allow signature verification with expired keys */
+  verify_expired_keys:      true,
+  /** @property {Boolean} rsa_blinding */
   rsa_blinding:             true,
-  use_native: true, // use native node.js crypto and Web Crypto apis (if available)
+  /** Work-around for rare GPG decryption bug when encrypting with multiple passwords
-  zero_copy: false, // use transferable objects between the Web Worker and main thread
+   * Slower and slightly less secure
+   * @property {Boolean} password_collision_check
+   */
+  password_collision_check: false,
+
+  /** @property {Boolean} use_native Use native Node.js crypto and WebCrypto API's when available */
+  use_native:               true,
+  /** @property {Boolean} Use transferable objects between the Web Worker and main thread */
+  zero_copy:                false,
+  /** @property {Boolean} debug If enabled, debug messages will be printed */
   debug:                    false,
-  tolerant: true, // ignore unsupported/unrecognizable packets instead of throwing an error,
+  /** @property {Boolean} tolerant Ignore unsupported/unrecognizable packets instead of throwing an error */
-  password_collision_check: false, // work-around for rare GPG decryption bug when encrypting with multiple passwords. Slower and slightly less secure
+  tolerant:                 true,
+
+  /** @property {Boolean} show_version Whether to include {@link module:config/config.versionstring} in armored messages */
   show_version: true,
+  /** @property {Boolean} show_comment Whether to include {@link module:config/config.commentstring} in armored messages */
   show_comment: true,
+  /** @property {String} versionstring A version string to be included in armored messages */
   versionstring: "OpenPGP.js VERSION",
+  /** @property {String} commentstring A comment string to be included in armored messages */
   commentstring: "https://openpgpjs.org",
+
+  /** @property {String} keyserver */
   keyserver:     "https://keyserver.ubuntu.com",
-  node_store: './openpgp.store'
+  /** @property {String} node_store */
+  node_store:    "./openpgp.store"
 };

src/crypto/crypto.js

@@ -54,10 +54,10 @@ export default {
    * Encrypts data using the specified public key multiprecision integers
    * and the specified algorithm.
    * @param {module:enums.publicKey} algo Algorithm to be used (See {@link http://tools.ietf.org/html/rfc4880#section-9.1|RFC 4880 9.1})
-   * @param {Array<module:type/mpi|module:type/oid|module:type/kdf|module:type/ecdh_symkey>} publicParams Algorithm dependent params
+   * @param {Array<module:type/mpi|module:type/oid|module:type/kdf_params|module:type/ecdh_symkey>} publicParams Algorithm dependent params
    * @param {module:type/mpi} data Data to be encrypted as MPI
    * @param {String} fingerprint Recipient fingerprint
-   * @return {Array<module:type/mpi|module:type/oid|module:type/kdf|module:type/ecdh_symkey>} encrypted session key parameters
+   * @return {Array<module:type/mpi|module:type/oid|module:type/kdf_params|module:type/ecdh_symkey>} encrypted session key parameters
    */
   publicKeyEncrypt: async function(algo, publicParams, data, fingerprint) {
     var types = this.getEncSessionKeyParamTypes(algo);
@@ -100,7 +100,7 @@ export default {
    * Decrypts data using the specified public key multiprecision integers of the private key,
    * the specified secretMPIs of the private key and the specified algorithm.
    * @param {module:enums.publicKey} algo Algorithm to be used (See {@link http://tools.ietf.org/html/rfc4880#section-9.1|RFC 4880 9.1})
-   * @param {Array<module:type/mpi|module:type/oid|module:type/kdf} keyIntegers Algorithm dependent params
+   * @param {Array<module:type/mpi|module:type/oid|module:type/kdf_params>} keyIntegers Algorithm dependent params
    * @param {Array<module:type/mpi|module:type/ecdh_symkey>} dataIntegers encrypted session key parameters
    * @param {String} fingerprint Recipient fingerprint
    * @return {module:type/mpi} returns a big integer containing the decrypted data; otherwise null

src/enums.js

@@ -11,6 +11,7 @@ export default {
    * @readonly
    */
   curve: {
+    /** NIST P-256 Curve */
     "p256":                "p256",
     "P-256":               "p256",
     "secp256r1":           "p256",
@@ -19,6 +20,7 @@ export default {
     "2a8648ce3d030107":  "p256",
     "2A8648CE3D030107":  "p256",
 
+    /** NIST P-384 Curve */
     "p384":         "p384",
     "P-384":        "p384",
     "secp384r1":    "p384",
@@ -26,6 +28,7 @@ export default {
     "2b81040022": "p384",
     "2B81040022": "p384",
 
+    /** NIST P-521 Curve */
     "p521":         "p521",
     "P-521":        "p521",
     "secp521r1":    "p521",
@@ -33,17 +36,20 @@ export default {
     "2b81040023": "p521",
     "2B81040023": "p521",
 
+    /** SECP256k1 Curve */
     "secp256k1":    "secp256k1",
     "1.3.132.0.10": "secp256k1",
     "2b8104000a": "secp256k1",
     "2B8104000A": "secp256k1",
 
+    /** Ed25519 Curve */
     "ed25519":                "ed25519",
     "Ed25519":                "ed25519",
     "1.3.6.1.4.1.11591.15.1": "ed25519",
     "2b06010401da470f01":   "ed25519",
     "2B06010401DA470F01":   "ed25519",
 
+    /** Curve25519 */
     "cv25519":                "curve25519",
     "curve25519":             "curve25519",
     "Curve25519":             "curve25519",

src/message.js

@@ -143,8 +143,7 @@ Message.prototype.decrypt = async function(privateKey, sessionKey, password) {
  * Decrypt an encrypted session key either with a private key or a password.
  * @param  {Key} privateKey    (optional) private key with decrypted secret data
  * @param  {String} password   (optional) password used to decrypt
- * @return {Array}             array of object with potential sessionKey, algorithm pairs in the form:
+ * @return {Array<{ data:Uint8Array, algorithm:String }>} array of object with potential sessionKey, algorithm pairs
- *                               { data:Uint8Array, algorithm:String }
  */
 Message.prototype.decryptSessionKeys = function(privateKey, password) {
   var keyPackets = [];

src/openpgp.js

@@ -16,12 +16,12 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 /**
- * @requires ed6-promise
  * @requires message
  * @requires cleartext
  * @requires key
  * @requires config
  * @requires util
+ * @requires polyfills
  * @requires worker/async_proxy
  * @module openpgp
  */
@@ -409,7 +409,7 @@ export function encryptSessionKey({ data, algorithm, publicKeys, passwords }) {
  * @param  {Message} message              a message object containing the encrypted session key packets
  * @param  {Key} privateKey               (optional) private key with decrypted secret key data
  * @param  {String} password              (optional) a single password to decrypt the session key
- * @return {Promise<Object|undefined>}    decrypted session key and algorithm in object form:
+ * @return {Promise<Object|undefined>}    Array of decrypted session key, algorithm pairs in form:
  *                                          { data:Uint8Array, algorithm:String }
  *                                          or 'undefined' if no key packets found
  * @static

src/polyfills.js

@@ -1,36 +1,29 @@
+/* eslint-disable import/no-extraneous-dependencies */
 // Old browser polyfills
 // All are listed as dev dependencies because Node does not need them
 // and for browser babel will take care of it
 
 if (typeof window.fetch === 'undefined') {
-  // eslint-disable-next-line import/no-extraneous-dependencies
   require('whatwg-fetch');
 }
 if (typeof Array.prototype.fill === 'undefined') {
-  // eslint-disable-next-line import/no-extraneous-dependencies
   require('core-js/fn/array/fill');
 }
 if (typeof Array.prototype.find === 'undefined') {
-  // eslint-disable-next-line import/no-extraneous-dependencies
   require('core-js/fn/array/find');
 }
 if (typeof Array.from === 'undefined') {
-  // eslint-disable-next-line import/no-extraneous-dependencies
   require('core-js/fn/array/from');
 }
 if (typeof Promise === 'undefined') {
-  // eslint-disable-next-line import/no-extraneous-dependencies
   require('core-js/fn/promise');
 }
 if (typeof Uint8Array.from === 'undefined') {
-  // eslint-disable-next-line import/no-extraneous-dependencies
   require('core-js/fn/typed/uint8-array');
 }
 if (typeof String.prototype.repeat === 'undefined') {
-  // eslint-disable-next-line import/no-extraneous-dependencies
   require('core-js/fn/string/repeat');
 }
 if (typeof Symbol === 'undefined') {
-  // eslint-disable-next-line import/no-extraneous-dependencies
   require('core-js/fn/symbol');
 }

src/util.js

@@ -537,22 +537,7 @@ export default {
   },
 
   /**
-   * Wraps a generic synchronous function in an ES6 Promise.
+   * Converts an IE11 web crypto api result to a promise.
-   * @param  {Function} fn  The function to be wrapped
-   * @return {Function}     The function wrapped in a Promise
-   */
-  promisify: function(fn) {
-    return function() {
-      var args = arguments;
-      return new Promise(function(resolve) {
-        var result = fn.apply(null, args);
-        resolve(result);
-      });
-    };
-  },
-
-  /**
-   * Converts an IE11 web crypro api result to a promise.
    *   This is required since IE11 implements an old version of the
    *   Web Crypto specification that does not use promises.
    * @param  {Object} cryptoOp The return value of an IE11 web cryptro api call