diff --git a/.eslintrc.js b/.eslintrc.js index 8c53889f..f142cfe0 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -307,7 +307,6 @@ module.exports = { "error", "never" ], - "valid-jsdoc": "off", "wrap-iife": "error", "wrap-regex": "off", "yield-star-spacing": "error", @@ -338,6 +337,7 @@ module.exports = { "indent": [ 0, 2, { "SwitchCase": 1 } ], // TODO Consider fixing these: + "valid-jsdoc": 0, "new-cap": [ 0, { "properties": false, "capIsNewExceptionPattern": "^type_.*" }], "no-lonely-if": 0, "no-fallthrough": 0, diff --git a/Gruntfile.js b/Gruntfile.js index 6e61f5de..2714535f 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -1,29 +1,5 @@ module.exports = function(grunt) { - var lintFiles = [ - 'src/config/**/*.js', - 'src/crypto/cipher/aes.js', - 'src/crypto/cipher/blowfish.js', - 'src/crypto/cipher/cast5.js', - 'src/crypto/cipher/des.js', - 'src/crypto/cipher/index.js', - 'src/crypto/hash/index.js', - 'src/crypto/hash/md5.js', - 'src/crypto/public_key/dsa.js', - 'src/crypto/public_key/elgamal.js', - 'src/crypto/public_key/index.js', - 'src/crypto/public_key/rsa.js', - 'src/crypto/public_key/elliptic/*.js', - 'src/crypto/*.js', - 'src/encoding/**/*.js', - 'src/hkp/**/*.js', - 'src/keyring/**/*.js', - 'src/packet/**/*.js', - 'src/type/**/*.js', - 'src/worker/**/*.js', - 'src/*.js' - ]; // add more over time ... goal should be 100% coverage - var version = grunt.option('release'); var fs = require('fs'); var browser_capabilities; @@ -179,7 +155,7 @@ module.exports = function(grunt) { } }, eslint: { - target: lintFiles, + target: ['src/**/*.js'], options: { configFile: '.eslintrc.js' } }, jsdoc: { diff --git a/README.md b/README.md index e4ad51dd..7ae0a4de 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ openpgp.encrypt(options).then(function(ciphertext) { ```js options = { message: openpgp.message.read(encrypted), // parse encrypted bytes - password: 'secret stuff', // decrypt with password + passwords: ['secret stuff'], // decrypt with password format: 'binary' // output as Uint8Array }; @@ -131,12 +131,12 @@ var privkey = '-----BEGIN PGP PRIVATE KEY BLOCK ... END PGP PRIVATE KEY BLOCK--- var passphrase = 'secret passphrase'; //what the privKey is encrypted with var privKeyObj = openpgp.key.readArmored(privkey).keys[0]; -privKeyObj.decrypt(passphrase); +await privKeyObj.decrypt(passphrase); options = { data: 'Hello, World!', // input as String (or Uint8Array) publicKeys: openpgp.key.readArmored(pubkey).keys, // for encryption - privateKeys: privKeyObj // for signing (optional) + privateKeys: [privKeyObj] // for signing (optional) }; openpgp.encrypt(options).then(function(ciphertext) { @@ -148,7 +148,7 @@ openpgp.encrypt(options).then(function(ciphertext) { options = { message: openpgp.message.readArmored(encrypted), // parse armored message publicKeys: openpgp.key.readArmored(pubkey).keys, // for verification (optional) - privateKey: privKeyObj // for decryption + privateKeys: [privKeyObj] // for decryption }; openpgp.decrypt(options).then(function(plaintext) { @@ -171,9 +171,7 @@ options = { compression: openpgp.enums.compression.zip // compress the data with zip }; -openpgp.encrypt(options).then(function(ciphertext) { - // use ciphertext -}); +ciphertext = await openpgp.encrypt(options); // use ciphertext ``` Or, override the config to enable compression: @@ -200,10 +198,15 @@ var options = { ``` ECC keys: + +Possible values for curve are curve25519, ed25519, p256, p384, p521, or secp256k1. +Note that options both curve25519 and ed25519 generate a primary key for signing using Ed25519 +and a subkey for encryption using Curve25519. + ```js var options = { userIds: [{ name:'Jon Smith', email:'jon@example.com' }], // multiple user IDs - curve: "ed25519", // ECC curve (curve25519, p256, p384, p521, or secp256k1) + curve: "ed25519", // ECC curve name passphrase: 'super long and hard to guess secret' // protects the private key }; ``` @@ -249,13 +252,13 @@ var privkey = '-----BEGIN PGP PRIVATE KEY BLOCK ... END PGP PRIVATE KEY BLOCK--- var passphrase = 'secret passphrase'; //what the privKey is encrypted with var privKeyObj = openpgp.key.readArmored(privkey).keys[0]; -privKeyObj.decrypt(passphrase); +await privKeyObj.decrypt(passphrase); ``` ```js options = { data: 'Hello, World!', // input as String (or Uint8Array) - privateKeys: privKeyObj // for signing + privateKeys: [privKeyObj] // for signing }; openpgp.sign(options).then(function(signed) { @@ -287,13 +290,13 @@ var privkey = '-----BEGIN PGP PRIVATE KEY BLOCK ... END PGP PRIVATE KEY BLOCK--- var passphrase = 'secret passphrase'; //what the privKey is encrypted with var privKeyObj = openpgp.key.readArmored(privkey).keys[0]; -privKeyObj.decrypt(passphrase); +await privKeyObj.decrypt(passphrase); ``` ```js options = { data: 'Hello, World!', // input as String (or Uint8Array) - privateKeys: privKeyObj, // for signing + privateKeys: [privKeyObj], // for signing detached: true }; diff --git a/src/cleartext.js b/src/cleartext.js index a794319a..99450b5a 100644 --- a/src/cleartext.js +++ b/src/cleartext.js @@ -38,7 +38,6 @@ import { createVerificationObjects, createSignaturePackets } from './message'; * @param {String} text The cleartext of the signed message * @param {module:signature} signature The detached signature or an empty signature if message not yet signed */ - export function CleartextMessage(text, signature) { if (!(this instanceof CleartextMessage)) { return new CleartextMessage(text, signature); @@ -53,7 +52,7 @@ export function CleartextMessage(text, signature) { /** * Returns the key IDs of the keys that signed the cleartext message - * @return {Array} array of keyid objects + * @returns {Array} array of keyid objects */ CleartextMessage.prototype.getSigningKeyIds = function() { const keyIds = []; @@ -69,7 +68,8 @@ CleartextMessage.prototype.getSigningKeyIds = function() { * @param {Array} privateKeys private keys with decrypted secret key data for signing * @param {Signature} signature (optional) any existing detached signature * @param {Date} date (optional) The creation time of the signature that should be created - * @return {module:message~CleartextMessage} new cleartext message with signed content + * @returns {Promise} new cleartext message with signed content + * @async */ CleartextMessage.prototype.sign = async function(privateKeys, signature=null, date=new Date()) { return new CleartextMessage(this.text, await this.signDetached(privateKeys, signature, date)); @@ -80,7 +80,8 @@ CleartextMessage.prototype.sign = async function(privateKeys, signature=null, da * @param {Array} privateKeys private keys with decrypted secret key data for signing * @param {Signature} signature (optional) any existing detached signature * @param {Date} date (optional) The creation time of the signature that should be created - * @return {module:signature~Signature} new detached signature of message content + * @returns {Promise} new detached signature of message content + * @async */ CleartextMessage.prototype.signDetached = async function(privateKeys, signature=null, date=new Date()) { const literalDataPacket = new packet.Literal(); @@ -93,7 +94,8 @@ CleartextMessage.prototype.signDetached = async function(privateKeys, signature= * Verify signatures of cleartext signed message * @param {Array} keys array of keys to verify signatures * @param {Date} date (optional) Verify the signature against the given date, i.e. check signature creation time < date < expiration time - * @return {Array<{keyid: module:type/keyid, valid: Boolean}>} list of signer's keyid and validity of signature + * @returns {Promise>} list of signer's keyid and validity of signature + * @async */ CleartextMessage.prototype.verify = function(keys, date=new Date()) { return this.verifyDetached(this.signature, keys, date); @@ -103,7 +105,8 @@ CleartextMessage.prototype.verify = function(keys, date=new Date()) { * Verify signatures of cleartext signed message * @param {Array} keys array of keys to verify signatures * @param {Date} date (optional) Verify the signature against the given date, i.e. check signature creation time < date < expiration time - * @return {Array<{keyid: module:type/keyid, valid: Boolean}>} list of signer's keyid and validity of signature + * @returns {Promise>} list of signer's keyid and validity of signature + * @async */ CleartextMessage.prototype.verifyDetached = function(signature, keys, date=new Date()) { const signatureList = signature.packets; @@ -115,7 +118,7 @@ CleartextMessage.prototype.verifyDetached = function(signature, keys, date=new D /** * Get cleartext - * @return {String} cleartext of message + * @returns {String} cleartext of message */ CleartextMessage.prototype.getText = function() { // normalize end of line to \n @@ -124,7 +127,7 @@ CleartextMessage.prototype.getText = function() { /** * Returns ASCII armored text of cleartext signed message - * @return {String} ASCII armor + * @returns {String} ASCII armor */ CleartextMessage.prototype.armor = function() { let hashes = this.signature.packets.map(function(packet) { @@ -143,7 +146,7 @@ CleartextMessage.prototype.armor = function() { /** * reads an OpenPGP cleartext signed message and returns a CleartextMessage object * @param {String} armoredText text to be parsed - * @return {module:cleartext~CleartextMessage} new cleartext message object + * @returns {module:cleartext~CleartextMessage} new cleartext message object * @static */ export function readArmored(armoredText) { diff --git a/src/config/config.js b/src/config/config.js index 4747b793..8af675bf 100644 --- a/src/config/config.js +++ b/src/config/config.js @@ -21,7 +21,7 @@ * @module config/config */ -import enums from '../enums.js'; +import enums from '../enums'; export default { /** @property {Integer} prefer_hash_algorithm Default hash algorithm {@link module:enums.hash} */ diff --git a/src/config/index.js b/src/config/index.js index b5c0d2c5..e76ff337 100644 --- a/src/config/index.js +++ b/src/config/index.js @@ -1,4 +1,5 @@ /** + * @fileoverview This object contains global configuration values. * @see module:config/config * @module config */ diff --git a/src/config/localStorage.js b/src/config/localStorage.js index af3823d5..1bf61a1b 100644 --- a/src/config/localStorage.js +++ b/src/config/localStorage.js @@ -1,12 +1,12 @@ /** - * This object storing and retrieving configuration from HTML5 local storage. * @module config/localStorage */ /** + * This object is used for storing and retrieving configuration from HTML5 local storage. * @constructor */ -export default function LocalStorage() {} +function LocalStorage() {} /** * Reads the config out of the HTML5 local storage @@ -30,3 +30,5 @@ LocalStorage.prototype.read = function () { LocalStorage.prototype.write = function () { window.localStorage.setItem("config", JSON.stringify(this.config)); }; + +export default LocalStorage; diff --git a/src/crypto/cfb.js b/src/crypto/cfb.js index 93245917..e71446dd 100644 --- a/src/crypto/cfb.js +++ b/src/crypto/cfb.js @@ -40,7 +40,7 @@ export default { * IV should be used or not. The encrypteddatapacket uses the * "old" style with a resync. Encryption within an * encryptedintegrityprotecteddata packet is not resyncing the IV. - * @return {Uint8Array} encrypted data + * @returns {Uint8Array} encrypted data */ encrypt: function(prefixrandom, cipherfn, plaintext, key, resync) { cipherfn = new cipher[cipherfn](key); @@ -133,7 +133,7 @@ export default { * @param {Uint8Array} key Uint8Array representation of key to be used to check the mdc * This will be passed to the cipherfn * @param {Uint8Array} ciphertext The encrypted data - * @return {Uint8Array} plaintext Data of D(ciphertext) with blocksize length +2 + * @returns {Uint8Array} plaintext Data of D(ciphertext) with blocksize length +2 */ mdc: function(cipherfn, key, ciphertext) { cipherfn = new cipher[cipherfn](key); @@ -175,7 +175,7 @@ export default { * IV should be used or not. The encrypteddatapacket uses the * "old" style with a resync. Decryption within an * encryptedintegrityprotecteddata packet is not resyncing the IV. - * @return {Uint8Array} the plaintext data + * @returns {Uint8Array} the plaintext data */ decrypt: function(cipherfn, key, ciphertext, resync) { diff --git a/src/crypto/cipher/aes.js b/src/crypto/cipher/aes.js index e23d513a..2049879d 100644 --- a/src/crypto/cipher/aes.js +++ b/src/crypto/cipher/aes.js @@ -6,7 +6,7 @@ import { AES_ECB } from 'asmcrypto.js/src/aes/ecb/exports'; // TODO use webCrypto or nodeCrypto when possible. -export default function aes(length) { +function aes(length) { const c = function(key) { this.key = Uint8Array.from(key); @@ -26,3 +26,5 @@ export default function aes(length) { return c; } + +export default aes; diff --git a/src/crypto/cipher/blowfish.js b/src/crypto/cipher/blowfish.js index aa5ec826..35c476e5 100644 --- a/src/crypto/cipher/blowfish.js +++ b/src/crypto/cipher/blowfish.js @@ -388,7 +388,7 @@ Blowfish.prototype.init = function(key) { // added by Recurity Labs -export default function BF(key) { +function BF(key) { this.bf = new Blowfish(); this.bf.init(key); @@ -396,5 +396,8 @@ export default function BF(key) { return this.bf.encrypt_block(block); }; } + BF.keySize = BF.prototype.keySize = 16; BF.blockSize = BF.prototype.blockSize = 16; + +export default BF; diff --git a/src/crypto/cipher/cast5.js b/src/crypto/cipher/cast5.js index fd423f83..1304c277 100644 --- a/src/crypto/cipher/cast5.js +++ b/src/crypto/cipher/cast5.js @@ -597,7 +597,7 @@ function OpenpgpSymencCast5() { ); } -export default function Cast5(key) { +function Cast5(key) { this.cast5 = new OpenpgpSymencCast5(); this.cast5.setKey(key); @@ -608,3 +608,5 @@ export default function Cast5(key) { Cast5.blockSize = Cast5.prototype.blockSize = 8; Cast5.keySize = Cast5.prototype.keySize = 16; + +export default Cast5; diff --git a/src/crypto/cipher/index.js b/src/crypto/cipher/index.js index 9b754c04..0f11a73d 100644 --- a/src/crypto/cipher/index.js +++ b/src/crypto/cipher/index.js @@ -1,4 +1,5 @@ /** + * @fileoverview Symmetric cryptography functions * @requires crypto/cipher/aes * @requires crypto/cipher/des * @requires crypto/cipher/cast5 diff --git a/src/crypto/cipher/twofish.js b/src/crypto/cipher/twofish.js index 5ad10c01..1602ff23 100644 --- a/src/crypto/cipher/twofish.js +++ b/src/crypto/cipher/twofish.js @@ -337,7 +337,7 @@ function createTwofish() { // added by Recurity Labs -export default function TF(key) { +function TF(key) { this.tf = createTwofish(); this.tf.open(toArray(key), 0); @@ -357,3 +357,5 @@ function toArray(typedArray) { TF.keySize = TF.prototype.keySize = 32; TF.blockSize = TF.prototype.blockSize = 16; + +export default TF; diff --git a/src/crypto/crypto.js b/src/crypto/crypto.js index 72680111..377f88e7 100644 --- a/src/crypto/crypto.js +++ b/src/crypto/crypto.js @@ -59,8 +59,9 @@ export default { module:type/kdf_params>} pub_params Algorithm-specific public key parameters * @param {module:type/mpi} data Data to be encrypted as MPI * @param {String} fingerprint Recipient fingerprint - * @return {Array} encrypted session key parameters + * @returns {Array} encrypted session key parameters + * @async */ publicKeyEncrypt: async function(algo, pub_params, data, fingerprint) { const types = this.getEncSessionKeyParamTypes(algo); @@ -107,7 +108,8 @@ export default { module:type/ecdh_symkey>} data_params encrypted session key parameters * @param {String} fingerprint Recipient fingerprint - * @return {module:type/mpi} An MPI containing the decrypted data + * @returns {module:type/mpi} An MPI containing the decrypted data + * @async */ publicKeyDecrypt: async function(algo, key_params, data_params, fingerprint) { return new type_mpi(await (async function() { @@ -147,7 +149,7 @@ export default { /** Returns the types comprising the private key of an algorithm * @param {String} algo The public key algorithm - * @return {Array} The array of types + * @returns {Array} The array of types */ getPrivKeyParamTypes: function(algo) { switch (algo) { @@ -181,7 +183,7 @@ export default { /** Returns the types comprising the public key of an algorithm * @param {String} algo The public key algorithm - * @return {Array} The array of types + * @returns {Array} The array of types */ getPubKeyParamTypes: function(algo) { switch (algo) { @@ -224,7 +226,7 @@ export default { /** Returns the types comprising the encrypted session key of an algorithm * @param {String} algo The public key algorithm - * @return {Array} The array of types + * @returns {Array} The array of types */ getEncSessionKeyParamTypes: function(algo) { switch (algo) { @@ -253,7 +255,8 @@ export default { * @param {String} algo The public key algorithm * @param {Integer} bits Bit length for RSA keys * @param {module:type/oid} oid Object identifier for ECC keys - * @return {Array} The array of parameters + * @returns {Array} The array of parameters + * @async */ generateParams: function(algo, bits, oid) { const types = [].concat(this.getPubKeyParamTypes(algo), this.getPrivKeyParamTypes(algo)); @@ -288,8 +291,8 @@ export default { * Generates a random byte prefix for the specified algorithm * See {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC 4880 9.2} for algorithms. * @param {module:enums.symmetric} algo Symmetric encryption algorithm - * @return {Uint8Array} Random bytes with length equal to the block - * size of the cipher + * @returns {Uint8Array} Random bytes with length equal to the block size of the cipher + * @async */ getPrefixRandom: function(algo) { return random.getRandomBytes(cipher[algo].blockSize); @@ -297,8 +300,10 @@ export default { /** * Generating a session key for the specified symmetric algorithm - * @param {module:enums.symmetric} algo Algorithm to use (see {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC 4880 9.2}) - * @return {Uint8Array} Random bytes as a string to be used as a key + * See {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC 4880 9.2} for algorithms. + * @param {module:enums.symmetric} algo Symmetric encryption algorithm + * @returns {Uint8Array} Random bytes as a string to be used as a key + * @async */ generateSessionKey: function(algo) { return random.getRandomBytes(cipher[algo].keySize); diff --git a/src/crypto/gcm.js b/src/crypto/gcm.js index b50325d1..6f357fb6 100644 --- a/src/crypto/gcm.js +++ b/src/crypto/gcm.js @@ -42,7 +42,7 @@ const ALGO = 'AES-GCM'; * @param {Uint8Array} plaintext The cleartext input to be encrypted * @param {Uint8Array} key The encryption key * @param {Uint8Array} iv The initialization vector (12 bytes) - * @return {Promise} The ciphertext output + * @returns {Promise} The ciphertext output */ function encrypt(cipher, plaintext, key, iv) { if (cipher.substr(0, 3) !== 'aes') { @@ -63,7 +63,7 @@ function encrypt(cipher, plaintext, key, iv) { * @param {Uint8Array} ciphertext The ciphertext input to be decrypted * @param {Uint8Array} key The encryption key * @param {Uint8Array} iv The initialization vector (12 bytes) - * @return {Promise} The plaintext output + * @returns {Promise} The plaintext output */ function decrypt(cipher, ciphertext, key, iv) { if (cipher.substr(0, 3) !== 'aes') { diff --git a/src/crypto/hash/index.js b/src/crypto/hash/index.js index 2cea7162..269a050f 100644 --- a/src/crypto/hash/index.js +++ b/src/crypto/hash/index.js @@ -1,4 +1,5 @@ /** + * @fileoverview Hashing functions * @requires rusha * @requires asmcrypto.js * @requires hash.js @@ -81,7 +82,7 @@ export default { * Create a hash on the specified data using the specified algorithm * @param {module:enums.hash} algo Hash algorithm type (see {@link https://tools.ietf.org/html/rfc4880#section-9.4|RFC 4880 9.4}) * @param {Uint8Array} data Data to be hashed - * @return {Uint8Array} hash value + * @returns {Uint8Array} hash value */ digest: function(algo, data) { switch (algo) { @@ -114,7 +115,7 @@ export default { /** * Returns the hash size in bytes of the specified hash algorithm type * @param {module:enums.hash} algo Hash algorithm type (See {@link https://tools.ietf.org/html/rfc4880#section-9.4|RFC 4880 9.4}) - * @return {Integer} Size in bytes of the resulting hash + * @returns {Integer} Size in bytes of the resulting hash */ getHashByteLength: function(algo) { switch (algo) { diff --git a/src/crypto/hash/md5.js b/src/crypto/hash/md5.js index a35979b3..3a36ebf3 100644 --- a/src/crypto/hash/md5.js +++ b/src/crypto/hash/md5.js @@ -17,16 +17,15 @@ * @module crypto/hash/md5 */ -import util from '../../util.js'; +import util from '../../util'; /** * MD5 hash * @param {String} entree string to hash */ -export default function(entree) { - const hex = md5(util.Uint8Array_to_str(entree)); - const bin = util.str_to_Uint8Array(util.hex_to_str(hex)); - return bin; +function md5(entree) { + const digest = md51(util.Uint8Array_to_str(entree)); + return util.hex_to_Uint8Array(hex(digest)); } function md5cycle(x, k) { @@ -197,10 +196,6 @@ function hex(x) { return x.join(''); } -function md5(s) { - return hex(md51(s)); -} - /* this function is much faster, so if possible we use it. Some IEs are the only ones I know of that @@ -210,3 +205,5 @@ generated by an if clause. */ function add32(a, b) { return (a + b) & 0xFFFFFFFF; } + +export default md5; diff --git a/src/crypto/index.js b/src/crypto/index.js index ad201506..cd11f4cf 100644 --- a/src/crypto/index.js +++ b/src/crypto/index.js @@ -1,5 +1,11 @@ /** + * @fileoverview Provides access to all cryptographic primitives used in OpenPGP.js * @see module:crypto/crypto + * @see module:crypto/signature + * @see module:crypto/public_key + * @see module:crypto/cipher + * @see module:crypto/random + * @see module:crypto/hash * @module crypto */ @@ -11,9 +17,9 @@ import publicKey from './public_key'; import signature from './signature'; import random from './random'; import pkcs1 from './pkcs1'; -import pkcs5 from './pkcs5.js'; -import crypto from './crypto.js'; -import aes_kw from './aes_kw.js'; +import pkcs5 from './pkcs5'; +import crypto from './crypto'; +import aes_kw from './aes_kw'; // TODO move cfb and gcm to cipher const mod = { diff --git a/src/crypto/pkcs1.js b/src/crypto/pkcs1.js index c0cc29cf..2fc05285 100644 --- a/src/crypto/pkcs1.js +++ b/src/crypto/pkcs1.js @@ -48,7 +48,8 @@ hash_headers[11] = [0x30, 0x2d, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, * Create padding with secure random data * @private * @param {Integer} length Length of the padding in bytes - * @return {String} Padding as string + * @returns {String} Padding as string + * @async */ async function getPkcs1Padding(length) { let result = ''; @@ -71,7 +72,8 @@ export default { * create a EME-PKCS1-v1_5 padding (See {@link https://tools.ietf.org/html/rfc4880#section-13.1.1|RFC 4880 13.1.1}) * @param {String} M message to be encoded * @param {Integer} k the length in octets of the key modulus - * @return {Promise} EME-PKCS1 padded message + * @returns {Promise} EME-PKCS1 padded message + * @async */ encode: async function(M, k) { const mLen = M.length; @@ -93,7 +95,7 @@ export default { /** * decodes a EME-PKCS1-v1_5 padding (See {@link https://tools.ietf.org/html/rfc4880#section-13.1.2|RFC 4880 13.1.2}) * @param {String} EM encoded message, an octet string - * @return {String} message, an octet string + * @returns {String} message, an octet string */ decode: function(EM) { // leading zeros truncated by bn.js diff --git a/src/crypto/pkcs5.js b/src/crypto/pkcs5.js index 088d2d89..6697842b 100644 --- a/src/crypto/pkcs5.js +++ b/src/crypto/pkcs5.js @@ -20,7 +20,7 @@ /** * Add pkcs5 padding to a text. * @param {String} msg Text to add padding - * @return {String} Text with padding added + * @returns {String} Text with padding added */ function encode(msg) { const c = 8 - (msg.length % 8); @@ -31,7 +31,7 @@ function encode(msg) { /** * Remove pkcs5 padding from a string. * @param {String} msg Text to remove padding from - * @return {String} Text with padding removed + * @returns {String} Text with padding removed */ function decode(msg) { const len = msg.length; diff --git a/src/crypto/public_key/dsa.js b/src/crypto/public_key/dsa.js index f30fc9d8..ecf547ee 100644 --- a/src/crypto/public_key/dsa.js +++ b/src/crypto/public_key/dsa.js @@ -42,11 +42,16 @@ const zero = new BN(0); */ export default { - /* - * hash_algo is integer - * m is string - * g, p, q, x are all BN - * returns { r: BN, s: BN } + /** + * DSA Sign function + * @param {Integer} hash_algo + * @param {String} m + * @param {BN} g + * @param {BN} p + * @param {BN} q + * @param {BN} x + * @returns {{ r: BN, s: BN }} + * @async */ sign: async function(hash_algo, m, g, p, q, x) { let k; @@ -90,14 +95,20 @@ export default { s: s.toArrayLike(Uint8Array) }; }, - /* - * hash_algo is integer - * r, s are both BN - * m is string - * p, q, g, y are all BN - * returns BN + /** + * DSA Verify function + * @param {Integer} hash_algo + * @param {BN} r + * @param {BN} s + * @param {String} m + * @param {BN} g + * @param {BN} p + * @param {BN} q + * @param {BN} y + * @returns BN + * @async */ - verify: async function(hash_algo, r, s, m, p, q, g, y) { + verify: async function(hash_algo, r, s, m, g, p, q, y) { if (zero.ucmp(r) >= 0 || r.ucmp(q) >= 0 || zero.ucmp(s) >= 0 || s.ucmp(q) >= 0) { util.print_debug("invalid DSA Signature"); diff --git a/src/crypto/public_key/elgamal.js b/src/crypto/public_key/elgamal.js index 678b0561..2ee9e062 100644 --- a/src/crypto/public_key/elgamal.js +++ b/src/crypto/public_key/elgamal.js @@ -29,9 +29,14 @@ import random from '../random'; const zero = new BN(0); export default { - /* - * m, p, g, y are all BN - * returns { c1: BN, c2: BN } + /** + * ElGamal Encryption function + * @param {BN} m + * @param {BN} p + * @param {BN} g + * @param {BN} y + * @returns {{ c1: BN, c2: BN }} + * @async */ encrypt: async function(m, p, g, y) { const redp = new BN.red(p); @@ -46,9 +51,14 @@ export default { }; }, - /* - * c1, c2, p, x are all BN - * returns BN + /** + * ElGamal Encryption function + * @param {BN} c1 + * @param {BN} c2 + * @param {BN} p + * @param {BN} x + * @returns BN + * @async */ decrypt: async function(c1, c2, p, x) { const redp = new BN.red(p); diff --git a/src/crypto/public_key/elliptic/curves.js b/src/crypto/public_key/elliptic/curves.js index 3508002c..c676d167 100644 --- a/src/crypto/public_key/elliptic/curves.js +++ b/src/crypto/public_key/elliptic/curves.js @@ -15,16 +15,15 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -// Wrapper of an instance of an Elliptic Curve - /** + * @fileoverview Wrapper of an instance of an Elliptic Curve * @requires bn.js * @requires elliptic * @requires crypto/public_key/elliptic/key * @requires crypto/random - * @requires type/oid * @requires enums * @requires util + * @requires type/oid * @module crypto/public_key/elliptic/curve */ @@ -112,7 +111,10 @@ const curves = { } }; -export default function Curve(oid_or_name, params) { +/** + * @constructor + */ +function Curve(oid_or_name, params) { try { if (util.isArray(oid_or_name) || util.isUint8Array(oid_or_name)) { @@ -206,11 +208,12 @@ function getPreferredHashAlgo(oid) { return curves[enums.write(enums.curve, oid.toHex())].hash; } +export default Curve; + export { curves, webCurves, nodeCurves, generate, getPreferredHashAlgo }; - ////////////////////////// // // // Helper functions // diff --git a/src/crypto/public_key/elliptic/ecdh.js b/src/crypto/public_key/elliptic/ecdh.js index 315492d8..57c92590 100644 --- a/src/crypto/public_key/elliptic/ecdh.js +++ b/src/crypto/public_key/elliptic/ecdh.js @@ -15,9 +15,8 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -// Key encryption and decryption for RFC 6637 ECDH - /** + * @fileoverview Key encryption and decryption for RFC 6637 ECDH * @requires crypto/public_key/elliptic/curves * @requires crypto/aes_kw * @requires crypto/cipher @@ -70,7 +69,8 @@ function kdf(hash_algo, X, length, param) { * @param {module:type/mpi} m Value derived from session key (RFC 6637) * @param {Uint8Array} Q Recipient public key * @param {String} fingerprint Recipient fingerprint - * @return {{V: BN, C: BN}} Returns ephemeral key and encoded session key + * @returns {{V: BN, C: BN}} Returns ephemeral key and encoded session key + * @async */ async function encrypt(oid, cipher_algo, hash_algo, m, Q, fingerprint) { fingerprint = util.hex_to_Uint8Array(fingerprint); @@ -98,7 +98,8 @@ async function encrypt(oid, cipher_algo, hash_algo, m, Q, fingerprint) { * @param {Uint8Array} C Encrypted and wrapped value derived from session key * @param {Uint8Array} d Recipient private key * @param {String} fingerprint Recipient fingerprint - * @return {Uint8Array} Value derived from session + * @returns {Uint8Array} Value derived from session + * @async */ async function decrypt(oid, cipher_algo, hash_algo, V, C, d, fingerprint) { fingerprint = util.hex_to_Uint8Array(fingerprint); diff --git a/src/crypto/public_key/elliptic/ecdsa.js b/src/crypto/public_key/elliptic/ecdsa.js index c9b1549d..1bf020b8 100644 --- a/src/crypto/public_key/elliptic/ecdsa.js +++ b/src/crypto/public_key/elliptic/ecdsa.js @@ -15,9 +15,8 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -// Implementation of ECDSA following RFC6637 for Openpgpjs - /** + * @fileoverview Implementation of ECDSA following RFC6637 for Openpgpjs * @requires crypto/hash * @requires crypto/public_key/elliptic/curves * @module crypto/public_key/elliptic/ecdsa @@ -32,8 +31,9 @@ import Curve from './curves'; * @param {enums.hash} hash_algo Hash algorithm used to sign * @param {Uint8Array} m Message to sign * @param {Uint8Array} d Private key used to sign the message - * @return {{r: Uint8Array, - s: Uint8Array}} Signature of the message + * @returns {{r: Uint8Array, + * s: Uint8Array}} Signature of the message + * @async */ async function sign(oid, hash_algo, m, d) { const curve = new Curve(oid); @@ -51,7 +51,8 @@ async function sign(oid, hash_algo, m, d) { s: Uint8Array}} signature Signature to verify * @param {Uint8Array} m Message to verify * @param {Uint8Array} Q Public key used to verify the message - * @return {Boolean} + * @returns {Boolean} + * @async */ async function verify(oid, hash_algo, signature, m, Q) { const curve = new Curve(oid); diff --git a/src/crypto/public_key/elliptic/eddsa.js b/src/crypto/public_key/elliptic/eddsa.js index 4db75099..02b1fcdc 100644 --- a/src/crypto/public_key/elliptic/eddsa.js +++ b/src/crypto/public_key/elliptic/eddsa.js @@ -15,9 +15,8 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -// Implementation of EdDSA following RFC4880bis-03 for OpenPGP - /** + * @fileoverview Implementation of EdDSA following RFC4880bis-03 for OpenPGP * @requires bn.js * @requires crypto/hash * @requires crypto/public_key/elliptic/curves @@ -34,8 +33,9 @@ import Curve from './curves'; * @param {enums.hash} hash_algo Hash algorithm used to sign * @param {Uint8Array} m Message to sign * @param {Uint8Array} d Private key used to sign - * @return {{R: Uint8Array, - S: Uint8Array}} Signature of the message + * @returns {{R: Uint8Array, + * S: Uint8Array}} Signature of the message + * @async */ async function sign(oid, hash_algo, m, d) { const curve = new Curve(oid); @@ -54,7 +54,8 @@ async function sign(oid, hash_algo, m, d) { S: Uint8Array}} signature Signature to verify the message * @param {Uint8Array} m Message to verify * @param {Uint8Array} Q Public key used to verify the message - * @return {Boolean} + * @returns {Boolean} + * @async */ async function verify(oid, hash_algo, signature, m, Q) { const curve = new Curve(oid); diff --git a/src/crypto/public_key/elliptic/index.js b/src/crypto/public_key/elliptic/index.js index cffe5dc4..aa271fff 100644 --- a/src/crypto/public_key/elliptic/index.js +++ b/src/crypto/public_key/elliptic/index.js @@ -15,13 +15,12 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -// Function to access Elliptic Curve Cryptography - /** - * @requires crypto/public_key/elliptic/curve - * @requires crypto/public_key/elliptic/ecdh - * @requires crypto/public_key/elliptic/ecdsa - * @requires crypto/public_key/elliptic/eddsa + * @fileoverview Functions to access Elliptic Curve Cryptography + * @see module:crypto/public_key/elliptic/curve + * @see module:crypto/public_key/elliptic/ecdh + * @see module:crypto/public_key/elliptic/ecdsa + * @see module:crypto/public_key/elliptic/eddsa * @module crypto/public_key/elliptic */ diff --git a/src/crypto/public_key/elliptic/key.js b/src/crypto/public_key/elliptic/key.js index ba6c26e1..07c4239d 100644 --- a/src/crypto/public_key/elliptic/key.js +++ b/src/crypto/public_key/elliptic/key.js @@ -15,15 +15,13 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -// Wrapper for a KeyPair of an Elliptic Curve - /** + * @fileoverview Wrapper for a KeyPair of an Elliptic Curve * @requires bn.js * @requires crypto/public_key/elliptic/curves * @requires crypto/hash * @requires util * @requires enums - * @requires jwk-to-pem * @requires asn1.js * @module crypto/public_key/elliptic/key */ @@ -37,7 +35,10 @@ import enums from '../../../enums'; const webCrypto = util.getWebCrypto(); const nodeCrypto = util.getNodeCrypto(); -export default function KeyPair(curve, options) { +/** + * @constructor + */ +function KeyPair(curve, options) { this.curve = curve; this.keyType = curve.curve.type === 'edwards' ? enums.publicKey.eddsa : enums.publicKey.ecdsa; this.keyPair = this.curve.curve.keyPair(options); @@ -97,6 +98,7 @@ KeyPair.prototype.getPrivate = function () { return this.keyPair.getPrivate().toArray(); }; +export default KeyPair; ////////////////////////// // // @@ -224,6 +226,9 @@ async function nodeVerify(curve, hash_algo, { r, s }, message, publicKey) { } } +// Originally written by Owen Smith https://github.com/omsmith +// Adapted on Feb 2018 from https://github.com/Brightspace/node-jwk-to-pem/ + const asn1 = nodeCrypto ? require('asn1.js') : undefined; const ECDSASignature = nodeCrypto ? diff --git a/src/crypto/public_key/index.js b/src/crypto/public_key/index.js index 927f0c52..d3cd1012 100644 --- a/src/crypto/public_key/index.js +++ b/src/crypto/public_key/index.js @@ -1,8 +1,9 @@ /** - * @requires crypto/public_key/dsa - * @requires crypto/public_key/elgamal - * @requires crypto/public_key/elliptic - * @requires crypto/public_key/rsa + * @fileoverview Asymmetric cryptography functions + * @see module:crypto/public_key/dsa + * @see module:crypto/public_key/elgamal + * @see module:crypto/public_key/elliptic + * @see module:crypto/public_key/rsa * @module crypto/public_key */ diff --git a/src/crypto/public_key/prime.js b/src/crypto/public_key/prime.js index 42d5e8f6..4446e06d 100644 --- a/src/crypto/public_key/prime.js +++ b/src/crypto/public_key/prime.js @@ -15,9 +15,8 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -// Algorithms for probabilistic random prime generation - /** + * @fileoverview Algorithms for probabilistic random prime generation * @requires bn.js * @requires crypto/random * @module crypto/public_key/prime @@ -35,7 +34,8 @@ export default { * @param {Integer} bits Bit length of the prime * @param {BN} e Optional RSA exponent to check against the prime * @param {Integer} k Optional number of iterations of Miller-Rabin test - * @return BN + * @returns BN + * @async */ async function randomProbablePrime(bits, e, k) { const min = new BN(1).shln(bits - 1); @@ -69,7 +69,8 @@ async function randomProbablePrime(bits, e, k) { * @param {BN} n Number to test * @param {BN} e Optional RSA exponent to check against the prime * @param {Integer} k Optional number of iterations of Miller-Rabin test - * @return {boolean} + * @returns {boolean} + * @async */ async function isProbablePrime(n, e, k) { if (e && !n.subn(1).gcd(e).eqn(1)) { @@ -94,7 +95,7 @@ async function isProbablePrime(n, e, k) { * Fails if b^(n-1) mod n === 1. * @param {BN} n Number to test * @param {Integer} b Optional Fermat test base - * @return {boolean} + * @returns {boolean} */ function fermat(n, b) { b = b || new BN(2); @@ -226,7 +227,8 @@ const small_primes = [ * @param {BN} n Number to test * @param {Integer} k Optional number of iterations of Miller-Rabin test * @param {Function} rand Optional function to generate potential witnesses - * @return {boolean} + * @returns {boolean} + * @async */ async function millerRabin(n, k, rand) { const len = n.bitLength(); diff --git a/src/crypto/public_key/rsa.js b/src/crypto/public_key/rsa.js index ac5c9e2f..9a02795b 100644 --- a/src/crypto/public_key/rsa.js +++ b/src/crypto/public_key/rsa.js @@ -53,7 +53,8 @@ export default { * @param n public MPI part as BN * @param e public MPI part as BN * @param d private MPI part as BN - * @return BN + * @returns BN + * @async */ sign: async function(m, n, e, d) { if (n.cmp(m) <= 0) { @@ -68,7 +69,8 @@ export default { * @param s signature as BN * @param n public MPI part as BN * @param e public MPI part as BN - * @return BN + * @returns BN + * @async */ verify: async function(s, n, e) { if (n.cmp(s) <= 0) { @@ -83,7 +85,8 @@ export default { * @param m message as BN * @param n public MPI part as BN * @param e public MPI part as BN - * @return BN + * @returns BN + * @async */ encrypt: async function(m, n, e) { if (n.cmp(m) <= 0) { @@ -102,7 +105,8 @@ export default { * @param p RSA p as BN * @param q RSA q as BN * @param u RSA u as BN - * @return {BN} The decrypted value of the message + * @returns {BN} The decrypted value of the message + * @async */ decrypt: async function(m, n, e, d, p, q, u) { if (n.cmp(m) <= 0) { @@ -140,9 +144,10 @@ export default { * Generate a new random private key B bits long with public exponent E * @param {Integer} B RSA bit length * @param {String} E RSA public exponent in hex string - * @return {{n: BN, e: BN, d: BN, - p: BN, q: BN, u: BN}} RSA public modulus, RSA public exponent, RSA private exponent, - RSA private prime p, RSA private prime q, u = q ** -1 mod p + * @returns {{n: BN, e: BN, d: BN, + * p: BN, q: BN, u: BN}} RSA public modulus, RSA public exponent, RSA private exponent, + * RSA private prime p, RSA private prime q, u = q ** -1 mod p + * @async */ generate: async function(B, E) { let key; diff --git a/src/crypto/random.js b/src/crypto/random.js index e714df31..11532473 100644 --- a/src/crypto/random.js +++ b/src/crypto/random.js @@ -35,7 +35,8 @@ export default { /** * Retrieve secure random byte array of the specified length * @param {Integer} length Length in bytes to generate - * @return {Uint8Array} Random byte array + * @returns {Uint8Array} Random byte array + * @async */ getRandomBytes: async function(length) { const buf = new Uint8Array(length); @@ -58,7 +59,8 @@ export default { * Create a secure random MPI that is greater than or equal to min and less than max. * @param {module:type/mpi} min Lower bound, included * @param {module:type/mpi} max Upper bound, excluded - * @return {module:BN} Random MPI + * @returns {module:BN} Random MPI + * @async */ getRandomBN: async function(min, max) { if (max.cmp(min) <= 0) { diff --git a/src/crypto/signature.js b/src/crypto/signature.js index 8b77c6d2..edcf247e 100644 --- a/src/crypto/signature.js +++ b/src/crypto/signature.js @@ -24,7 +24,8 @@ export default { * @param {Array} msg_MPIs Algorithm-specific signature parameters * @param {Array} pub_MPIs Algorithm-specific public key parameters * @param {Uint8Array} data Data for which the signature was created - * @return {Boolean} True if signature is valid + * @returns {Boolean} True if signature is valid + * @async */ verify: async function(algo, hash_algo, msg_MPIs, pub_MPIs, data) { switch (algo) { @@ -45,7 +46,7 @@ export default { const q = pub_MPIs[1].toBN(); const g = pub_MPIs[2].toBN(); const y = pub_MPIs[3].toBN(); - return publicKey.dsa.verify(hash_algo, r, s, data, p, q, g, y); + return publicKey.dsa.verify(hash_algo, r, s, data, g, p, q, y); } case enums.publicKey.ecdsa: { const oid = pub_MPIs[0]; @@ -76,7 +77,8 @@ export default { * @param {module:enums.hash} hash_algo Hash algorithm * @param {Array} key_params Algorithm-specific public and private key parameters * @param {Uint8Array} data Data to be signed - * @return {Uint8Array} Signature + * @returns {Uint8Array} Signature + * @async */ sign: async function(algo, hash_algo, key_params, data) { switch (algo) { diff --git a/src/encoding/armor.js b/src/encoding/armor.js index 5abdb096..4b030867 100644 --- a/src/encoding/armor.js +++ b/src/encoding/armor.js @@ -111,7 +111,7 @@ function addheader() { /** * Calculates a checksum over the given data and returns it base64 encoded * @param {String} data Data to create a CRC-24 checksum for - * @return {String} Base64 encoded checksum + * @returns {String} Base64 encoded checksum */ function getCheckSum(data) { const c = createcrc24(data); @@ -124,7 +124,7 @@ function getCheckSum(data) { * given base64 encoded checksum * @param {String} data Data to create a CRC-24 checksum for * @param {String} checksum Base64 encoded checksum - * @return {Boolean} True if the given checksum is correct; otherwise false + * @returns {Boolean} True if the given checksum is correct; otherwise false */ function verifyCheckSum(data, checksum) { const c = getCheckSum(data); @@ -134,7 +134,7 @@ function verifyCheckSum(data, checksum) { /** * Internal function to calculate a CRC-24 checksum over a given string (data) * @param {String} data Data to create a CRC-24 checksum for - * @return {Integer} The CRC-24 checksum as number + * @returns {Integer} The CRC-24 checksum as number */ const crc_table = [ 0x00000000, 0x00864cfb, 0x018ad50d, 0x010c99f6, 0x0393e6e1, 0x0315aa1a, 0x021933ec, 0x029f7f17, 0x07a18139, diff --git a/src/hkp.js b/src/hkp.js index 18e3ab68..37c5d7cb 100644 --- a/src/hkp.js +++ b/src/hkp.js @@ -29,7 +29,7 @@ import config from './config'; * @param {String} keyServerBaseUrl (optional) The HKP key server base url including * the protocol to use e.g. https://pgp.mit.edu */ -export default function HKP(keyServerBaseUrl) { +function HKP(keyServerBaseUrl) { this._baseUrl = keyServerBaseUrl || config.keyserver; this._fetch = typeof window !== 'undefined' ? window.fetch : require('node-fetch'); } @@ -39,7 +39,8 @@ export default function HKP(keyServerBaseUrl) { * @param {String} options.keyID The long public key ID. * @param {String} options.query This can be any part of the key user ID such as name * or email address. - * @return {Promise} The ascii armored public key. + * @returns {Promise} The ascii armored public key. + * @async */ HKP.prototype.lookup = function(options) { let uri = this._baseUrl + '/pks/lookup?op=get&options=mr&search='; @@ -68,7 +69,8 @@ HKP.prototype.lookup = function(options) { /** * Upload a public key to the server. * @param {String} publicKeyArmored An ascii armored public key to be uploaded. - * @return {Promise} + * @returns {Promise} + * @async */ HKP.prototype.upload = function(publicKeyArmored) { const uri = this._baseUrl + '/pks/add'; @@ -82,3 +84,5 @@ HKP.prototype.upload = function(publicKeyArmored) { body: 'keytext=' + encodeURIComponent(publicKeyArmored) }); }; + +export default HKP; diff --git a/src/key.js b/src/key.js index c0a8ee83..75fd19f6 100644 --- a/src/key.js +++ b/src/key.js @@ -263,8 +263,9 @@ function isValidSigningKeyPacket(keyPacket, signature, date=new Date()) { * Returns first key packet or key packet by given keyId that is available for signing and verification * @param {module:type/keyid} keyId, optional * @param {Date} date use the given date for verification instead of the current time - * @returns {(module:packet/secret_subkey| - module:packet/secret_key|null)} key packet or null if no signing key has been found + * @returns {Promise} key packet or null if no signing key has been found + * @async */ Key.prototype.getSigningKeyPacket = async function (keyId=null, date=new Date()) { const primaryKey = this.primaryKey; @@ -305,10 +306,11 @@ function isValidEncryptionKeyPacket(keyPacket, signature, date=new Date()) { * Returns first key packet or key packet by given keyId that is available for encryption or decryption * @param {module:type/keyid} keyId, optional * @param {Date} date, optional - * @returns {(module:packet/public_subkey| - * module:packet/secret_subkey| - * module:packet/secret_key| - * module:packet/public_key|null)} key packet or null if no encryption key has been found + * @returns {Promise} key packet or null if no encryption key has been found + * @async */ Key.prototype.getEncryptionKeyPacket = async function(keyId, date=new Date()) { const primaryKey = this.primaryKey; @@ -340,6 +342,7 @@ Key.prototype.getEncryptionKeyPacket = async function(keyId, date=new Date()) { * @param {module:type/keyid} keyId * @param {String} passphrase * @returns {Promise>} + * @async */ Key.prototype.encrypt = async function(passphrase, keyId=null) { if (!this.isPrivate()) { @@ -358,6 +361,7 @@ Key.prototype.encrypt = async function(passphrase, keyId=null) { * @param {String} passphrase * @param {module:type/keyid} keyId * @returns {Promise} true if all matching key and subkey packets decrypted successfully + * @async */ Key.prototype.decrypt = async function(passphrase, keyId=null) { if (!this.isPrivate()) { @@ -380,6 +384,7 @@ Key.prototype.decrypt = async function(passphrase, keyId=null) { * module:packet/secret_key} key, optional The key to verify the signature * @param {Date} date Use the given date instead of the current time * @returns {Promise} True if the certificate is revoked + * @async */ Key.prototype.isRevoked = async function(signature, key, date=new Date()) { return isDataRevoked( @@ -394,6 +399,7 @@ Key.prototype.isRevoked = async function(signature, key, date=new Date()) { * @param {type/keyid} keyId * @param {Date} date Use the given date instead of the current time * @returns {Promise} + * @async */ Key.prototype.verifyKeyPackets = async function(keyId=null, date=new Date()) { const packets = new packet.List(); @@ -418,6 +424,7 @@ Key.prototype.verifyKeyPackets = async function(keyId=null, date=new Date()) { * and valid self signature * @param {Date} date (optional) use the given date for verification instead of the current time * @returns {Promise} The status of the primary key + * @async */ Key.prototype.verifyPrimaryKey = async function(date=new Date()) { const primaryKey = this.primaryKey; @@ -446,7 +453,8 @@ Key.prototype.verifyPrimaryKey = async function(date=new Date()) { /** * Returns the expiration time of the primary key or Infinity if key does not expire - * @returns {Date} + * @returns {Promise} + * @async */ Key.prototype.getExpirationTime = async function() { if (this.primaryKey.version === 3) { @@ -466,7 +474,9 @@ Key.prototype.getExpirationTime = async function() { * - if multiple primary users exist, returns the one with the latest self signature * - otherwise, returns the user with the latest self signature * @param {Date} date use the given date for verification instead of the current time - * @returns {{user: Array, selfCertification: Array}|null} The primary user and the self signature + * @returns {Promise<{user: Array, + * selfCertification: Array}|undefined>} The primary user and the self signature + * @async */ Key.prototype.getPrimaryUser = async function(date=new Date()) { const { primaryKey } = this; @@ -615,6 +625,7 @@ Key.prototype.revoke = function() { * Signs primary user of key * @param {Array} privateKey decrypted private keys for signing * @returns {Promise} new public key with new certificate signature + * @async */ Key.prototype.signPrimaryUser = async function(privateKeys) { const { index, user } = await this.getPrimaryUser() || {}; @@ -631,6 +642,7 @@ Key.prototype.signPrimaryUser = async function(privateKeys) { * Signs all users of key * @param {Array} privateKeys decrypted private keys for signing * @returns {Promise} new public key with new certificate signature + * @async */ Key.prototype.signAllUsers = async function(privateKeys) { const that = this; @@ -648,6 +660,7 @@ Key.prototype.signAllUsers = async function(privateKeys) { * @param {Array} keys array of keys to verify certificate signatures * @returns {Promise>} List of signer's keyid and validity of signature + * @async */ Key.prototype.verifyPrimaryUser = async function(keys) { const primaryKey = this.primaryKey; @@ -668,6 +681,7 @@ Key.prototype.verifyPrimaryUser = async function(keys) { * @returns {Promise>} list of userid, signer's keyid and validity of signature + * @async */ Key.prototype.verifyAllUsers = async function(keys) { const results = []; @@ -720,6 +734,7 @@ User.prototype.toPacketlist = function() { * module:packet/public_key} primaryKey The primary key packet * @param {Array} privateKeys Decrypted private keys for signing * @returns {Promise} New user with new certificate signatures + * @async */ User.prototype.sign = async function(primaryKey, privateKeys) { const dataToSign = { userid: this.userId || this.userAttribute, key: primaryKey }; @@ -764,6 +779,7 @@ User.prototype.sign = async function(primaryKey, privateKeys) { * module:packet/secret_key} key, optional The key to verify the signature * @param {Date} date Use the given date instead of the current time * @returns {Promise} True if the certificate is revoked + * @async */ User.prototype.isRevoked = async function(primaryKey, certificate, key, date=new Date()) { return isDataRevoked( @@ -782,6 +798,7 @@ User.prototype.isRevoked = async function(primaryKey, certificate, key, date=new * @param {Array} keys Array of keys to verify certificate signatures * @param {Date} date Use the given date instead of the current time * @returns {Promise} status of the certificate + * @async */ User.prototype.verifyCertificate = async function(primaryKey, certificate, keys, date=new Date()) { const that = this; @@ -811,6 +828,7 @@ User.prototype.verifyCertificate = async function(primaryKey, certificate, keys, * @param {Array} keys Array of keys to verify certificate signatures * @returns {Promise>} List of signer's keyid and validity of signature + * @async */ User.prototype.verifyAllCertifications = async function(primaryKey, keys) { const that = this; @@ -830,6 +848,7 @@ User.prototype.verifyAllCertifications = async function(primaryKey, keys) { * @param {module:packet/secret_key| * module:packet/public_key} primaryKey The primary key packet * @returns {Promise} Status of user + * @async */ User.prototype.verify = async function(primaryKey) { if (!this.selfCertifications.length) { @@ -911,6 +930,7 @@ SubKey.prototype.toPacketlist = function() { * module:packet/secret_key} key, optional The key to verify the signature * @param {Date} date Use the given date instead of the current time * @returns {Promise} True if the binding signature is revoked + * @async */ SubKey.prototype.isRevoked = async function(primaryKey, signature, key, date=new Date()) { return isDataRevoked( @@ -928,6 +948,7 @@ SubKey.prototype.isRevoked = async function(primaryKey, signature, key, date=new * module:packet/public_key} primaryKey The primary key packet * @param {Date} date Use the given date instead of the current time * @returns {Promise} The status of the subkey + * @async */ SubKey.prototype.verify = async function(primaryKey, date=new Date()) { const that = this; @@ -1021,7 +1042,8 @@ SubKey.prototype.update = async function(subKey, primaryKey) { /** * Reads an unarmored OpenPGP key list and returns one or multiple key objects * @param {Uint8Array} data to be parsed - * @returns {{keys: Array, err: (Array|null)}} result object with key and error arrays + * @returns {{keys: Array, + * err: (Array|null)}} result object with key and error arrays * @static */ export function read(data) { @@ -1055,7 +1077,7 @@ export function read(data) { * Reads an OpenPGP armored text and returns one or multiple key objects * @param {String} armoredText text to be parsed * @returns {{keys: Array, - err: (Array|null)}} result object with key and error arrays + * err: (Array|null)}} result object with key and error arrays * @static */ export function readArmored(armoredText) { @@ -1083,7 +1105,8 @@ export function readArmored(armoredText) { * @param {String} options.passphrase The passphrase used to encrypt the resulting private key * @param {Boolean} [options.unlocked=false] The secret part of the generated key is unlocked * @param {Number} [options.keyExpirationTime=0] The number of seconds after the key creation time that the key expires - * @returns {module:key~Key} + * @returns {Promise} + * @async * @static */ export function generate(options) { @@ -1159,6 +1182,7 @@ export function generate(options) { * @param {Boolean} [options.unlocked=false] The secret part of the generated key is unlocked * @param {Number} [options.keyExpirationTime=0] The number of seconds after the key creation time that the key expires * @returns {Promise} + * @async * @static */ export async function reformat(options) { @@ -1304,6 +1328,7 @@ async function wrapKeyObject(secretKeyPacket, secretSubkeyPacket, options) { * module:packet/secret_key} key, optional The key packet to check the signature * @param {Date} date Use the given date instead of the current time * @returns {Promise} True if the signature revokes the data + * @async */ async function isDataRevoked(primaryKey, dataToVerify, revocations, signature, key, date=new Date()) { key = key || primaryKey; @@ -1353,7 +1378,8 @@ function getExpirationTime(keyPacket, signature) { /** * Returns the preferred signature hash algorithm of a key * @param {object} key - * @returns {String} + * @returns {Promise} + * @async */ export async function getPreferredHashAlgo(key) { let hash_algo = config.prefer_hash_algorithm; @@ -1387,7 +1413,8 @@ export async function getPreferredHashAlgo(key) { /** * Returns the preferred symmetric algorithm for a set of keys * @param {Array} keys Set of keys - * @returns {enums.symmetric} Preferred symmetric algorithm + * @returns {Promise} Preferred symmetric algorithm + * @async */ export async function getPreferredSymAlgo(keys) { const prioMap = {}; diff --git a/src/keyring/index.js b/src/keyring/index.js index 1279a644..70cca7ee 100644 --- a/src/keyring/index.js +++ b/src/keyring/index.js @@ -1,5 +1,7 @@ /** + * @fileoverview Functions dealing with storage of the keyring. * @see module:keyring/keyring + * @see module:keyring/localstore * @module keyring */ import Keyring from './keyring.js'; diff --git a/src/keyring/keyring.js b/src/keyring/keyring.js index 4bf39e4e..7461a655 100644 --- a/src/keyring/keyring.js +++ b/src/keyring/keyring.js @@ -16,23 +16,21 @@ // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA /** - * The class that deals with storage of the keyring. Currently the only option is to use HTML5 local storage. * @requires key * @requires keyring/localstore * @module keyring/keyring - * @param {keyring/localstore} [storeHandler] class implementing loadPublic(), loadPrivate(), storePublic(), and storePrivate() methods */ import { readArmored } from '../key'; import LocalStore from './localstore'; /** - * Initialization routine for the keyring. This method reads the - * keyring from HTML5 local storage and initializes this instance. + * Initialization routine for the keyring. + * This method reads the keyring from HTML5 local storage and initializes this instance. * @constructor * @param {keyring/localstore} [storeHandler] class implementing loadPublic(), loadPrivate(), storePublic(), and storePrivate() methods */ -export default function Keyring(storeHandler) { +function Keyring(storeHandler) { this.storeHandler = storeHandler || new LocalStore(); this.publicKeys = new KeyArray(this.storeHandler.loadPublic()); this.privateKeys = new KeyArray(this.storeHandler.loadPrivate()); @@ -59,7 +57,7 @@ Keyring.prototype.clear = function() { * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) * @param {Boolean} deep if true search also in subkeys - * @return {Array|null} keys found or null + * @returns {Array|null} keys found or null */ Keyring.prototype.getKeysForId = function (keyId, deep) { let result = []; @@ -72,7 +70,7 @@ Keyring.prototype.getKeysForId = function (keyId, deep) { * Removes keys having the specified key id from the keyring * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) - * @return {Array|null} keys found or null + * @returns {Array|null} keys found or null */ Keyring.prototype.removeKeysForId = function (keyId) { let result = []; @@ -83,7 +81,7 @@ Keyring.prototype.removeKeysForId = function (keyId) { /** * Get all public and private keys - * @return {Array} all keys + * @returns {Array} all keys */ Keyring.prototype.getAllKeys = function () { return this.publicKeys.keys.concat(this.privateKeys.keys); @@ -100,7 +98,7 @@ function KeyArray(keys) { /** * Searches all keys in the KeyArray matching the address or address part of the user ids * @param {String} email email address to search for - * @return {Array} The public keys associated with provided email address. + * @returns {Array} The public keys associated with provided email address. */ KeyArray.prototype.getForAddress = function(email) { const results = []; @@ -117,7 +115,7 @@ KeyArray.prototype.getForAddress = function(email) { * @private * @param {String} email email address to search for * @param {module:key~Key} key The key to be checked. - * @return {Boolean} True if the email address is defined in the specified key + * @returns {Boolean} True if the email address is defined in the specified key */ function emailCheck(email, key) { email = email.toLowerCase(); @@ -140,7 +138,7 @@ function emailCheck(email, key) { * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) * @param {module:packet/secret_key|public_key|public_subkey|secret_subkey} keypacket The keypacket to be checked - * @return {Boolean} True if keypacket has the specified keyid + * @returns {Boolean} True if keypacket has the specified keyid */ function keyIdCheck(keyId, keypacket) { if (keyId.length === 16) { @@ -154,7 +152,7 @@ function keyIdCheck(keyId, keypacket) { * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) * @param {Boolean} deep if true search also in subkeys - * @return {module:key~Key|null} key found or null + * @returns {module:key~Key|null} key found or null */ KeyArray.prototype.getForId = function (keyId, deep) { for (let i = 0; i < this.keys.length; i++) { @@ -175,28 +173,31 @@ KeyArray.prototype.getForId = function (keyId, deep) { /** * Imports a key from an ascii armored message * @param {String} armored message to read the keys/key from - * @return {Array|null} array of error objects or null + * @returns {Promise|null>} array of error objects or null + * @async */ -KeyArray.prototype.importKey = function (armored) { +KeyArray.prototype.importKey = async function (armored) { const imported = readArmored(armored); const that = this; - imported.keys.forEach(async function(key) { + for (let i = 0; i < imported.keys.length; i++) { + const key = imported.keys[i]; // check if key already in key array const keyidHex = key.primaryKey.getKeyId().toHex(); const keyFound = that.getForId(keyidHex); if (keyFound) { + // eslint-disable-next-line no-await-in-loop await keyFound.update(key); } else { that.push(key); } - }); + } return imported.err ? imported.err : null; }; /** * Add key to KeyArray * @param {module:key~Key} key The key that will be added to the keyring - * @return {Number} The new length of the KeyArray + * @returns {Number} The new length of the KeyArray */ KeyArray.prototype.push = function (key) { return this.keys.push(key); @@ -206,7 +207,7 @@ KeyArray.prototype.push = function (key) { * Removes a key with the specified keyid from the keyring * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) - * @return {module:key~Key|null} The key object which has been removed or null + * @returns {module:key~Key|null} The key object which has been removed or null */ KeyArray.prototype.removeForId = function (keyId) { for (let i = 0; i < this.keys.length; i++) { @@ -216,3 +217,5 @@ KeyArray.prototype.removeForId = function (keyId) { } return null; }; + +export default Keyring; diff --git a/src/keyring/localstore.js b/src/keyring/localstore.js index 800d9a7d..7a45818d 100644 --- a/src/keyring/localstore.js +++ b/src/keyring/localstore.js @@ -16,19 +16,23 @@ // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA /** - * The class that deals with storage of the keyring. Currently the only option is to use HTML5 local storage. * @requires config * @requires key * @requires util * @module keyring/localstore - * @param {String} prefix prefix for itemnames in localstore */ import config from '../config'; import { readArmored } from '../key'; import util from '../util'; -export default function LocalStore(prefix) { +/** + * The class that deals with storage of the keyring. + * Currently the only option is to use HTML5 local storage. + * @constructor + * @param {String} prefix prefix for itemnames in localstore + */ +function LocalStore(prefix) { prefix = prefix || 'openpgp-'; this.publicKeysItem = prefix + this.publicKeysItem; this.privateKeysItem = prefix + this.privateKeysItem; @@ -47,7 +51,7 @@ LocalStore.prototype.privateKeysItem = 'private-keys'; /** * Load the public keys from HTML5 local storage. - * @return {Array} array of keys retrieved from localstore + * @returns {Array} array of keys retrieved from localstore */ LocalStore.prototype.loadPublic = function () { return loadKeys(this.storage, this.publicKeysItem); @@ -55,7 +59,7 @@ LocalStore.prototype.loadPublic = function () { /** * Load the private keys from HTML5 local storage. - * @return {Array} array of keys retrieved from localstore + * @returns {Array} array of keys retrieved from localstore */ LocalStore.prototype.loadPrivate = function () { return loadKeys(this.storage, this.privateKeysItem); @@ -107,3 +111,5 @@ function storeKeys(storage, itemname, keys) { storage.removeItem(itemname); } } + +export default LocalStore; diff --git a/src/message.js b/src/message.js index 0ce048b9..1fbe384e 100644 --- a/src/message.js +++ b/src/message.js @@ -94,6 +94,7 @@ Message.prototype.getSigningKeyIds = function() { * @param {Array} passwords (optional) passwords used to decrypt * @param {Array} sessionKeys (optional) session keys in the form: { data:Uint8Array, algorithm:String } * @returns {Promise} new message with decrypted content + * @async */ Message.prototype.decrypt = async function(privateKeys, passwords, sessionKeys) { const keyObjs = sessionKeys || await this.decryptSessionKeys(privateKeys, passwords); @@ -140,6 +141,7 @@ Message.prototype.decrypt = async function(privateKeys, passwords, sessionKeys) * @param {Array} passwords (optional) passwords used to decrypt * @returns {Promise>} array of object with potential sessionKey, algorithm pairs + * @async */ Message.prototype.decryptSessionKeys = async function(privateKeys, passwords) { let keyPackets = []; @@ -241,6 +243,7 @@ Message.prototype.getText = function() { * @param {Boolean} wildcard (optional) use a key ID of 0 instead of the public key IDs * @param {Date} date (optional) override the creation date of the literal package * @returns {Promise} new message with encrypted content + * @async */ Message.prototype.encrypt = async function(keys, passwords, sessionKey, wildcard=false, date=new Date()) { let symAlgo; @@ -297,6 +300,7 @@ Message.prototype.encrypt = async function(keys, passwords, sessionKey, wildcard * @param {Boolean} wildcard (optional) use a key ID of 0 instead of the public key IDs * @param {Date} date (optional) override the creation date signature * @returns {Promise} new message with encrypted content + * @async */ export async function encryptSessionKey(sessionKey, symAlgo, publicKeys, passwords, wildcard=false, date=new Date()) { const packetlist = new packet.List(); @@ -361,6 +365,7 @@ export async function encryptSessionKey(sessionKey, symAlgo, publicKeys, passwor * @param {Signature} signature (optional) any existing detached signature to add to the message * @param {Date} date} (optional) override the creation time of the signature * @returns {Promise} new message with signed content + * @async */ Message.prototype.sign = async function(privateKeys=[], signature=null, date=new Date()) { const packetlist = new packet.List(); @@ -446,6 +451,7 @@ Message.prototype.compress = function(compression) { * @param {Signature} signature (optional) any existing detached signature * @param {Date} date (optional) override the creation time of the signature * @returns {Promise} new detached signature of message content + * @async */ Message.prototype.signDetached = async function(privateKeys=[], signature=null, date=new Date()) { const literalDataPacket = this.packets.findPacket(enums.packet.literal); @@ -462,6 +468,7 @@ Message.prototype.signDetached = async function(privateKeys=[], signature=null, * @param {Signature} signature (optional) any existing detached signature to append * @param {Date} date (optional) override the creationtime of the signature * @returns {Promise} list of signature packets + * @async */ export async function createSignaturePackets(literalDataPacket, privateKeys, signature=null, date=new Date()) { const packetlist = new packet.List(); @@ -503,7 +510,8 @@ export async function createSignaturePackets(literalDataPacket, privateKeys, sig * Verify message signatures * @param {Array} keys array of keys to verify signatures * @param {Date} date (optional) Verify the signature against the given date, i.e. check signature creation time < date < expiration time - * @returns {Array<({keyid: module:type/keyid, valid: Boolean})>} list of signer's keyid and validity of signature + * @returns {Promise>} list of signer's keyid and validity of signature + * @async */ Message.prototype.verify = function(keys, date=new Date()) { const msg = this.unwrapCompressed(); @@ -520,7 +528,8 @@ Message.prototype.verify = function(keys, date=new Date()) { * @param {Array} keys array of keys to verify signatures * @param {Signature} signature * @param {Date} date Verify the signature against the given date, i.e. check signature creation time < date < expiration time - * @returns {Array<({keyid: module:type/keyid, valid: Boolean})>} list of signer's keyid and validity of signature + * @returns {Promise>} list of signer's keyid and validity of signature + * @async */ Message.prototype.verifyDetached = function(signature, keys, date=new Date()) { const msg = this.unwrapCompressed(); @@ -541,6 +550,7 @@ Message.prototype.verifyDetached = function(signature, keys, date=new Date()) { * i.e. check signature creation time < date < expiration time * @returns {Promise>} list of signer's keyid and validity of signature + * @async */ export async function createVerificationObjects(signatureList, literalDataList, keys, date=new Date()) { return Promise.all(signatureList.map(async function(signature) { diff --git a/src/openpgp.js b/src/openpgp.js index 201b4d64..e39a5ddc 100644 --- a/src/openpgp.js +++ b/src/openpgp.js @@ -99,6 +99,7 @@ export function destroyWorker() { * @param {Number} keyExpirationTime (optional) The number of seconds after the key creation time that the key expires * @returns {Promise} The generated key object in the form: * { key:Key, privateKeyArmored:String, publicKeyArmored:String } + * @async * @static */ @@ -136,6 +137,7 @@ export function generateKey({ * @param {Number} keyExpirationTime (optional) The number of seconds after the key creation time that the key expires * @returns {Promise} The generated key object in the form: * { key:Key, privateKeyArmored:String, publicKeyArmored:String } + * @async * @static */ export function reformatKey({ @@ -165,6 +167,7 @@ export function reformatKey({ * @param {Key} privateKey the private key that is to be decrypted * @param {String} passphrase the user's passphrase chosen during key generation * @returns {Promise} the unlocked key object in the form: { key:Key } + * @async */ export function decryptKey({ privateKey, passphrase }) { if (asyncProxy) { // use web worker if available @@ -185,6 +188,7 @@ export function decryptKey({ privateKey, passphrase }) { * @param {Key} privateKey the private key that is to be decrypted * @param {String} passphrase the user's passphrase chosen during key generation * @returns {Promise} the locked key object in the form: { key:Key } + * @async */ export function encryptKey({ privateKey, passphrase }) { if (asyncProxy) { // use web worker if available @@ -227,6 +231,7 @@ export function encryptKey({ privateKey, passphrase }) { * @returns {Promise} encrypted (and optionally signed message) in the form: * {data: ASCII armored message if 'armor' is true, * message: full Message object if 'armor' is false, signature: detached signature if 'detached' is true} + * @async * @static */ export function encrypt({ data, publicKeys, privateKeys, passwords, sessionKey, filename, compression=config.compression, armor=true, detached=false, signature=null, returnSessionKey=false, wildcard=false, date=new Date()}) { @@ -278,6 +283,7 @@ export function encrypt({ data, publicKeys, privateKeys, passwords, sessionKey, * @param {Date} date (optional) use the given date for verification instead of the current time * @returns {Promise} decrypted and verified message in the form: * { data:Uint8Array|String, filename:String, signatures:[{ keyid:String, valid:Boolean }] } + * @async * @static */ export function decrypt({ message, privateKeys, passwords, sessionKeys, publicKeys, format='utf8', signature=null, date=new Date() }) { @@ -318,6 +324,7 @@ export function decrypt({ message, privateKeys, passwords, sessionKeys, publicKe * @returns {Promise} signed cleartext in the form: * {data: ASCII armored message if 'armor' is true, * message: full Message object if 'armor' is false, signature: detached signature if 'detached' is true} + * @async * @static */ export function sign({ @@ -359,6 +366,7 @@ export function sign({ * @param {Date} date (optional) use the given date for verification instead of the current time * @returns {Promise} cleartext with status of verified signatures in the form of: * { data:String, signatures: [{ keyid:String, valid:Boolean }] } + * @async * @static */ export function verify({ message, publicKeys, signature=null, date=new Date() }) { @@ -396,6 +404,7 @@ export function verify({ message, publicKeys, signature=null, date=new Date() }) * @param {String|Array} passwords (optional) passwords for the message * @param {Boolean} wildcard (optional) use a key ID of 0 instead of the public key IDs * @returns {Promise} the encrypted session key packets contained in a message object + * @async * @static */ export function encryptSessionKey({ data, algorithm, publicKeys, passwords, wildcard=false }) { @@ -421,6 +430,7 @@ export function encryptSessionKey({ data, algorithm, publicKeys, passwords, wild * @returns {Promise} Array of decrypted session key, algorithm pairs in form: * { data:Uint8Array, algorithm:String } * or 'undefined' if no key packets found + * @async * @static */ export function decryptSessionKeys({ message, privateKeys, passwords }) { diff --git a/src/packet/clone.js b/src/packet/clone.js index 83cb9221..227f67aa 100644 --- a/src/packet/clone.js +++ b/src/packet/clone.js @@ -41,7 +41,7 @@ import util from '../util'; /** * Create a packetlist from the correspoding object types. * @param {Object} options the object passed to and from the web worker - * @return {Object} a mutated version of the options optject + * @returns {Object} a mutated version of the options optject */ export function clonePackets(options) { if (options.publicKeys) { @@ -89,7 +89,7 @@ function verificationObjectToClone(verObject) { * Creates an object with the correct prototype from a corresponding packetlist. * @param {Object} options the object passed to and from the web worker * @param {String} method the public api function name to be delegated to the worker - * @return {Object} a mutated version of the options optject + * @returns {Object} a mutated version of the options optject */ export function parseClonedPackets(options) { if (options.publicKeys) { diff --git a/src/packet/compressed.js b/src/packet/compressed.js index 4a3ee47d..a06e5541 100644 --- a/src/packet/compressed.js +++ b/src/packet/compressed.js @@ -89,7 +89,7 @@ if (nodeZlib) { // Use Node native zlib for DEFLATE compression/decompression /** * @constructor */ -export default function Compressed() { +function Compressed() { /** * Packet type * @type {module:enums.packet} @@ -130,7 +130,7 @@ Compressed.prototype.read = function (bytes) { /** * Return the compressed packet. - * @return {String} binary compressed packet + * @returns {String} binary compressed packet */ Compressed.prototype.write = function () { if (this.compressed === null) { @@ -165,3 +165,5 @@ Compressed.prototype.compress = function () { this.compressed = compress_fns[this.algorithm](this.packets.write()); }; + +export default Compressed; diff --git a/src/packet/index.js b/src/packet/index.js index 5531d316..0f372eea 100644 --- a/src/packet/index.js +++ b/src/packet/index.js @@ -1,3 +1,11 @@ +/** + * @fileoverview OpenPGP packet types + * @see module:packet/all_packets + * @see module:packet/packetlist + * @see module:packet/clone + * @module packet + */ + import * as packets from './all_packets.js'; import * as clone from './clone.js'; import List from './packetlist.js'; diff --git a/src/packet/literal.js b/src/packet/literal.js index 79d08685..a3e85315 100644 --- a/src/packet/literal.js +++ b/src/packet/literal.js @@ -33,7 +33,7 @@ import enums from '../enums.js'; * @param {Date} date the creation date of the literal package * @constructor */ -export default function Literal(date=new Date()) { +function Literal(date=new Date()) { this.tag = enums.packet.literal; this.format = 'utf8'; // default format for literal data packets this.date = util.normalizeDate(date); @@ -56,7 +56,7 @@ Literal.prototype.setText = function(text) { /** * Returns literal data packets as native JavaScript string * with normalized end of line to \n - * @return {String} literal data as text + * @returns {String} literal data as text */ Literal.prototype.getText = function() { // decode UTF8 @@ -107,7 +107,7 @@ Literal.prototype.getFilename = function() { * Parsing function for a literal data packet (tag 11). * * @param {Uint8Array} input Payload of a tag 11 packet - * @return {module:packet/literal} object representation + * @returns {module:packet/literal} object representation */ Literal.prototype.read = function(bytes) { // - A one-octet field that describes how the data is formatted. @@ -126,7 +126,7 @@ Literal.prototype.read = function(bytes) { /** * Creates a string representation of the packet * - * @return {Uint8Array} Uint8Array representation of the packet + * @returns {Uint8Array} Uint8Array representation of the packet */ Literal.prototype.write = function() { const filename = util.str_to_Uint8Array(util.encode_utf8(this.filename)); @@ -138,3 +138,5 @@ Literal.prototype.write = function() { return util.concatUint8Array([format, filename_length, filename, date, data]); }; + +export default Literal; diff --git a/src/packet/marker.js b/src/packet/marker.js index f77ce0c4..2cafd114 100644 --- a/src/packet/marker.js +++ b/src/packet/marker.js @@ -34,7 +34,7 @@ import enums from '../enums.js'; /** * @constructor */ -export default function Marker() { +function Marker() { this.tag = enums.packet.marker; } @@ -47,7 +47,7 @@ export default function Marker() { * @param {Integer} len * Length of the packet or the remaining length of * input at position - * @return {module:packet/marker} Object representation + * @returns {module:packet/marker} Object representation */ Marker.prototype.read = function (bytes) { if (bytes[0] === 0x50 && // P @@ -58,3 +58,5 @@ Marker.prototype.read = function (bytes) { // marker packet does not contain "PGP" return false; }; + +export default Marker; diff --git a/src/packet/one_pass_signature.js b/src/packet/one_pass_signature.js index 7facea19..96261850 100644 --- a/src/packet/one_pass_signature.js +++ b/src/packet/one_pass_signature.js @@ -37,7 +37,7 @@ import type_keyid from '../type/keyid.js'; /** * @constructor */ -export default function OnePassSignature() { +function OnePassSignature() { this.tag = enums.packet.onePassSignature; // The packet type this.version = null; // A one-octet version number. The current version is 3. this.type = null; // A one-octet signature type. Signature types are described in {@link https://tools.ietf.org/html/rfc4880#section-5.2.1|RFC4880 Section 5.2.1}. @@ -50,7 +50,7 @@ export default function OnePassSignature() { /** * parsing function for a one-pass signature packet (tag 4). * @param {Uint8Array} bytes payload of a tag 4 packet - * @return {module:packet/one_pass_signature} object representation + * @returns {module:packet/one_pass_signature} object representation */ OnePassSignature.prototype.read = function (bytes) { let mypos = 0; @@ -82,7 +82,7 @@ OnePassSignature.prototype.read = function (bytes) { /** * creates a string representation of a one-pass signature packet - * @return {Uint8Array} a Uint8Array representation of a one-pass signature packet + * @returns {Uint8Array} a Uint8Array representation of a one-pass signature packet */ OnePassSignature.prototype.write = function () { const start = new Uint8Array([3, enums.write(enums.signature, this.type), @@ -100,3 +100,5 @@ OnePassSignature.prototype.write = function () { OnePassSignature.prototype.postCloneTypeFix = function() { this.signingKeyId = type_keyid.fromClone(this.signingKeyId); }; + +export default OnePassSignature; diff --git a/src/packet/packet.js b/src/packet/packet.js index cf226ae1..1060d5a4 100644 --- a/src/packet/packet.js +++ b/src/packet/packet.js @@ -52,7 +52,7 @@ export default { * string * * @param {Integer} length The length to encode - * @return {Uint8Array} String with openpgp length representation + * @returns {Uint8Array} String with openpgp length representation */ writeSimpleLength: function(length) { if (length < 192) { @@ -73,7 +73,7 @@ export default { * * @param {Integer} tag_type Tag type * @param {Integer} length Length of the payload - * @return {String} String of the header + * @returns {String} String of the header */ writeHeader: function(tag_type, length) { /* we're only generating v4 packet headers here */ @@ -86,7 +86,7 @@ export default { * * @param {Integer} tag_type Tag type * @param {Integer} length Length of the payload - * @return {String} String of the header + * @returns {String} String of the header */ writeOldHeader: function(tag_type, length) { if (length < 256) { @@ -103,7 +103,7 @@ export default { * @param {String} input Input stream as string * @param {integer} position Position to start parsing * @param {integer} len Length of the input from position on - * @return {Object} Returns a parsed module:packet/packet + * @returns {Object} Returns a parsed module:packet/packet */ read: function(input, position, len) { // some sanity checks diff --git a/src/packet/packetlist.js b/src/packet/packetlist.js index 0e5438ea..9c463524 100644 --- a/src/packet/packetlist.js +++ b/src/packet/packetlist.js @@ -1,8 +1,5 @@ /* eslint-disable callback-return */ /** - * This class represents a list of openpgp packets. - * Take care when iterating over it - the packets themselves - * are stored as numerical indices. * @requires util * @requires enums * @requires packet @@ -17,14 +14,19 @@ import enums from '../enums.js'; import config from '../config'; /** + * This class represents a list of openpgp packets. + * Take care when iterating over it - the packets themselves + * are stored as numerical indices. * @constructor */ -export default function Packetlist() { - /** The number of packets contained within the list. +function Packetlist() { + /** + * The number of packets contained within the list. * @readonly * @type {Integer} */ this.length = 0; } + /** * Reads a stream of binary data and interprents it as a list of packets. * @param {Uint8Array} A Uint8Array of bytes. @@ -106,8 +108,8 @@ Packetlist.prototype.pop = function() { }; /** -* Creates a new PacketList with all packets that pass the test implemented by the provided function. -*/ + * Creates a new PacketList with all packets that pass the test implemented by the provided function. + */ Packetlist.prototype.filter = function (callback) { const filtered = new Packetlist(); @@ -121,8 +123,8 @@ Packetlist.prototype.filter = function (callback) { }; /** -* Creates a new PacketList with all packets from the given types -*/ + * Creates a new PacketList with all packets from the given types + */ Packetlist.prototype.filterByTag = function (...args) { const filtered = new Packetlist(); const that = this; @@ -139,8 +141,8 @@ Packetlist.prototype.filterByTag = function (...args) { }; /** -* Executes the provided callback once for each element -*/ + * Executes the provided callback once for each element + */ Packetlist.prototype.forEach = function (callback) { for (let i = 0; i < this.length; i++) { callback(this[i], i, this); @@ -148,9 +150,9 @@ Packetlist.prototype.forEach = function (callback) { }; /** -* Returns an array containing return values of callback -* on each element -*/ + * Returns an array containing return values of callback + * on each element + */ Packetlist.prototype.map = function (callback) { const packetArray = []; @@ -162,11 +164,12 @@ Packetlist.prototype.map = function (callback) { }; /** -* Executes the callback function once for each element -* until it finds one where callback returns a truthy value -* @param {Function} callback -* @returns {Promise} -*/ + * Executes the callback function once for each element + * until it finds one where callback returns a truthy value + * @param {Function} callback + * @returns {Promise} + * @async + */ Packetlist.prototype.some = async function (callback) { for (let i = 0; i < this.length; i++) { // eslint-disable-next-line no-await-in-loop @@ -178,9 +181,9 @@ Packetlist.prototype.some = async function (callback) { }; /** -* Executes the callback function once for each element, -* returns true if all callbacks returns a truthy value -*/ + * Executes the callback function once for each element, + * returns true if all callbacks returns a truthy value + */ Packetlist.prototype.every = function (callback) { for (let i = 0; i < this.length; i++) { if (!callback(this[i], i, this)) { @@ -274,3 +277,5 @@ Packetlist.fromStructuredClone = function(packetlistClone) { } return packetlist; }; + +export default Packetlist; diff --git a/src/packet/public_key.js b/src/packet/public_key.js index 73b7366e..f51efab3 100644 --- a/src/packet/public_key.js +++ b/src/packet/public_key.js @@ -38,7 +38,7 @@ import type_mpi from '../type/mpi'; /** * @constructor */ -export default function PublicKey() { +function PublicKey() { this.tag = enums.packet.publicKey; this.version = 4; /** Key creation date. @@ -64,7 +64,7 @@ export default function PublicKey() { * Internal Parser for public keys as specified in {@link https://tools.ietf.org/html/rfc4880#section-5.5.2|RFC 4880 section 5.5.2 Public-Key Packet Formats} * called by read_tag<num> * @param {Uint8Array} bytes Input array to read the packet from - * @return {Object} This object with attributes set by the parser + * @returns {Object} This object with attributes set by the parser */ PublicKey.prototype.read = function (bytes) { let pos = 0; @@ -113,7 +113,7 @@ PublicKey.prototype.readPublicKey = PublicKey.prototype.read; /** * Same as write_private_key, but has less information because of * public key. - * @return {Uint8Array} OpenPGP packet body contents, + * @returns {Uint8Array} OpenPGP packet body contents, */ PublicKey.prototype.write = function () { const arr = []; @@ -151,7 +151,7 @@ PublicKey.prototype.writeOld = function () { /** * Calculates the key id of the key - * @return {String} A 8 byte key id + * @returns {String} A 8 byte key id */ PublicKey.prototype.getKeyId = function () { if (this.keyid) { @@ -169,7 +169,7 @@ PublicKey.prototype.getKeyId = function () { /** * Calculates the fingerprint of the key - * @return {String} A string containing the fingerprint in lowercase hex + * @returns {String} A string containing the fingerprint in lowercase hex */ PublicKey.prototype.getFingerprint = function () { if (this.fingerprint) { @@ -193,7 +193,7 @@ PublicKey.prototype.getFingerprint = function () { /** * Returns algorithm information - * @return {Promise} An object of the form {algorithm: String, bits:int, curve:String} + * @returns {Promise} An object of the form {algorithm: String, bits:int, curve:String} */ PublicKey.prototype.getAlgorithmInfo = function () { const result = {}; @@ -220,3 +220,5 @@ PublicKey.prototype.postCloneTypeFix = function() { this.keyid = type_keyid.fromClone(this.keyid); } }; + +export default PublicKey; diff --git a/src/packet/public_key_encrypted_session_key.js b/src/packet/public_key_encrypted_session_key.js index 23a90fdb..31351335 100644 --- a/src/packet/public_key_encrypted_session_key.js +++ b/src/packet/public_key_encrypted_session_key.js @@ -49,7 +49,7 @@ import crypto from '../crypto'; /** * @constructor */ -export default function PublicKeyEncryptedSessionKey() { +function PublicKeyEncryptedSessionKey() { this.tag = enums.packet.publicKeyEncryptedSessionKey; this.version = 3; @@ -104,6 +104,7 @@ PublicKeyEncryptedSessionKey.prototype.write = function () { * Encrypt session key packet * @param {module:packet/public_key} key Public key * @returns {Promise} + * @async */ PublicKeyEncryptedSessionKey.prototype.encrypt = async function (key) { let data = String.fromCharCode(enums.write(enums.symmetric, this.sessionKeyAlgorithm)); @@ -132,6 +133,7 @@ PublicKeyEncryptedSessionKey.prototype.encrypt = async function (key) { * @param {module:packet/secret_key} key * Private key with secret params unlocked * @returns {Promise} + * @async */ PublicKeyEncryptedSessionKey.prototype.decrypt = async function (key) { const algo = enums.write(enums.publicKey, this.publicKeyAlgorithm); @@ -170,3 +172,5 @@ PublicKeyEncryptedSessionKey.prototype.postCloneTypeFix = function() { this.encrypted[i] = types[i].fromClone(this.encrypted[i]); } }; + +export default PublicKeyEncryptedSessionKey; diff --git a/src/packet/public_subkey.js b/src/packet/public_subkey.js index 1c71a77a..6f38b68e 100644 --- a/src/packet/public_subkey.js +++ b/src/packet/public_subkey.js @@ -28,10 +28,12 @@ import enums from '../enums.js'; * @constructor * @extends module:packet/public_key */ -export default function PublicSubkey() { +function PublicSubkey() { publicKey.call(this); this.tag = enums.packet.publicSubkey; } PublicSubkey.prototype = new publicKey(); PublicSubkey.prototype.constructor = PublicSubkey; + +export default PublicSubkey; diff --git a/src/packet/secret_key.js b/src/packet/secret_key.js index f23343fe..2d22a283 100644 --- a/src/packet/secret_key.js +++ b/src/packet/secret_key.js @@ -42,7 +42,7 @@ import type_keyid from '../type/keyid.js'; * @constructor * @extends module:packet/public_key */ -export default function SecretKey() { +function SecretKey() { publicKey.call(this); this.tag = enums.packet.secretKey; // encrypted secret-key data @@ -173,6 +173,7 @@ SecretKey.prototype.write = function () { * This can be used to remove passphrase protection after calling decrypt(). * @param {String} passphrase * @returns {Promise} + * @async */ SecretKey.prototype.encrypt = async function (passphrase) { if (this.isDecrypted && !passphrase) { @@ -213,6 +214,7 @@ function produceEncryptionKey(s2k, passphrase, algorithm) { * * @param {String} passphrase The passphrase for this private key as string * @returns {Promise} + * @async */ SecretKey.prototype.decrypt = async function (passphrase) { if (this.isDecrypted) { @@ -306,3 +308,5 @@ SecretKey.prototype.postCloneTypeFix = function() { this.keyid = type_keyid.fromClone(this.keyid); } }; + +export default SecretKey; diff --git a/src/packet/secret_subkey.js b/src/packet/secret_subkey.js index 2439cf7b..3423a980 100644 --- a/src/packet/secret_subkey.js +++ b/src/packet/secret_subkey.js @@ -28,10 +28,12 @@ import enums from '../enums.js'; * @constructor * @extends module:packet/secret_key */ -export default function SecretSubkey() { +function SecretSubkey() { secretKey.call(this); this.tag = enums.packet.secretSubkey; } SecretSubkey.prototype = new secretKey(); SecretSubkey.prototype.constructor = SecretSubkey; + +export default SecretSubkey; diff --git a/src/packet/signature.js b/src/packet/signature.js index 8f405adf..5e559af8 100644 --- a/src/packet/signature.js +++ b/src/packet/signature.js @@ -42,7 +42,7 @@ import type_keyid from '../type/keyid.js'; * @constructor * @param {Date} date the creation date of the signature */ -export default function Signature(date=new Date()) { +function Signature(date=new Date()) { this.tag = enums.packet.signature; this.version = 4; this.signatureType = null; @@ -94,7 +94,7 @@ export default function Signature(date=new Date()) { * @param {String} bytes payload of a tag 2 packet * @param {Integer} position position to start reading from the bytes string * @param {Integer} len length of the packet or the remaining length of bytes at position - * @return {module:packet/signature} object representation + * @returns {module:packet/signature} object representation */ Signature.prototype.read = function (bytes) { let i = 0; @@ -213,6 +213,7 @@ Signature.prototype.write = function () { * @param {module:packet/secret_key} key private key used to sign the message. * @param {Object} data Contains packets to be signed. * @returns {Promise} + * @async */ Signature.prototype.sign = async function (key, data) { const signatureType = enums.write(enums.signature, this.signatureType); @@ -254,7 +255,7 @@ Signature.prototype.sign = async function (key, data) { /** * Creates string of bytes with all subpacket data - * @return {String} a string-representation of a all subpacket data + * @returns {String} a string-representation of a all subpacket data */ Signature.prototype.write_all_sub_packets = function () { const sub = enums.signatureSubpacket; @@ -366,7 +367,7 @@ Signature.prototype.write_all_sub_packets = function () { * @param {Integer} type subpacket signature type. Signature types as described * in {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.2|RFC4880 Section 5.2.3.2} * @param {String} data data to be included - * @return {String} a string-representation of a sub signature packet (See {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.1|RFC 4880 5.2.3.1}) + * @returns {String} a string-representation of a sub signature packet (See {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.1|RFC 4880 5.2.3.1}) */ function write_sub_packet(type, data) { const arr = []; @@ -618,7 +619,8 @@ Signature.prototype.calculateTrailer = function () { * @param {String|Object} data data which on the signature applies * @param {module:packet/public_subkey|module:packet/public_key| * module:packet/secret_subkey|module:packet/secret_key} key the public key to verify the signature - * @return {Promise} True if message is verified, else false. + * @returns {Promise} True if message is verified, else false. + * @async */ Signature.prototype.verify = async function (key, data) { const signatureType = enums.write(enums.signature, this.signatureType); @@ -664,7 +666,7 @@ Signature.prototype.verify = async function (key, data) { /** * Verifies signature expiration date * @param {Date} date (optional) use the given date for verification instead of the current time - * @return {Boolean} true if expired + * @returns {Boolean} true if expired */ Signature.prototype.isExpired = function (date=new Date()) { const normDate = util.normalizeDate(date); @@ -681,3 +683,5 @@ Signature.prototype.isExpired = function (date=new Date()) { Signature.prototype.postCloneTypeFix = function() { this.issuerKeyId = type_keyid.fromClone(this.issuerKeyId); }; + +export default Signature; diff --git a/src/packet/sym_encrypted_aead_protected.js b/src/packet/sym_encrypted_aead_protected.js index af469913..4e2449fb 100644 --- a/src/packet/sym_encrypted_aead_protected.js +++ b/src/packet/sym_encrypted_aead_protected.js @@ -16,21 +16,24 @@ // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA /** - * Implementation of the Symmetrically Encrypted Authenticated Encryption with Additional Data (AEAD) Protected Data Packet - * {@link https://tools.ietf.org/html/draft-ford-openpgp-format-00#section-2.1}: AEAD Protected Data Packet + * Implementation of the Symmetrically Encrypted Authenticated Encryption with + * Additional Data (AEAD) Protected Data Packet + * + * {@link https://tools.ietf.org/html/draft-ford-openpgp-format-00#section-2.1}: + * AEAD Protected Data Packet */ -import util from '../util.js'; +import util from '../util'; import crypto from '../crypto'; -import enums from '../enums.js'; +import enums from '../enums'; const VERSION = 1; // A one-octet version number of the data packet. const IV_LEN = crypto.gcm.ivLength; // currently only AES-GCM is supported /** - * @constructor + * @class */ -export default function SymEncryptedAEADProtected() { +function SymEncryptedAEADProtected() { this.tag = enums.packet.symEncryptedAEADProtected; this.version = VERSION; this.iv = null; @@ -38,6 +41,8 @@ export default function SymEncryptedAEADProtected() { this.packets = null; } +export default SymEncryptedAEADProtected; + /** * Parse an encrypted payload of bytes in the order: version, IV, ciphertext (see specification) */ @@ -54,7 +59,7 @@ SymEncryptedAEADProtected.prototype.read = function (bytes) { /** * Write the encrypted payload of bytes in the order: version, IV, ciphertext (see specification) - * @return {Uint8Array} The encrypted payload + * @returns {Uint8Array} The encrypted payload */ SymEncryptedAEADProtected.prototype.write = function () { return util.concatUint8Array([new Uint8Array([this.version]), this.iv, this.encrypted]); @@ -64,7 +69,8 @@ SymEncryptedAEADProtected.prototype.write = function () { * Decrypt the encrypted payload. * @param {String} sessionKeyAlgorithm The session key's cipher algorithm e.g. 'aes128' * @param {Uint8Array} key The session key used to encrypt the payload - * @return {Promise} + * @returns {Promise} + * @async */ SymEncryptedAEADProtected.prototype.decrypt = async function (sessionKeyAlgorithm, key) { this.packets.read(await crypto.gcm.decrypt(sessionKeyAlgorithm, this.encrypted, key, this.iv)); @@ -75,7 +81,8 @@ SymEncryptedAEADProtected.prototype.decrypt = async function (sessionKeyAlgorith * Encrypt the packet list payload. * @param {String} sessionKeyAlgorithm The session key's cipher algorithm e.g. 'aes128' * @param {Uint8Array} key The session key used to encrypt the payload - * @return {Promise} + * @returns {Promise} + * @async */ SymEncryptedAEADProtected.prototype.encrypt = async function (sessionKeyAlgorithm, key) { this.iv = await crypto.random.getRandomBytes(IV_LEN); // generate new random IV diff --git a/src/packet/sym_encrypted_integrity_protected.js b/src/packet/sym_encrypted_integrity_protected.js index 335dfd5b..30b749b8 100644 --- a/src/packet/sym_encrypted_integrity_protected.js +++ b/src/packet/sym_encrypted_integrity_protected.js @@ -44,7 +44,7 @@ const VERSION = 1; // A one-octet version number of the data packet. /** * @constructor */ -export default function SymEncryptedIntegrityProtected() { +function SymEncryptedIntegrityProtected() { this.tag = enums.packet.symEncryptedIntegrityProtected; this.version = VERSION; /** The encrypted payload. */ @@ -79,7 +79,8 @@ SymEncryptedIntegrityProtected.prototype.write = function () { * Encrypt the payload in the packet. * @param {String} sessionKeyAlgorithm The selected symmetric encryption algorithm to be used e.g. 'aes128' * @param {Uint8Array} key The key of cipher blocksize length to be used - * @return {Promise} + * @returns {Promise} + * @async */ SymEncryptedIntegrityProtected.prototype.encrypt = async function (sessionKeyAlgorithm, key) { const bytes = this.packets.write(); @@ -105,7 +106,8 @@ SymEncryptedIntegrityProtected.prototype.encrypt = async function (sessionKeyAlg * Decrypts the encrypted data contained in the packet. * @param {String} sessionKeyAlgorithm The selected symmetric encryption algorithm to be used e.g. 'aes128' * @param {Uint8Array} key The key of cipher blocksize length to be used - * @return {Promise} + * @returns {Promise} + * @async */ SymEncryptedIntegrityProtected.prototype.decrypt = async function (sessionKeyAlgorithm, key) { let decrypted; @@ -132,6 +134,8 @@ SymEncryptedIntegrityProtected.prototype.decrypt = async function (sessionKeyAlg return true; }; +export default SymEncryptedIntegrityProtected; + ////////////////////////// // // diff --git a/src/packet/sym_encrypted_session_key.js b/src/packet/sym_encrypted_session_key.js index 6433b0ab..d4aced91 100644 --- a/src/packet/sym_encrypted_session_key.js +++ b/src/packet/sym_encrypted_session_key.js @@ -45,7 +45,7 @@ import crypto from '../crypto'; /** * @constructor */ -export default function SymEncryptedSessionKey() { +function SymEncryptedSessionKey() { this.tag = enums.packet.symEncryptedSessionKey; this.version = 4; this.sessionKey = null; @@ -63,7 +63,7 @@ export default function SymEncryptedSessionKey() { * @param {Integer} len * Length of the packet or the remaining length of * input at position - * @return {module:packet/sym_encrypted_session_key} Object representation + * @returns {module:packet/sym_encrypted_session_key} Object representation */ SymEncryptedSessionKey.prototype.read = function(bytes) { // A one-octet version number. The only currently defined version is 4. @@ -104,7 +104,8 @@ SymEncryptedSessionKey.prototype.write = function() { /** * Decrypts the session key * @param {String} passphrase The passphrase in string form - * @return {Promise} + * @returns {Promise} + * @async */ SymEncryptedSessionKey.prototype.decrypt = async function(passphrase) { const algo = this.sessionKeyEncryptionAlgorithm !== null ? @@ -128,7 +129,8 @@ SymEncryptedSessionKey.prototype.decrypt = async function(passphrase) { /** * Encrypts the session key * @param {String} passphrase The passphrase in string form - * @return {Promise} + * @returns {Promise} + * @async */ SymEncryptedSessionKey.prototype.encrypt = async function(passphrase) { const algo = this.sessionKeyEncryptionAlgorithm !== null ? @@ -160,3 +162,5 @@ SymEncryptedSessionKey.prototype.encrypt = async function(passphrase) { SymEncryptedSessionKey.prototype.postCloneTypeFix = function() { this.s2k = type_s2k.fromClone(this.s2k); }; + +export default SymEncryptedSessionKey; diff --git a/src/packet/symmetrically_encrypted.js b/src/packet/symmetrically_encrypted.js index b8ba4ccf..4150dfd0 100644 --- a/src/packet/symmetrically_encrypted.js +++ b/src/packet/symmetrically_encrypted.js @@ -36,7 +36,7 @@ import config from '../config'; /** * @constructor */ -export default function SymmetricallyEncrypted() { +function SymmetricallyEncrypted() { this.tag = enums.packet.symmetricallyEncrypted; this.encrypted = null; /** Decrypted packets contained within. @@ -59,6 +59,7 @@ SymmetricallyEncrypted.prototype.write = function () { * Symmetric key algorithm to use // See {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC4880 9.2} * @param {Uint8Array} key The key of cipher blocksize length to be used * @returns {Promise} + * @async */ SymmetricallyEncrypted.prototype.decrypt = async function (sessionKeyAlgorithm, key) { const decrypted = crypto.cfb.decrypt(sessionKeyAlgorithm, key, this.encrypted, true); @@ -80,6 +81,7 @@ SymmetricallyEncrypted.prototype.decrypt = async function (sessionKeyAlgorithm, * Symmetric key algorithm to use // See {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC4880 9.2} * @param {Uint8Array} key The key of cipher blocksize length to be used * @returns {Promise} + * @async */ SymmetricallyEncrypted.prototype.encrypt = async function (algo, key) { const data = this.packets.write(); @@ -88,3 +90,5 @@ SymmetricallyEncrypted.prototype.encrypt = async function (algo, key) { return true; }; + +export default SymmetricallyEncrypted; diff --git a/src/packet/trust.js b/src/packet/trust.js index 8eeed343..9877ec89 100644 --- a/src/packet/trust.js +++ b/src/packet/trust.js @@ -8,13 +8,15 @@ import enums from '../enums.js'; /** * @constructor */ -export default function Trust() { +function Trust() { this.tag = enums.packet.trust; } /** * Parsing function for a trust packet (tag 12). - * Currently empty as we ignore trust packets + * Currently not implemented as we ignore trust packets * @param {String} byptes payload of a tag 12 packet */ -Trust.prototype.read = function () {}; +Trust.prototype.read = function () {}; // TODO + +export default Trust; diff --git a/src/packet/user_attribute.js b/src/packet/user_attribute.js index eaabdcbf..47dd67e1 100644 --- a/src/packet/user_attribute.js +++ b/src/packet/user_attribute.js @@ -43,7 +43,7 @@ import enums from '../enums.js'; /** * @constructor */ -export default function UserAttribute() { +function UserAttribute() { this.tag = enums.packet.userAttribute; this.attributes = []; } @@ -65,7 +65,7 @@ UserAttribute.prototype.read = function(bytes) { /** * Creates a binary representation of the user attribute packet - * @return {Uint8Array} string representation + * @returns {Uint8Array} string representation */ UserAttribute.prototype.write = function() { const arr = []; @@ -79,7 +79,7 @@ UserAttribute.prototype.write = function() { /** * Compare for equality * @param {module:user_attribute~UserAttribute} usrAttr - * @return {Boolean} true if equal + * @returns {Boolean} true if equal */ UserAttribute.prototype.equals = function(usrAttr) { if (!usrAttr || !(usrAttr instanceof UserAttribute)) { @@ -89,3 +89,5 @@ UserAttribute.prototype.equals = function(usrAttr) { return attr === usrAttr.attributes[index]; }); }; + +export default UserAttribute; diff --git a/src/packet/userid.js b/src/packet/userid.js index 95bde6ba..9be7fb73 100644 --- a/src/packet/userid.js +++ b/src/packet/userid.js @@ -34,7 +34,7 @@ import enums from '../enums.js'; /** * @constructor */ -export default function Userid() { +function Userid() { this.tag = enums.packet.userid; /** A string containing the user id. Usually in the form * John Doe @@ -53,8 +53,10 @@ Userid.prototype.read = function (bytes) { /** * Creates a binary representation of the user id packet - * @return {Uint8Array} binary representation + * @returns {Uint8Array} binary representation */ Userid.prototype.write = function () { return util.str_to_Uint8Array(util.encode_utf8(this.userid)); }; + +export default Userid; diff --git a/src/signature.js b/src/signature.js index 0b2b4156..51016cff 100644 --- a/src/signature.js +++ b/src/signature.js @@ -16,16 +16,15 @@ // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA /** - * @requires crypto - * @requires encoding/armor * @requires enums * @requires packet + * @requires encoding/armor * @module signature */ import packet from './packet'; -import enums from './enums.js'; -import armor from './encoding/armor.js'; +import enums from './enums'; +import armor from './encoding/armor'; /** * @class @@ -43,7 +42,7 @@ export function Signature(packetlist) { /** * Returns ASCII armored text of signature - * @return {String} ASCII armor + * @returns {String} ASCII armor */ Signature.prototype.armor = function() { return armor.encode(enums.armor.signature, this.packets.write()); @@ -52,7 +51,7 @@ Signature.prototype.armor = function() { /** * reads an OpenPGP armored signature and returns a signature object * @param {String} armoredText text to be parsed - * @return {Signature} new signature object + * @returns {Signature} new signature object * @static */ export function readArmored(armoredText) { @@ -63,7 +62,7 @@ export function readArmored(armoredText) { /** * reads an OpenPGP signature as byte array and returns a signature object * @param {Uint8Array} input binary signature - * @return {Signature} new signature object + * @returns {Signature} new signature object * @static */ export function read(input) { diff --git a/src/type/ecdh_symkey.js b/src/type/ecdh_symkey.js index 31599aaa..6cd86631 100644 --- a/src/type/ecdh_symkey.js +++ b/src/type/ecdh_symkey.js @@ -27,7 +27,7 @@ import util from '../util'; /** * @constructor */ -export default function ECDHSymmetricKey(data) { +function ECDHSymmetricKey(data) { if (typeof data === 'undefined') { data = new Uint8Array([]); } else if (util.isString(data)) { @@ -41,7 +41,7 @@ export default function ECDHSymmetricKey(data) { /** * Read an ECDHSymmetricKey from an Uint8Array * @param {Uint8Array} input Where to read the encoded symmetric key from - * @return {Number} Number of read bytes + * @returns {Number} Number of read bytes */ ECDHSymmetricKey.prototype.read = function (input) { if (input.length >= 1) { @@ -56,7 +56,7 @@ ECDHSymmetricKey.prototype.read = function (input) { /** * Write an ECDHSymmetricKey as an Uint8Array - * @return {Uint8Array} An array containing the value + * @returns {Uint8Array} An array containing the value */ ECDHSymmetricKey.prototype.write = function () { return util.concatUint8Array([new Uint8Array([this.data.length]), this.data]); @@ -65,3 +65,5 @@ ECDHSymmetricKey.prototype.write = function () { ECDHSymmetricKey.fromClone = function (clone) { return new ECDHSymmetricKey(clone.data); }; + +export default ECDHSymmetricKey; diff --git a/src/type/kdf_params.js b/src/type/kdf_params.js index 3605fb7f..7cf1eec7 100644 --- a/src/type/kdf_params.js +++ b/src/type/kdf_params.js @@ -16,8 +16,13 @@ // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA /** - * Implementation of type KDF parameters RFC 6637 + * Implementation of type KDF parameters * + * {@link https://tools.ietf.org/html/rfc6637#section-7|RFC 6637 7}: + * A key derivation function (KDF) is necessary to implement the EC + * encryption. The Concatenation Key Derivation Function (Approved + * Alternative 1) [NIST-SP800-56A] with the KDF hash function that is + * SHA2-256 [FIPS-180-3] or stronger is REQUIRED. * @requires enums * @module type/kdf_params */ @@ -42,7 +47,7 @@ function KDFParams(data) { /** * Read KDFParams from an Uint8Array * @param {Uint8Array} input Where to read the KDFParams from - * @return {Number} Number of read bytes + * @returns {Number} Number of read bytes */ KDFParams.prototype.read = function (input) { if (input.length < 4 || input[0] !== 3 || input[1] !== 1) { @@ -55,7 +60,7 @@ KDFParams.prototype.read = function (input) { /** * Write KDFParams to an Uint8Array - * @return {Uint8Array} Array with the KDFParams value + * @returns {Uint8Array} Array with the KDFParams value */ KDFParams.prototype.write = function () { return new Uint8Array([3, 1, this.hash, this.cipher]); diff --git a/src/type/keyid.js b/src/type/keyid.js index 392d821f..c7f77cce 100644 --- a/src/type/keyid.js +++ b/src/type/keyid.js @@ -32,7 +32,7 @@ import util from '../util.js'; /** * @constructor */ -export default function Keyid() { +function Keyid() { this.bytes = ''; } @@ -90,3 +90,5 @@ Keyid.wildcard = function () { keyid.read(new Uint8Array(8)); return keyid; }; + +export default Keyid; diff --git a/src/type/mpi.js b/src/type/mpi.js index 7c76b81b..69db5980 100644 --- a/src/type/mpi.js +++ b/src/type/mpi.js @@ -39,7 +39,7 @@ import util from '../util'; /** * @constructor */ -export default function MPI(data) { +function MPI(data) { /** An implementation dependent integer */ if (data instanceof MPI) { this.data = data.data; @@ -58,7 +58,7 @@ export default function MPI(data) { * Parsing function for a MPI ({@link https://tools.ietf.org/html/rfc4880#section-3.2|RFC 4880 3.2}). * @param {Uint8Array} input Payload of MPI data * @param {String} endian Endianness of the data; 'be' for big-endian or 'le' for little-endian - * @return {Integer} Length of data read + * @returns {Integer} Length of data read */ MPI.prototype.read = function (bytes, endian='be') { if (util.isString(bytes)) { @@ -79,7 +79,7 @@ MPI.prototype.read = function (bytes, endian='be') { * {@link https://tools.ietf.org/html/rfc4880#section-3.2|RFC4880 3.2} * @param {String} endian Endianness of the payload; 'be' for big-endian or 'le' for little-endian * @param {Integer} length Length of the data part of the MPI - * @return {Uint8Aray} mpi Byte representation + * @returns {Uint8Aray} mpi Byte representation */ MPI.prototype.write = function (endian, length) { return util.Uint8Array_to_MPI(this.toUint8Array(endian, length)); @@ -139,3 +139,5 @@ MPI.prototype.fromBN = function (bn) { MPI.fromClone = function (clone) { return new MPI(clone.data); }; + +export default MPI; diff --git a/src/type/oid.js b/src/type/oid.js index b7fdb4f4..d22fbe19 100644 --- a/src/type/oid.js +++ b/src/type/oid.js @@ -40,7 +40,7 @@ import enums from '../enums'; /** * @constructor */ -export default function OID(oid) { +function OID(oid) { if (oid instanceof OID) { this.oid = oid.oid; } else if (util.isArray(oid) || @@ -58,7 +58,7 @@ export default function OID(oid) { /** * Method to read an OID object * @param {Uint8Array} input Where to read the OID from - * @return {Number} Number of read bytes + * @returns {Number} Number of read bytes */ OID.prototype.read = function (input) { if (input.length >= 1) { @@ -73,7 +73,7 @@ OID.prototype.read = function (input) { /** * Serialize an OID object - * @return {Uint8Array} Array with the serialized value the OID + * @returns {Uint8Array} Array with the serialized value the OID */ OID.prototype.write = function () { return util.concatUint8Array([new Uint8Array([this.oid.length]), this.oid]); @@ -81,7 +81,7 @@ OID.prototype.write = function () { /** * Serialize an OID object as a hex string - * @return {string} String with the hex value of the OID + * @returns {string} String with the hex value of the OID */ OID.prototype.toHex = function() { return util.Uint8Array_to_hex(this.oid); @@ -89,7 +89,7 @@ OID.prototype.toHex = function() { /** * If a known curve object identifier, return the canonical name of the curve - * @return {string} String with the canonical name of the curve + * @returns {string} String with the canonical name of the curve */ OID.prototype.getName = function() { const hex = this.toHex(); @@ -103,3 +103,5 @@ OID.prototype.getName = function() { OID.fromClone = function (clone) { return new OID(clone.oid); }; + +export default OID; diff --git a/src/type/s2k.js b/src/type/s2k.js index d0294dc1..340243e0 100644 --- a/src/type/s2k.js +++ b/src/type/s2k.js @@ -37,7 +37,7 @@ import crypto from '../crypto'; /** * @constructor */ -export default function S2K() { +function S2K() { /** @type {module:enums.hash} */ this.algorithm = 'sha256'; /** @type {module:enums.s2k} */ @@ -59,7 +59,7 @@ S2K.prototype.get_count = function () { /** * Parsing function for a string-to-key specifier ({@link https://tools.ietf.org/html/rfc4880#section-3.7|RFC 4880 3.7}). * @param {String} input Payload of string-to-key specifier - * @return {Integer} Actual length of the object + * @returns {Integer} Actual length of the object */ S2K.prototype.read = function (bytes) { let i = 0; @@ -108,7 +108,7 @@ S2K.prototype.read = function (bytes) { /** * Serializes s2k information - * @return {Uint8Array} binary representation of s2k + * @returns {Uint8Array} binary representation of s2k */ S2K.prototype.write = function () { const arr = [new Uint8Array([enums.write(enums.s2k, this.type), enums.write(enums.hash, this.algorithm)])]; @@ -136,7 +136,7 @@ S2K.prototype.write = function () { * Produces a key using the specified passphrase and the defined * hashAlgorithm * @param {String} passphrase Passphrase containing user input - * @return {Uint8Array} Produced key with a length corresponding to + * @returns {Uint8Array} Produced key with a length corresponding to * hashAlgorithm hash length */ S2K.prototype.produce_key = function (passphrase, numBytes) { @@ -203,3 +203,5 @@ S2K.fromClone = function (clone) { s2k.salt = clone.salt; return s2k; }; + +export default S2K; diff --git a/src/util.js b/src/util.js index b1ec077e..3bf569df 100644 --- a/src/util.js +++ b/src/util.js @@ -43,7 +43,7 @@ const util = { * Get transferable objects to pass buffers with zero copy (similar to "pass by reference" in C++) * See: https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage * @param {Object} obj the options object to be passed to the web worker - * @return {Array} an array of binary data to be passed + * @returns {Array} an array of binary data to be passed */ getTransferables: function(obj) { if (config.zero_copy && Object.prototype.isPrototypeOf(obj)) { @@ -104,7 +104,7 @@ const util = { /** * Create hex string from a binary * @param {String} str String to convert - * @return {String} String containing the hexadecimal values + * @returns {String} String containing the hexadecimal values */ str_to_hex: function (str) { if (str === null) { @@ -127,7 +127,7 @@ const util = { /** * Create binary string from a hex encoded string * @param {String} str Hex string to convert - * @return {String} + * @returns {String} */ hex_to_str: function (hex) { let str = ''; @@ -143,7 +143,7 @@ const util = { * @see {@link module:type/mpi/MPI.fromUint8Array} * @see {@link module:type/mpi/MPI.toUint8Array} * @param {Uint8Array} bin An array of 8-bit integers to convert - * @return {Uint8Array} MPI-formatted Uint8Array + * @returns {Uint8Array} MPI-formatted Uint8Array */ Uint8Array_to_MPI: function (bin) { const size = (bin.length - 1) * 8 + util.nbits(bin[0]); @@ -156,7 +156,7 @@ const util = { * * Note: accepts both Radix-64 and URL-safe strings * @param {String} base64 Base-64 encoded string to convert - * @return {Uint8Array} An array of 8-bit integers + * @returns {Uint8Array} An array of 8-bit integers */ b64_to_Uint8Array: function (base64) { // atob(base64.replace(/\-/g, '+').replace(/_/g, '/')); @@ -167,7 +167,7 @@ const util = { * Convert an array of 8-bit integer to a Base-64 encoded string * @param {Uint8Array} bytes An array of 8-bit integers to convert * @param {bool} url If true, output is URL-safe - * @return {String} Base-64 encoded string + * @returns {String} Base-64 encoded string */ Uint8Array_to_b64: function (bytes, url) { // btoa(util.Uint8Array_to_str(bytes)).replace(/\+/g, '-').replace(/\//g, '_'); @@ -177,7 +177,7 @@ const util = { /** * Convert a hex string to an array of 8-bit integers * @param {String} hex A hex string to convert - * @return {Uint8Array} An array of 8-bit integers + * @returns {Uint8Array} An array of 8-bit integers */ hex_to_Uint8Array: function (hex) { const result = new Uint8Array(hex.length >> 1); @@ -190,7 +190,7 @@ const util = { /** * Convert an array of 8-bit integers to a hex string * @param {Uint8Array} bytes Array of 8-bit integers to convert - * @return {String} Hexadecimal representation of the array + * @returns {String} Hexadecimal representation of the array */ Uint8Array_to_hex: function (bytes) { const r = []; @@ -210,7 +210,7 @@ const util = { /** * Convert a string to an array of 8-bit integers * @param {String} str String to convert - * @return {Uint8Array} An array of 8-bit integers + * @returns {Uint8Array} An array of 8-bit integers */ str_to_Uint8Array: function (str) { if (!util.isString(str)) { @@ -227,7 +227,7 @@ const util = { /** * Convert an array of 8-bit integers to a string * @param {Uint8Array} bytes An array of 8-bit integers to convert - * @return {String} String representation of the array + * @returns {String} String representation of the array */ Uint8Array_to_str: function (bytes) { bytes = new Uint8Array(bytes); @@ -244,7 +244,7 @@ const util = { /** * Convert a native javascript string to a string of utf8 bytes * @param {String} str The string to convert - * @return {String} A valid squence of utf8 bytes + * @returns {String} A valid squence of utf8 bytes */ encode_utf8: function (str) { return unescape(encodeURIComponent(str)); @@ -253,7 +253,7 @@ const util = { /** * Convert a string of utf8 bytes to a native javascript string * @param {String} utf8 A valid squence of utf8 bytes - * @return {String} A native javascript string + * @returns {String} A native javascript string */ decode_utf8: function (utf8) { if (typeof utf8 !== 'string') { @@ -269,7 +269,7 @@ const util = { /** * Concat Uint8arrays * @param {Array} Array of Uint8Arrays to concatenate - * @return {Uint8array} Concatenated array + * @returns {Uint8array} Concatenated array */ concatUint8Array: function (arrays) { let totalLength = 0; @@ -294,7 +294,7 @@ const util = { /** * Deep copy Uint8Array * @param {Uint8Array} Array to copy - * @return {Uint8Array} new Uint8Array + * @returns {Uint8Array} new Uint8Array */ copyUint8Array: function (array) { if (!util.isUint8Array(array)) { @@ -310,7 +310,7 @@ const util = { * Check Uint8Array equality * @param {Uint8Array} first array * @param {Uint8Array} second array - * @return {Boolean} equality + * @returns {Boolean} equality */ equalsUint8Array: function (array1, array2) { if (!util.isUint8Array(array1) || !util.isUint8Array(array2)) { @@ -333,7 +333,7 @@ const util = { * Calculates a 16bit sum of a Uint8Array by adding each character * codes modulus 65535 * @param {Uint8Array} Uint8Array to create a sum of - * @return {Integer} An integer containing the sum of all character + * @returns {Integer} An integer containing the sum of all character * codes % 65535 */ calc_checksum: function (text) { @@ -422,7 +422,7 @@ const util = { * @param {String} value The string to shift * @param {Integer} bitcount Amount of bits to shift (MUST be smaller * than 9) - * @return {String} Resulting string. + * @returns {String} Resulting string. */ shiftRight: function (value, bitcount) { const temp = util.str_to_Uint8Array(value); @@ -443,7 +443,7 @@ const util = { * Get native Web Cryptography api, only the current version of the spec. * The default configuration is to use the api when available. But it can * be deactivated with config.use_native - * @return {Object} The SubtleCrypto api or 'undefined' + * @returns {Object} The SubtleCrypto api or 'undefined' */ getWebCrypto: function() { if (!config.use_native) { @@ -458,7 +458,7 @@ const util = { * implementations of the spec e.g IE11 and Safari 8/9. The default * configuration is to use the api when available. But it can be deactivated * with config.use_native - * @return {Object} The SubtleCrypto api or 'undefined' + * @returns {Object} The SubtleCrypto api or 'undefined' */ getWebCryptoAll: function() { if (!config.use_native) { @@ -485,7 +485,7 @@ const util = { /** * Get native Node.js crypto api. The default configuration is to use * the api when available. But it can also be deactivated with config.use_native - * @return {Object} The crypto module or 'undefined' + * @returns {Object} The crypto module or 'undefined' */ getNodeCrypto: function() { if (!util.detectNode() || !config.use_native) { @@ -498,7 +498,7 @@ const util = { /** * Get native Node.js Buffer constructor. This should be used since * Buffer is not available under browserify. - * @return {Function} The Buffer constructor or 'undefined' + * @returns {Function} The Buffer constructor or 'undefined' */ getNodeBuffer: function() { if (!util.detectNode()) { diff --git a/src/worker/async_proxy.js b/src/worker/async_proxy.js index 2d8469bb..6d13b3ba 100644 --- a/src/worker/async_proxy.js +++ b/src/worker/async_proxy.js @@ -57,7 +57,7 @@ function handleMessage(workerId) { * @param {Object} config config The worker configuration * @param {Array} worker alternative to path parameter: web worker initialized with 'openpgp.worker.js' */ -export default function AsyncProxy({ path='openpgp.worker.js', n = 1, workers = [], config } = {}) { +function AsyncProxy({ path='openpgp.worker.js', n = 1, workers = [], config } = {}) { if (workers.length) { this.workers = workers; @@ -89,7 +89,7 @@ export default function AsyncProxy({ path='openpgp.worker.js', n = 1, workers = /** * Get new request ID - * @return {integer} New unique request ID + * @returns {integer} New unique request ID */ AsyncProxy.prototype.getID = function() { return this.currentID++; @@ -117,7 +117,7 @@ AsyncProxy.prototype.terminate = function() { * Generic proxy function that handles all commands from the public api. * @param {String} method the public api function to be delegated to the worker thread * @param {Object} options the api function's options - * @return {Promise} see the corresponding public api functions for their return types + * @returns {Promise} see the corresponding public api functions for their return types */ AsyncProxy.prototype.delegate = function(method, options) { @@ -140,3 +140,5 @@ AsyncProxy.prototype.delegate = function(method, options) { this.tasks[id] = { resolve: data => resolve(packet.clone.parseClonedPackets(data, method)), reject }; }); }; + +export default AsyncProxy; diff --git a/src/worker/worker.js b/src/worker/worker.js index 7b934376..2c595cf9 100644 --- a/src/worker/worker.js +++ b/src/worker/worker.js @@ -32,7 +32,7 @@ var MIN_SIZE_RANDOM_REQUEST = 20000; /** * Handle random buffer exhaustion by requesting more random bytes from the main window - * @return {Promise} Empty promise whose resolution indicates that the buffer has been refilled + * @returns {Promise} Empty promise whose resolution indicates that the buffer has been refilled */ function randomCallback() {