Mirroristas/openpgpjs
2
0
Fork 0
mirror of https://github.com/openpgpjs/openpgpjs.git synced 2025-03-30 15:08:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clean up JSDocs

Browse Source
This commit is contained in:
Daniel Huigens 2021-02-28 00:11:14 +01:00
parent e2eadd09e4
commit 21e3ba4653
61 changed files with 1028 additions and 1027 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
openpgp.d.ts vendored
View File

@ -288,7 +288,7 @@ export class Message<T extends MaybeStream<Data>> {
/**
* Append signature to unencrypted message object
* @param {String|Uint8Array} detachedSignature The detached ASCII-armored or Uint8Array PGP signature
* @param {String|Uint8Array} detachedSignature - The detached ASCII-armored or Uint8Array PGP signature
*/
public appendSignature(detachedSignature: string | Uint8Array): Promise<void>;
@ -868,22 +868,22 @@ declare namespace util {
/**
* Convert a string to an array of 8-bit integers
* @param {String} str String to convert
* @returns {Uint8Array} An array of 8-bit integers
* @param {String} str - String to convert
* @returns {Uint8Array} An array of 8-bit integers.
*/
function strToUint8Array(str: string): Uint8Array;
/**
* Convert an array of 8-bit integers to a string
* @param {Uint8Array} bytes An array of 8-bit integers to convert
* @returns {String} String representation of the array
* @param {Uint8Array} bytes - An array of 8-bit integers to convert
* @returns {String} String representation of the array.
*/
function uint8ArrayToStr(bin: Uint8Array): string;
/**
* Convert an array of 8-bit integers to a hex string
* @param {Uint8Array} bytes Array of 8-bit integers to convert
* @returns {String} Hexadecimal representation of the array
* @param {Uint8Array} bytes - Array of 8-bit integers to convert
* @returns {String} Hexadecimal representation of the array.
*/
function uint8ArrayToHex(bytes: Uint8Array): string;
@ -893,21 +893,21 @@ declare namespace util {
/**
* Convert a hex string to an array of 8-bit integers
* @param {String} hex A hex string to convert
* @returns {Uint8Array} An array of 8-bit integers
* @param {String} hex - A hex string to convert
* @returns {Uint8Array} An array of 8-bit integers.
*/
function hexToUint8Array(hex: string): Uint8Array;
/**
* Create hex string from a binary
* @param {String} str String to convert
* @returns {String} String containing the hexadecimal values
* @param {String} str - String to convert
* @returns {String} String containing the hexadecimal values.
*/
function strToHex(str: string): string;
/**
* Create binary string from a hex encoded string
* @param {String} str Hex string to convert
* @param {String} str - Hex string to convert
* @returns {String}
*/
function hexToStr(hex: string): string;
@ -918,8 +918,8 @@ declare namespace util {
* Encode input buffer using Z-Base32 encoding.
* See: https://tools.ietf.org/html/rfc6189#section-5.1.6
*
* @param {Uint8Array} data The binary data to encode
* @returns {String} Binary data encoded using Z-Base32
* @param {Uint8Array} data - The binary data to encode
* @returns {String} Binary data encoded using Z-Base32.
*/
function encodeZBase32(data: Uint8Array): string;
}

74
src/biginteger/bn.interface.js
View File

@ -14,7 +14,7 @@ import BN from 'bn.js';
export default class BigInteger {
/**
* Get a BigInteger (input must be big endian for strings and arrays)
* @param {Number|String|Uint8Array} n value to convert
* @param {Number|String|Uint8Array} n - Value to convert
* @throws {Error} on undefined input
*/
constructor(n) {
@ -41,7 +41,7 @@ export default class BigInteger {
/**
* BigInteger increment
* @returns {BigInteger} this + 1
* @returns {BigInteger} this + 1.
*/
inc() {
return this.clone().iinc();
@ -57,7 +57,7 @@ export default class BigInteger {
/**
* BigInteger decrement
* @returns {BigInteger} this - 1
* @returns {BigInteger} this - 1.
*/
dec() {
return this.clone().idec();
@ -66,7 +66,7 @@ export default class BigInteger {
/**
* BigInteger addition in place
* @param {BigInteger} x value to add
* @param {BigInteger} x - Value to add
*/
iadd(x) {
this.value.iadd(x.value);
@ -75,8 +75,8 @@ export default class BigInteger {
/**
* BigInteger addition
* @param {BigInteger} x value to add
* @returns {BigInteger} this + x
* @param {BigInteger} x - Value to add
* @returns {BigInteger} this + x.
*/
add(x) {
return this.clone().iadd(x);
@ -84,7 +84,7 @@ export default class BigInteger {
/**
* BigInteger subtraction in place
* @param {BigInteger} x value to subtract
* @param {BigInteger} x - Value to subtract
*/
isub(x) {
this.value.isub(x.value);
@ -93,8 +93,8 @@ export default class BigInteger {
/**
* BigInteger subtraction
* @param {BigInteger} x value to subtract
* @returns {BigInteger} this - x
* @param {BigInteger} x - Value to subtract
* @returns {BigInteger} this - x.
*/
sub(x) {
return this.clone().isub(x);
@ -102,7 +102,7 @@ export default class BigInteger {
/**
* BigInteger multiplication in place
* @param {BigInteger} x value to multiply
* @param {BigInteger} x - Value to multiply
*/
imul(x) {
this.value.imul(x.value);
@ -111,8 +111,8 @@ export default class BigInteger {
/**
* BigInteger multiplication
* @param {BigInteger} x value to multiply
* @returns {BigInteger} this * x
* @param {BigInteger} x - Value to multiply
* @returns {BigInteger} this * x.
*/
mul(x) {
return this.clone().imul(x);
@ -120,7 +120,7 @@ export default class BigInteger {
/**
* Compute value modulo m, in place
* @param {BigInteger} m modulo
* @param {BigInteger} m - Modulo
*/
imod(m) {
this.value = this.value.umod(m.value);
@ -129,8 +129,8 @@ export default class BigInteger {
/**
* Compute value modulo m
* @param {BigInteger} m modulo
* @returns {BigInteger} this mod m
* @param {BigInteger} m - Modulo
* @returns {BigInteger} this mod m.
*/
mod(m) {
return this.clone().imod(m);
@ -139,9 +139,9 @@ export default class BigInteger {
/**
* Compute modular exponentiation
* Much faster than this.exp(e).mod(n)
* @param {BigInteger} e exponent
* @param {BigInteger} n modulo
* @returns {BigInteger} this ** e mod n
* @param {BigInteger} e - Exponent
* @param {BigInteger} n - Modulo
* @returns {BigInteger} this ** e mod n.
*/
modExp(e, n) {
// We use either Montgomery or normal reduction context
@ -156,8 +156,8 @@ export default class BigInteger {
/**
* Compute the inverse of this value modulo n
* Note: this and and n must be relatively prime
* @param {BigInteger} n modulo
* @return {BigInteger} x such that this*x = 1 mod n
* @param {BigInteger} n - Modulo
* @returns {BigInteger} x such that this*x = 1 mod n
* @throws {Error} if the inverse does not exist
*/
modInv(n) {
@ -170,8 +170,8 @@ export default class BigInteger {
/**
* Compute greatest common divisor between this and n
* @param {BigInteger} n operand
* @return {BigInteger} gcd
* @param {BigInteger} n - Operand
* @returns {BigInteger} gcd
*/
gcd(n) {
return new BigInteger(this.value.gcd(n.value));
@ -179,7 +179,7 @@ export default class BigInteger {
/**
* Shift this to the left by x, in place
* @param {BigInteger} x shift value
* @param {BigInteger} x - Shift value
*/
ileftShift(x) {
this.value.ishln(x.value.toNumber());
@ -188,8 +188,8 @@ export default class BigInteger {
/**
* Shift this to the left by x
* @param {BigInteger} x shift value
* @returns {BigInteger} this << x
* @param {BigInteger} x - Shift value
* @returns {BigInteger} this << x.
*/
leftShift(x) {
return this.clone().ileftShift(x);
@ -197,7 +197,7 @@ export default class BigInteger {
/**
* Shift this to the right by x, in place
* @param {BigInteger} x shift value
* @param {BigInteger} x - Shift value
*/
irightShift(x) {
this.value.ishrn(x.value.toNumber());
@ -206,8 +206,8 @@ export default class BigInteger {
/**
* Shift this to the right by x
* @param {BigInteger} x shift value
* @returns {BigInteger} this >> x
* @param {BigInteger} x - Shift value
* @returns {BigInteger} this >> x.
*/
rightShift(x) {
return this.clone().irightShift(x);
@ -282,7 +282,7 @@ export default class BigInteger {
/**
* Get this value as a string
* @returns {String} this value
* @returns {String} this value.
*/
toString() {
return this.value.toString();
@ -291,7 +291,7 @@ export default class BigInteger {
/**
* Get this value as an exact Number (max 53 bits)
* Fails if this value is too large
* @return {Number}
* @returns {Number}
*/
toNumber() {
return this.value.toNumber();
@ -299,8 +299,8 @@ export default class BigInteger {
/**
* Get value of i-th bit
* @param {Number} i bit index
* @returns {Number} bit value
* @param {Number} i - Bit index
* @returns {Number} Bit value.
*/
getBit(i) {
return this.value.testn(i) ? 1 : 0;
@ -308,7 +308,7 @@ export default class BigInteger {
/**
* Compute bit length
* @returns {Number} bit length
* @returns {Number} Bit length.
*/
bitLength() {
return this.value.bitLength();
@ -316,7 +316,7 @@ export default class BigInteger {
/**
* Compute byte length
* @returns {Number} byte length
* @returns {Number} Byte length.
*/
byteLength() {
return this.value.byteLength();
@ -324,9 +324,9 @@ export default class BigInteger {
/**
* Get Uint8Array representation of this number
* @param {String} endian endianess of output array (defaults to 'be')
* @param {Number} length of output array
* @return {Uint8Array}
* @param {String} endian - Endianess of output array (defaults to 'be')
* @param {Number} length - Of output array
* @returns {Uint8Array}
*/
toUint8Array(endian = 'be', length) {
return this.value.toArrayLike(Uint8Array, endian, length);

76
src/biginteger/native.interface.js
View File

@ -16,7 +16,7 @@
export default class BigInteger {
/**
* Get a BigInteger (input must be big endian for strings and arrays)
* @param {Number|String|Uint8Array} n value to convert
* @param {Number|String|Uint8Array} n - Value to convert
* @throws {Error} on null or undefined input
*/
constructor(n) {
@ -51,7 +51,7 @@ export default class BigInteger {
/**
* BigInteger increment
* @returns {BigInteger} this + 1
* @returns {BigInteger} this + 1.
*/
inc() {
return this.clone().iinc();
@ -67,7 +67,7 @@ export default class BigInteger {
/**
* BigInteger decrement
* @returns {BigInteger} this - 1
* @returns {BigInteger} this - 1.
*/
dec() {
return this.clone().idec();
@ -75,7 +75,7 @@ export default class BigInteger {
/**
* BigInteger addition in place
* @param {BigInteger} x value to add
* @param {BigInteger} x - Value to add
*/
iadd(x) {
this.value += x.value;
@ -84,8 +84,8 @@ export default class BigInteger {
/**
* BigInteger addition
* @param {BigInteger} x value to add
* @returns {BigInteger} this + x
* @param {BigInteger} x - Value to add
* @returns {BigInteger} this + x.
*/
add(x) {
return this.clone().iadd(x);
@ -93,7 +93,7 @@ export default class BigInteger {
/**
* BigInteger subtraction in place
* @param {BigInteger} x value to subtract
* @param {BigInteger} x - Value to subtract
*/
isub(x) {
this.value -= x.value;
@ -102,8 +102,8 @@ export default class BigInteger {
/**
* BigInteger subtraction
* @param {BigInteger} x value to subtract
* @returns {BigInteger} this - x
* @param {BigInteger} x - Value to subtract
* @returns {BigInteger} this - x.
*/
sub(x) {
return this.clone().isub(x);
@ -111,7 +111,7 @@ export default class BigInteger {
/**
* BigInteger multiplication in place
* @param {BigInteger} x value to multiply
* @param {BigInteger} x - Value to multiply
*/
imul(x) {
this.value *= x.value;
@ -120,8 +120,8 @@ export default class BigInteger {
/**
* BigInteger multiplication
* @param {BigInteger} x value to multiply
* @returns {BigInteger} this * x
* @param {BigInteger} x - Value to multiply
* @returns {BigInteger} this * x.
*/
mul(x) {
return this.clone().imul(x);
@ -129,7 +129,7 @@ export default class BigInteger {
/**
* Compute value modulo m, in place
* @param {BigInteger} m modulo
* @param {BigInteger} m - Modulo
*/
imod(m) {
this.value %= m.value;
@ -141,8 +141,8 @@ export default class BigInteger {
/**
* Compute value modulo m
* @param {BigInteger} m modulo
* @returns {BigInteger} this mod m
* @param {BigInteger} m - Modulo
* @returns {BigInteger} this mod m.
*/
mod(m) {
return this.clone().imod(m);
@ -150,9 +150,9 @@ export default class BigInteger {
/**
* Compute modular exponentiation using square and multiply
* @param {BigInteger} e exponent
* @param {BigInteger} n modulo
* @returns {BigInteger} this ** e mod n
* @param {BigInteger} e - Exponent
* @param {BigInteger} n - Modulo
* @returns {BigInteger} this ** e mod n.
*/
modExp(e, n) {
if (n.isZero()) throw Error("Modulo cannot be zero");
@ -180,8 +180,8 @@ export default class BigInteger {
/**
* Compute the inverse of this value modulo n
* Note: this and and n must be relatively prime
* @param {BigInteger} n modulo
* @return {BigInteger} x such that this*x = 1 mod n
* @param {BigInteger} n - Modulo
* @returns {BigInteger} x such that this*x = 1 mod n
* @throws {Error} if the inverse does not exist
*/
modInv(n) {
@ -195,7 +195,7 @@ export default class BigInteger {
/**
* Extended Eucleadian algorithm (http://anh.cs.luc.edu/331/notes/xgcd.pdf)
* Given a = this and b, compute (x, y) such that ax + by = gdc(a, b)
* @param {BigInteger} b second operand
* @param {BigInteger} b - Second operand
* @returns {{ gcd, x, y: BigInteger }}
*/
_egcd(b) {
@ -231,8 +231,8 @@ export default class BigInteger {
/**
* Compute greatest common divisor between this and n
* @param {BigInteger} b operand
* @return {BigInteger} gcd
* @param {BigInteger} b - Operand
* @returns {BigInteger} gcd
*/
gcd(b) {
let a = this.value;
@ -247,7 +247,7 @@ export default class BigInteger {
/**
* Shift this to the left by x, in place
* @param {BigInteger} x shift value
* @param {BigInteger} x - Shift value
*/
ileftShift(x) {
this.value <<= x.value;
@ -256,8 +256,8 @@ export default class BigInteger {
/**
* Shift this to the left by x
* @param {BigInteger} x shift value
* @returns {BigInteger} this << x
* @param {BigInteger} x - Shift value
* @returns {BigInteger} this << x.
*/
leftShift(x) {
return this.clone().ileftShift(x);
@ -265,7 +265,7 @@ export default class BigInteger {
/**
* Shift this to the right by x, in place
* @param {BigInteger} x shift value
* @param {BigInteger} x - Shift value
*/
irightShift(x) {
this.value >>= x.value;
@ -274,8 +274,8 @@ export default class BigInteger {
/**
* Shift this to the right by x
* @param {BigInteger} x shift value
* @returns {BigInteger} this >> x
* @param {BigInteger} x - Shift value
* @returns {BigInteger} this >> x.
*/
rightShift(x) {
return this.clone().irightShift(x);
@ -352,7 +352,7 @@ export default class BigInteger {
/**
* Get this value as a string
* @returns {String} this value
* @returns {String} this value.
*/
toString() {
return this.value.toString();
@ -361,7 +361,7 @@ export default class BigInteger {
/**
* Get this value as an exact Number (max 53 bits)
* Fails if this value is too large
* @return {Number}
* @returns {Number}
*/
toNumber() {
const number = Number(this.value);
@ -374,8 +374,8 @@ export default class BigInteger {
/**
* Get value of i-th bit
* @param {Number} i bit index
* @returns {Number} bit value
* @param {Number} i - Bit index
* @returns {Number} Bit value.
*/
getBit(i) {
const bit = (this.value >> BigInt(i)) & BigInt(1);
@ -384,7 +384,7 @@ export default class BigInteger {
/**
* Compute bit length
* @returns {Number} bit length
* @returns {Number} Bit length.
*/
bitLength() {
const zero = new BigInteger(0);
@ -404,7 +404,7 @@ export default class BigInteger {
/**
* Compute byte length
* @returns {Number} byte length
* @returns {Number} Byte length.
*/
byteLength() {
const zero = new BigInteger(0);
@ -422,9 +422,9 @@ export default class BigInteger {
/**
* Get Uint8Array representation of this number
* @param {String} endian endianess of output array (defaults to 'be')
* @param {Number} length of output array
* @return {Uint8Array}
* @param {String} endian - Endianess of output array (defaults to 'be')
* @param {Number} length - Of output array
* @returns {Uint8Array}
*/
toUint8Array(endian = 'be', length) {
// we get and parse the hex string (https://coolaj86.com/articles/convert-js-bigints-to-typedarrays/)

66
src/cleartext.js
View File

@ -29,8 +29,8 @@ import defaultConfig from './config';
*/
export class CleartextMessage {
/**
* @param {String} text The cleartext of the signed message
* @param {Signature} signature The detached signature or an empty signature for unsigned messages
* @param {String} text - The cleartext of the signed message
* @param {Signature} signature - The detached signature or an empty signature for unsigned messages
*/
constructor(text, signature) {
// normalize EOL to canonical form <CR><LF>
@ -43,7 +43,7 @@ export class CleartextMessage {
/**
* Returns the key IDs of the keys that signed the cleartext message
* @returns {Array<module:type/keyid~Keyid>} array of keyid objects
* @returns {Array<module:type/keyid~Keyid>} Array of keyid objects.
*/
getSigningKeyIds() {
const keyIds = [];
@ -56,13 +56,13 @@ export class CleartextMessage {
/**
* Sign the cleartext message
* @param {Array<Key>} privateKeys private keys with decrypted secret key data for signing
* @param {Signature} [signature] - any existing detached signature
* @param {Array<module:type/keyid~Keyid>} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - The creation time of the signature that should be created
* @param {Array} [userIds] - user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<CleartextMessage>} new cleartext message with signed content
* @param {Array<Key>} privateKeys - private keys with decrypted secret key data for signing
* @param {Signature} [signature] - Any existing detached signature
* @param {Array<module:type/keyid~Keyid>} [signingKeyIds] - Array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - The creation time of the signature that should be created
* @param {Array} [userIds] - User IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<CleartextMessage>} New cleartext message with signed content.
* @async
*/
async sign(privateKeys, signature = null, signingKeyIds = [], date = new Date(), userIds = [], config = defaultConfig) {
@ -71,13 +71,13 @@ export class CleartextMessage {
/**
* Sign the cleartext message
* @param {Array<Key>} privateKeys private keys with decrypted secret key data for signing
* @param {Signature} [signature] - any existing detached signature
* @param {Array<module:type/keyid~Keyid>} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - The creation time of the signature that should be created
* @param {Array} [userIds] - user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<Signature>} new detached signature of message content
* @param {Array<Key>} privateKeys - private keys with decrypted secret key data for signing
* @param {Signature} [signature] - Any existing detached signature
* @param {Array<module:type/keyid~Keyid>} [signingKeyIds] - Array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - The creation time of the signature that should be created
* @param {Array} [userIds] - User IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Signature>} New detached signature of message content.
* @async
*/
async signDetached(privateKeys, signature = null, signingKeyIds = [], date = new Date(), userIds = [], config = defaultConfig) {
@ -89,10 +89,10 @@ export class CleartextMessage {
/**
* Verify signatures of cleartext signed message
* @param {Array<Key>} 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
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Array<{keyid: module:type/keyid~Keyid, valid: Boolean}>>} list of signer's keyid and validity of signature
* @param {Array<Key>} keys - Array of keys to verify signatures
* @param {Date} [date] - Verify the signature against the given date, i.e. check signature creation time < date < expiration time
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<{keyid: module:type/keyid~Keyid, valid: Boolean}>>} List of signer's keyid and validity of signature.
* @async
*/
verify(keys, date = new Date(), config = defaultConfig) {
@ -101,10 +101,10 @@ export class CleartextMessage {
/**
* Verify signatures of cleartext signed message
* @param {Array<Key>} 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
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Array<{keyid: module:type/keyid~Keyid, valid: Boolean}>>} list of signer's keyid and validity of signature
* @param {Array<Key>} keys - Array of keys to verify signatures
* @param {Date} [date] - Verify the signature against the given date, i.e. check signature creation time < date < expiration time
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<{keyid: module:type/keyid~Keyid, valid: Boolean}>>} List of signer's keyid and validity of signature.
* @async
*/
verifyDetached(signature, keys, date = new Date(), config = defaultConfig) {
@ -117,7 +117,7 @@ export class CleartextMessage {
/**
* Get cleartext
* @returns {String} cleartext of message
* @returns {String} Cleartext of message.
*/
getText() {
// normalize end of line to \n
@ -126,8 +126,8 @@ export class CleartextMessage {
/**
* Returns ASCII armored text of cleartext signed message
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {String | ReadableStream<String>} ASCII armor
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {String | ReadableStream<String>} ASCII armor.
*/
armor(config = defaultConfig) {
let hashes = this.signature.packets.map(function(packet) {
@ -156,9 +156,9 @@ export class CleartextMessage {
/**
* Reads an OpenPGP cleartext signed message and returns a CleartextMessage object
* @param {Object} options
* @param {String | ReadableStream<String>} options.cleartextMessage - text to be parsed
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {CleartextMessage} new cleartext message object
* @param {String | ReadableStream<String>} options.cleartextMessage - Text to be parsed
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {CleartextMessage} New cleartext message object.
* @async
* @static
*/
@ -180,8 +180,8 @@ export async function readCleartextMessage({ cleartextMessage, config }) {
/**
* Compare hash algorithm specified in the armor header with signatures
* @param {Array<String>} headers Armor headers
* @param {PacketList} packetlist The packetlist with signature packets
* @param {Array<String>} headers - Armor headers
* @param {PacketList} packetlist - The packetlist with signature packets
* @private
*/
function verifyHeaders(headers, packetlist) {

14
src/crypto/cipher/index.js
View File

@ -13,7 +13,7 @@ import BF from './blowfish';
/**
* AES-128 encryption and decryption (ID 7)
* @function
* @param {String} key 128-bit key
* @param {String} key - 128-bit key
* @see {@link https://github.com/asmcrypto/asmcrypto.js|asmCrypto}
* @see {@link https://csrc.nist.gov/publications/fips/fips197/fips-197.pdf|NIST FIPS-197}
* @returns {Object}
@ -22,7 +22,7 @@ export const aes128 = aes(128);
/**
* AES-128 Block Cipher (ID 8)
* @function
* @param {String} key 192-bit key
* @param {String} key - 192-bit key
* @see {@link https://github.com/asmcrypto/asmcrypto.js|asmCrypto}
* @see {@link https://csrc.nist.gov/publications/fips/fips197/fips-197.pdf|NIST FIPS-197}
* @returns {Object}
@ -31,7 +31,7 @@ export const aes192 = aes(192);
/**
* AES-128 Block Cipher (ID 9)
* @function
* @param {String} key 256-bit key
* @param {String} key - 256-bit key
* @see {@link https://github.com/asmcrypto/asmcrypto.js|asmCrypto}
* @see {@link https://csrc.nist.gov/publications/fips/fips197/fips-197.pdf|NIST FIPS-197}
* @returns {Object}
@ -42,7 +42,7 @@ export const des = DES;
/**
* Triple DES Block Cipher (ID 2)
* @function
* @param {String} key 192-bit key
* @param {String} key - 192-bit key
* @see {@link https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-67r2.pdf|NIST SP 800-67}
* @returns {Object}
*/
@ -50,7 +50,7 @@ export const tripledes = TripleDES;
/**
* CAST-128 Block Cipher (ID 3)
* @function
* @param {String} key 128-bit key
* @param {String} key - 128-bit key
* @see {@link https://tools.ietf.org/html/rfc2144|The CAST-128 Encryption Algorithm}
* @returns {Object}
*/
@ -58,7 +58,7 @@ export const cast5 = Cast5;
/**
* Twofish Block Cipher (ID 10)
* @function
* @param {String} key 256-bit key
* @param {String} key - 256-bit key
* @see {@link https://tools.ietf.org/html/rfc4880#ref-TWOFISH|TWOFISH}
* @returns {Object}
*/
@ -66,7 +66,7 @@ export const twofish = TF;
/**
* Blowfish Block Cipher (ID 4)
* @function
* @param {String} key 128-bit key
* @param {String} key - 128-bit key
* @see {@link https://tools.ietf.org/html/rfc4880#ref-BLOWFISH|BLOWFISH}
* @returns {Object}
*/

72
src/crypto/crypto.js
View File

@ -37,11 +37,11 @@ import { Curve } from './public_key/elliptic/curves';
/**
* Encrypts data using specified algorithm and public key parameters.
* See {@link https://tools.ietf.org/html/rfc4880#section-9.1|RFC 4880 9.1} for public key algorithms.
* @param {module:enums.publicKey} algo Public key algorithm
* @param {Object} publicParams Algorithm-specific public key parameters
* @param {Uint8Array} data Data to be encrypted
* @param {Uint8Array} fingerprint Recipient fingerprint
* @returns {Object} Encrypted session key parameters
* @param {module:enums.publicKey} algo - Public key algorithm
* @param {Object} publicParams - Algorithm-specific public key parameters
* @param {Uint8Array} data - Data to be encrypted
* @param {Uint8Array} fingerprint - Recipient fingerprint
* @returns {Object} Encrypted session key parameters.
* @async
*/
export async function publicKeyEncrypt(algo, publicParams, data, fingerprint) {
@ -70,12 +70,12 @@ export async function publicKeyEncrypt(algo, publicParams, data, fingerprint) {
/**
* Decrypts data using specified algorithm and private key parameters.
* See {@link https://tools.ietf.org/html/rfc4880#section-5.5.3|RFC 4880 5.5.3}
* @param {module:enums.publicKey} algo Public key algorithm
* @param {Object} publicKeyParams Algorithm-specific public key parameters
* @param {Object} privateKeyParams Algorithm-specific private key parameters
* @param {Object} sessionKeyParams Encrypted session key parameters
* @param {Uint8Array} fingerprint Recipient fingerprint
* @returns {Uint8Array} Decrypted data
* @param {module:enums.publicKey} algo - Public key algorithm
* @param {Object} publicKeyParams - Algorithm-specific public key parameters
* @param {Object} privateKeyParams - Algorithm-specific private key parameters
* @param {Object} sessionKeyParams - Encrypted session key parameters
* @param {Uint8Array} fingerprint - Recipient fingerprint
* @returns {Uint8Array} Decrypted data.
* @async
*/
export async function publicKeyDecrypt(algo, publicKeyParams, privateKeyParams, sessionKeyParams, fingerprint) {
@ -107,9 +107,9 @@ export async function publicKeyDecrypt(algo, publicKeyParams, privateKeyParams,
/**
* Parse public key material in binary form to get the key parameters
* @param {module:enums.publicKey} algo The key algorithm
* @param {Uint8Array} bytes The key material to parse
* @returns {{ read: Number, publicParams: Object }} Number of read bytes plus key parameters referenced by name
* @param {module:enums.publicKey} algo - The key algorithm
* @param {Uint8Array} bytes - The key material to parse
* @returns {{ read: Number, publicParams: Object }} Number of read bytes plus key parameters referenced by name.
*/
export function parsePublicKeyParams(algo, bytes) {
let read = 0;
@ -158,10 +158,10 @@ export function parsePublicKeyParams(algo, bytes) {
/**
* Parse private key material in binary form to get the key parameters
* @param {module:enums.publicKey} algo The key algorithm
* @param {Uint8Array} bytes The key material to parse
* @param {Object} publicParams (ECC only) public params, needed to format some private params
* @returns {{ read: Number, privateParams: Object }} Number of read bytes plus the key parameters referenced by name
* @param {module:enums.publicKey} algo - The key algorithm
* @param {Uint8Array} bytes - The key material to parse
* @param {Object} publicParams - (ECC only) public params, needed to format some private params
* @returns {{ read: Number, privateParams: Object }} Number of read bytes plus the key parameters referenced by name.
*/
export function parsePrivateKeyParams(algo, bytes, publicParams) {
let read = 0;
@ -198,9 +198,9 @@ export function parsePrivateKeyParams(algo, bytes, publicParams) {
}
/** Returns the types comprising the encrypted session key of an algorithm
* @param {module:enums.publicKey} algo The key algorithm
* @param {Uint8Array} bytes The key material to parse
* @returns {Object} The session key parameters referenced by name
* @param {module:enums.publicKey} algo - The key algorithm
* @param {Uint8Array} bytes - The key material to parse
* @returns {Object} The session key parameters referenced by name.
*/
export function parseEncSessionKeyParams(algo, bytes) {
let read = 0;
@ -236,9 +236,9 @@ export function parseEncSessionKeyParams(algo, bytes) {
/**
* Convert params to MPI and serializes them in the proper order
* @param {module:enums.publicKey} algo The public key algorithm
* @param {Object} params The key parameters indexed by name
* @returns {Uint8Array} The array containing the MPIs
* @param {module:enums.publicKey} algo - The public key algorithm
* @param {Object} params - The key parameters indexed by name
* @returns {Uint8Array} The array containing the MPIs.
*/
export function serializeParams(algo, params) {
const orderedParams = Object.keys(params).map(name => {
@ -250,10 +250,10 @@ export function serializeParams(algo, params) {
/**
* Generate algorithm-specific key parameters
* @param {module:enums.publicKey} algo The public key algorithm
* @param {Integer} bits Bit length for RSA keys
* @param {module:type/oid} oid Object identifier for ECC keys
* @returns {{ publicParams: {Object}, privateParams: {Object} }} The parameters referenced by name
* @param {module:enums.publicKey} algo - The public key algorithm
* @param {Integer} bits - Bit length for RSA keys
* @param {module:type/oid} oid - Object identifier for ECC keys
* @returns {{ publicParams: {Object}, privateParams: {Object} }} The parameters referenced by name.
* @async
*/
export function generateParams(algo, bits, oid) {
@ -295,10 +295,10 @@ export function generateParams(algo, bits, oid) {
/**
* Validate algorithm-specific key parameters
* @param {module:enums.publicKey} algo The public key algorithm
* @param {Object} publicParams Algorithm-specific public key parameters
* @param {Object} privateParams Algorithm-specific private key parameters
* @returns {Promise<Boolean>} Whether the parameters are valid
* @param {module:enums.publicKey} algo - The public key algorithm
* @param {Object} publicParams - Algorithm-specific public key parameters
* @param {Object} privateParams - Algorithm-specific private key parameters
* @returns {Promise<Boolean>} Whether the parameters are valid.
* @async
*/
export async function validateParams(algo, publicParams, privateParams) {
@ -343,8 +343,8 @@ export async function validateParams(algo, publicParams, privateParams) {
/**
* 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
* @returns {Uint8Array} Random bytes with length equal to the block size of the cipher, plus the last two bytes repeated.
* @param {module:enums.symmetric} algo - Symmetric encryption algorithm
* @returns {Uint8Array} Random bytes with length equal to the block size of the cipher, plus the last two bytes repeated.
* @async
*/
export async function getPrefixRandom(algo) {
@ -356,8 +356,8 @@ export async function getPrefixRandom(algo) {
/**
* Generating a session key for the specified symmetric 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
* @returns {Uint8Array} Random bytes as a string to be used as a key
* @param {module:enums.symmetric} algo - Symmetric encryption algorithm
* @returns {Uint8Array} Random bytes as a string to be used as a key.
* @async
*/
export function generateSessionKey(algo) {

24
src/crypto/eax.js
View File

@ -77,8 +77,8 @@ async function CTR(key) {
/**
* Class to en/decrypt using EAX mode.
* @param {String} cipher The symmetric cipher algorithm to use e.g. 'aes128'
* @param {Uint8Array} key The encryption key
* @param {String} cipher - The symmetric cipher algorithm to use e.g. 'aes128'
* @param {Uint8Array} key - The encryption key
*/
async function EAX(cipher, key) {
if (cipher.substr(0, 3) !== 'aes') {
@ -96,10 +96,10 @@ async function EAX(cipher, key) {
return {
/**
* Encrypt plaintext input.
* @param {Uint8Array} plaintext The cleartext input to be encrypted
* @param {Uint8Array} nonce The nonce (16 bytes)
* @param {Uint8Array} adata Associated data to sign
* @returns {Promise<Uint8Array>} The ciphertext output
* @param {Uint8Array} plaintext - The cleartext input to be encrypted
* @param {Uint8Array} nonce - The nonce (16 bytes)
* @param {Uint8Array} adata - Associated data to sign
* @returns {Promise<Uint8Array>} The ciphertext output.
*/
encrypt: async function(plaintext, nonce, adata) {
const [
@ -120,10 +120,10 @@ async function EAX(cipher, key) {
/**
* Decrypt ciphertext input.
* @param {Uint8Array} ciphertext The ciphertext input to be decrypted
* @param {Uint8Array} nonce The nonce (16 bytes)
* @param {Uint8Array} adata Associated data to verify
* @returns {Promise<Uint8Array>} The plaintext output
* @param {Uint8Array} ciphertext - The ciphertext input to be decrypted
* @param {Uint8Array} nonce - The nonce (16 bytes)
* @param {Uint8Array} adata - Associated data to verify
* @returns {Promise<Uint8Array>} The plaintext output.
*/
decrypt: async function(ciphertext, nonce, adata) {
if (ciphertext.length < tagLength) throw new Error('Invalid EAX ciphertext');
@ -152,8 +152,8 @@ async function EAX(cipher, key) {
/**
* Get EAX nonce as defined by {@link https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-04#section-5.16.1|RFC4880bis-04, section 5.16.1}.
* @param {Uint8Array} iv The initialization vector (16 bytes)
* @param {Uint8Array} chunkIndex The chunk index (8 bytes)
* @param {Uint8Array} iv - The initialization vector (16 bytes)
* @param {Uint8Array} chunkIndex - The chunk index (8 bytes)
*/
EAX.getNonce = function(iv, chunkIndex) {
const nonce = iv.slice();

8
src/crypto/gcm.js
View File

@ -36,8 +36,8 @@ const ALGO = 'AES-GCM';
/**
* Class to en/decrypt using GCM mode.
* @param {String} cipher The symmetric cipher algorithm to use e.g. 'aes128'
* @param {Uint8Array} key The encryption key
* @param {String} cipher - The symmetric cipher algorithm to use e.g. 'aes128'
* @param {Uint8Array} key - The encryption key
*/
async function GCM(cipher, key) {
if (cipher.substr(0, 3) !== 'aes') {
@ -122,8 +122,8 @@ async function GCM(cipher, key) {
* A future version of the standard may define GCM mode differently,
* hopefully under a different ID (we use Private/Experimental algorithm
* ID 100) so that we can maintain backwards compatibility.
* @param {Uint8Array} iv The initialization vector (12 bytes)
* @param {Uint8Array} chunkIndex The chunk index (8 bytes)
* @param {Uint8Array} iv - The initialization vector (12 bytes)
* @param {Uint8Array} chunkIndex - The chunk index (8 bytes)
*/
GCM.getNonce = function(iv, chunkIndex) {
const nonce = iv.slice();

10
src/crypto/hash/index.js
View File

@ -99,9 +99,9 @@ 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
* @returns {Promise<Uint8Array>} hash value
* @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
* @returns {Promise<Uint8Array>} Hash value.
*/
digest: function(algo, data) {
switch (algo) {
@ -133,8 +133,8 @@ 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})
* @returns {Integer} Size in bytes of the resulting hash
* @param {module:enums.hash} algo - Hash algorithm type (See {@link https://tools.ietf.org/html/rfc4880#section-9.4|RFC 4880 9.4})
* @returns {Integer} Size in bytes of the resulting hash.
*/
getHashByteLength: function(algo) {
switch (algo) {

34
src/crypto/ocb.js
View File

@ -59,8 +59,8 @@ const one = new Uint8Array([1]);
/**
* Class to en/decrypt using OCB mode.
* @param {String} cipher The symmetric cipher algorithm to use e.g. 'aes128'
* @param {Uint8Array} key The encryption key
* @param {String} cipher - The symmetric cipher algorithm to use e.g. 'aes128'
* @param {Uint8Array} key - The encryption key
*/
async function OCB(cipher, key) {
@ -132,11 +132,11 @@ async function OCB(cipher, key) {
/**
* Encrypt/decrypt data.
* @param {encipher|decipher} fn Encryption/decryption block cipher function
* @param {Uint8Array} text The cleartext or ciphertext (without tag) input
* @param {Uint8Array} nonce The nonce (15 bytes)
* @param {Uint8Array} adata Associated data to sign
* @returns {Promise<Uint8Array>} The ciphertext or plaintext output, with tag appended in both cases
* @param {encipher|decipher} fn - Encryption/decryption block cipher function
* @param {Uint8Array} text - The cleartext or ciphertext (without tag) input
* @param {Uint8Array} nonce - The nonce (15 bytes)
* @param {Uint8Array} adata - Associated data to sign
* @returns {Promise<Uint8Array>} The ciphertext or plaintext output, with tag appended in both cases.
*/
function crypt(fn, text, nonce, adata) {
//
@ -220,10 +220,10 @@ async function OCB(cipher, key) {
return {
/**
* Encrypt plaintext input.
* @param {Uint8Array} plaintext The cleartext input to be encrypted
* @param {Uint8Array} nonce The nonce (15 bytes)
* @param {Uint8Array} adata Associated data to sign
* @returns {Promise<Uint8Array>} The ciphertext output
* @param {Uint8Array} plaintext - The cleartext input to be encrypted
* @param {Uint8Array} nonce - The nonce (15 bytes)
* @param {Uint8Array} adata - Associated data to sign
* @returns {Promise<Uint8Array>} The ciphertext output.
*/
encrypt: async function(plaintext, nonce, adata) {
return crypt(encipher, plaintext, nonce, adata);
@ -231,10 +231,10 @@ async function OCB(cipher, key) {
/**
* Decrypt ciphertext input.
* @param {Uint8Array} ciphertext The ciphertext input to be decrypted
* @param {Uint8Array} nonce The nonce (15 bytes)
* @param {Uint8Array} adata Associated data to sign
* @returns {Promise<Uint8Array>} The ciphertext output
* @param {Uint8Array} ciphertext - The ciphertext input to be decrypted
* @param {Uint8Array} nonce - The nonce (15 bytes)
* @param {Uint8Array} adata - Associated data to sign
* @returns {Promise<Uint8Array>} The ciphertext output.
*/
decrypt: async function(ciphertext, nonce, adata) {
if (ciphertext.length < tagLength) throw new Error('Invalid OCB ciphertext');
@ -255,8 +255,8 @@ async function OCB(cipher, key) {
/**
* Get OCB nonce as defined by {@link https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-04#section-5.16.2|RFC4880bis-04, section 5.16.2}.
* @param {Uint8Array} iv The initialization vector (15 bytes)
* @param {Uint8Array} chunkIndex The chunk index (8 bytes)
* @param {Uint8Array} iv - The initialization vector (15 bytes)
* @param {Uint8Array} chunkIndex - The chunk index (8 bytes)
*/
OCB.getNonce = function(iv, chunkIndex) {
const nonce = iv.slice();

22
src/crypto/pkcs1.js
View File

@ -48,8 +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
* @returns {Uint8Array} Random padding
* @param {Integer} length - Length of the padding in bytes
* @returns {Uint8Array} Random padding.
* @async
*/
async function getPkcs1Padding(length) {
@ -69,9 +69,9 @@ async function getPkcs1Padding(length) {
/**
* Create a EME-PKCS1-v1_5 padded message
* @see {@link https://tools.ietf.org/html/rfc4880#section-13.1.1|RFC 4880 13.1.1}
* @param {Uint8Array} message message to be encoded
* @param {Integer} keyLength the length in octets of the key modulus
* @returns {Promise<Uint8Array>} EME-PKCS1 padded message
* @param {Uint8Array} message - Message to be encoded
* @param {Integer} keyLength - The length in octets of the key modulus
* @returns {Promise<Uint8Array>} EME-PKCS1 padded message.
* @async
*/
export async function emeEncode(message, keyLength) {
@ -97,8 +97,8 @@ export async function emeEncode(message, keyLength) {
/**
* Decode a EME-PKCS1-v1_5 padded message
* @see {@link https://tools.ietf.org/html/rfc4880#section-13.1.2|RFC 4880 13.1.2}
* @param {Uint8Array} encoded encoded message bytes
* @returns {Uint8Array} message
* @param {Uint8Array} encoded - Encoded message bytes
* @returns {Uint8Array} Message.
*/
export function emeDecode(encoded) {
let i = 2;
@ -116,10 +116,10 @@ export function emeDecode(encoded) {
/**
* Create a EMSA-PKCS1-v1_5 padded message
* @see {@link https://tools.ietf.org/html/rfc4880#section-13.1.3|RFC 4880 13.1.3}
* @param {Integer} algo Hash algorithm type used
* @param {Uint8Array} hashed message to be encoded
* @param {Integer} emLen intended length in octets of the encoded message
* @returns {Uint8Array} encoded message
* @param {Integer} algo - Hash algorithm type used
* @param {Uint8Array} hashed - Message to be encoded
* @param {Integer} emLen - Intended length in octets of the encoded message
* @returns {Uint8Array} Encoded message.
*/
export async function emsaEncode(algo, hashed, emLen) {
let i;

8
src/crypto/pkcs5.js
View File

@ -26,8 +26,8 @@ import util from '../util';
/**
* Add pkcs5 padding to a message
* @param {Uint8Array} message message to pad
* @returns {Uint8Array} padded message
* @param {Uint8Array} message - message to pad
* @returns {Uint8Array} Padded message.
*/
export function encode(message) {
const c = 8 - (message.length % 8);
@ -38,8 +38,8 @@ export function encode(message) {
/**
* Remove pkcs5 padding from a message
* @param {Uint8Array} message message to remove padding from
* @returns {Uint8Array} message without padding
* @param {Uint8Array} message - message to remove padding from
* @returns {Uint8Array} Message without padding.
*/
export function decode(message) {
const len = message.length;

12
src/crypto/public_key/dsa.js
View File

@ -135,12 +135,12 @@ export async function verify(hash_algo, r, s, hashed, g, p, q, y) {
/**
* Validate DSA parameters
* @param {Uint8Array} p DSA prime
* @param {Uint8Array} q DSA group order
* @param {Uint8Array} g DSA sub-group generator
* @param {Uint8Array} y DSA public key
* @param {Uint8Array} x DSA private key
* @returns {Promise<Boolean>} whether params are valid
* @param {Uint8Array} p - DSA prime
* @param {Uint8Array} q - DSA group order
* @param {Uint8Array} g - DSA sub-group generator
* @param {Uint8Array} y - DSA public key
* @param {Uint8Array} x - DSA private key
* @returns {Promise<Boolean>} Whether params are valid.
* @async
*/
export async function validateParams(p, q, g, y, x) {

14
src/crypto/public_key/elgamal.js
View File

@ -28,7 +28,7 @@ import { emeEncode, emeDecode } from '../pkcs1';
/**
* ElGamal Encryption function
* Note that in OpenPGP, the message needs to be padded with PKCS#1 (same as RSA)
* @param {Uint8Array} data to be padded and encrypted
* @param {Uint8Array} data - To be padded and encrypted
* @param {Uint8Array} p
* @param {Uint8Array} g
* @param {Uint8Array} y
@ -59,7 +59,7 @@ export async function encrypt(data, p, g, y) {
* @param {Uint8Array} c2
* @param {Uint8Array} p
* @param {Uint8Array} x
* @returns {Uint8Array} unpadded message
* @returns {Uint8Array} Unpadded message.
* @async
*/
export async function decrypt(c1, c2, p, x) {
@ -75,11 +75,11 @@ export async function decrypt(c1, c2, p, x) {
/**
* Validate ElGamal parameters
* @param {Uint8Array} p ElGamal prime
* @param {Uint8Array} g ElGamal group generator
* @param {Uint8Array} y ElGamal public key
* @param {Uint8Array} x ElGamal private exponent
* @returns {Promise<Boolean>} whether params are valid
* @param {Uint8Array} p - ElGamal prime
* @param {Uint8Array} g - ElGamal group generator
* @param {Uint8Array} y - ElGamal public key
* @param {Uint8Array} x - ElGamal private exponent
* @returns {Promise<Boolean>} Whether params are valid.
* @async
*/
export async function validateParams(p, g, y, x) {

32
src/crypto/public_key/elliptic/curves.js
View File

@ -227,11 +227,11 @@ function getPreferredHashAlgo(oid) {
/**
* Validate ECDH and EcDSA parameters
* Not suitable for EdDSA (different secret key format)
* @param {module:enums.publicKey} algo EC algorithm, to filter supported curves
* @param {module:type/oid} oid EC object identifier
* @param {Uint8Array} Q EC public point
* @param {Uint8Array} d EC secret scalar
* @returns {Promise<Boolean>} whether params are valid
* @param {module:enums.publicKey} algo - EC algorithm, to filter supported curves
* @param {module:type/oid} oid - EC object identifier
* @param {Uint8Array} Q - EC public point
* @param {Uint8Array} d - EC secret scalar
* @returns {Promise<Boolean>} Whether params are valid.
* @async
*/
async function validateStandardParams(algo, oid, Q, d) {
@ -327,9 +327,9 @@ async function nodeGenKeyPair(name) {
//////////////////////////
/**
* @param {JsonWebKey} jwk key for conversion
* @param {JsonWebKey} jwk - key for conversion
*
* @returns {Uint8Array} raw public key
* @returns {Uint8Array} Raw public key.
*/
function jwkToRawPublic(jwk) {
const bufX = b64ToUint8Array(jwk.x);
@ -342,11 +342,11 @@ function jwkToRawPublic(jwk) {
}
/**
* @param {Integer} payloadSize ec payload size
* @param {String} name curve name
* @param {Uint8Array} publicKey public key
* @param {Integer} payloadSize - ec payload size
* @param {String} name - curve name
* @param {Uint8Array} publicKey - public key
*
* @returns {JsonWebKey} public key in jwk format
* @returns {JsonWebKey} Public key in jwk format.
*/
function rawPublicToJwk(payloadSize, name, publicKey) {
const len = payloadSize;
@ -364,12 +364,12 @@ function rawPublicToJwk(payloadSize, name, publicKey) {
}
/**
* @param {Integer} payloadSize ec payload size
* @param {String} name curve name
* @param {Uint8Array} publicKey public key
* @param {Uint8Array} privateKey private key
* @param {Integer} payloadSize - ec payload size
* @param {String} name - curve name
* @param {Uint8Array} publicKey - public key
* @param {Uint8Array} privateKey - private key
*
* @returns {JsonWebKey} private key in jwk format
* @returns {JsonWebKey} Private key in jwk format.
*/
function privateToJwk(payloadSize, name, publicKey, privateKey) {
const jwk = rawPublicToJwk(payloadSize, name, publicKey);

78
src/crypto/public_key/elliptic/ecdh.js
View File

@ -38,10 +38,10 @@ const nodeCrypto = util.getNodeCrypto();
/**
* Validate ECDH parameters
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {Uint8Array} Q ECDH public point
* @param {Uint8Array} d ECDH secret scalar
* @returns {Promise<Boolean>} whether params are valid
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {Uint8Array} Q - ECDH public point
* @param {Uint8Array} d - ECDH secret scalar
* @returns {Promise<Boolean>} Whether params are valid.
* @async
*/
export async function validateParams(oid, Q, d) {
@ -86,8 +86,8 @@ async function kdf(hash_algo, X, length, param, stripLeading = false, stripTrail
/**
* Generate ECDHE ephemeral key and secret from public key
*
* @param {Curve} curve Elliptic curve object
* @param {Uint8Array} Q Recipient public key
* @param {Curve} curve - Elliptic curve object
* @param {Uint8Array} Q - Recipient public key
* @returns {Promise<{publicKey: Uint8Array, sharedKey: Uint8Array}>}
* @async
*/
@ -118,11 +118,11 @@ async function genPublicEphemeralKey(curve, Q) {
/**
* Encrypt and wrap a session key
*
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {module:type/kdf_params} kdfParams KDF params including cipher and algorithm to use
* @param {Uint8Array} data Unpadded session key data
* @param {Uint8Array} Q Recipient public key
* @param {Uint8Array} fingerprint Recipient fingerprint
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {module:type/kdf_params} kdfParams - KDF params including cipher and algorithm to use
* @param {Uint8Array} data - Unpadded session key data
* @param {Uint8Array} Q - Recipient public key
* @param {Uint8Array} fingerprint - Recipient fingerprint
* @returns {Promise<{publicKey: Uint8Array, wrappedKey: Uint8Array}>}
* @async
*/
@ -141,10 +141,10 @@ export async function encrypt(oid, kdfParams, data, Q, fingerprint) {
/**
* Generate ECDHE secret from private key and public part of ephemeral key
*
* @param {Curve} curve Elliptic curve object
* @param {Uint8Array} V Public part of ephemeral key
* @param {Uint8Array} Q Recipient public key
* @param {Uint8Array} d Recipient private key
* @param {Curve} curve - Elliptic curve object
* @param {Uint8Array} V - Public part of ephemeral key
* @param {Uint8Array} Q - Recipient public key
* @param {Uint8Array} d - Recipient private key
* @returns {Promise<{secretKey: Uint8Array, sharedKey: Uint8Array}>}
* @async
*/
@ -178,14 +178,14 @@ async function genPrivateEphemeralKey(curve, V, Q, d) {
/**
* Decrypt and unwrap the value derived from session key
*
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {module:type/kdf_params} kdfParams KDF params including cipher and algorithm to use
* @param {Uint8Array} V Public part of ephemeral key
* @param {Uint8Array} C Encrypted and wrapped value derived from session key
* @param {Uint8Array} Q Recipient public key
* @param {Uint8Array} d Recipient private key
* @param {Uint8Array} fingerprint Recipient fingerprint
* @returns {Promise<Uint8Array>} Value derived from session key
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {module:type/kdf_params} kdfParams - KDF params including cipher and algorithm to use
* @param {Uint8Array} V - Public part of ephemeral key
* @param {Uint8Array} C - Encrypted and wrapped value derived from session key
* @param {Uint8Array} Q - Recipient public key
* @param {Uint8Array} d - Recipient private key
* @param {Uint8Array} fingerprint - Recipient fingerprint
* @returns {Promise<Uint8Array>} Value derived from session key.
* @async
*/
export async function decrypt(oid, kdfParams, V, C, Q, d, fingerprint) {
@ -209,10 +209,10 @@ export async function decrypt(oid, kdfParams, V, C, Q, d, fingerprint) {
/**
* Generate ECDHE secret from private key and public part of ephemeral key using webCrypto
*
* @param {Curve} curve Elliptic curve object
* @param {Uint8Array} V Public part of ephemeral key
* @param {Uint8Array} Q Recipient public key
* @param {Uint8Array} d Recipient private key
* @param {Curve} curve - Elliptic curve object
* @param {Uint8Array} V - Public part of ephemeral key
* @param {Uint8Array} Q - Recipient public key
* @param {Uint8Array} d - Recipient private key
* @returns {Promise<{secretKey: Uint8Array, sharedKey: Uint8Array}>}
* @async
*/
@ -262,8 +262,8 @@ async function webPrivateEphemeralKey(curve, V, Q, d) {
/**
* Generate ECDHE ephemeral key and secret from public key using webCrypto
*
* @param {Curve} curve Elliptic curve object
* @param {Uint8Array} Q Recipient public key
* @param {Curve} curve - Elliptic curve object
* @param {Uint8Array} Q - Recipient public key
* @returns {Promise<{publicKey: Uint8Array, sharedKey: Uint8Array}>}
* @async
*/
@ -310,9 +310,9 @@ async function webPublicEphemeralKey(curve, Q) {
/**
* Generate ECDHE secret from private key and public part of ephemeral key using indutny/elliptic
*
* @param {Curve} curve Elliptic curve object
* @param {Uint8Array} V Public part of ephemeral key
* @param {Uint8Array} d Recipient private key
* @param {Curve} curve - Elliptic curve object
* @param {Uint8Array} V - Public part of ephemeral key
* @param {Uint8Array} d - Recipient private key
* @returns {Promise<{secretKey: Uint8Array, sharedKey: Uint8Array}>}
* @async
*/
@ -330,8 +330,8 @@ async function ellipticPrivateEphemeralKey(curve, V, d) {
/**
* Generate ECDHE ephemeral key and secret from public key using indutny/elliptic
*
* @param {Curve} curve Elliptic curve object
* @param {Uint8Array} Q Recipient public key
* @param {Curve} curve - Elliptic curve object
* @param {Uint8Array} Q - Recipient public key
* @returns {Promise<{publicKey: Uint8Array, sharedKey: Uint8Array}>}
* @async
*/
@ -350,9 +350,9 @@ async function ellipticPublicEphemeralKey(curve, Q) {
/**
* Generate ECDHE secret from private key and public part of ephemeral key using nodeCrypto
*
* @param {Curve} curve Elliptic curve object
* @param {Uint8Array} V Public part of ephemeral key
* @param {Uint8Array} d Recipient private key
* @param {Curve} curve - Elliptic curve object
* @param {Uint8Array} V - Public part of ephemeral key
* @param {Uint8Array} d - Recipient private key
* @returns {Promise<{secretKey: Uint8Array, sharedKey: Uint8Array}>}
* @async
*/
@ -367,8 +367,8 @@ async function nodePrivateEphemeralKey(curve, V, d) {
/**
* Generate ECDHE ephemeral key and secret from public key using nodeCrypto
*
* @param {Curve} curve Elliptic curve object
* @param {Uint8Array} Q Recipient public key
* @param {Curve} curve - Elliptic curve object
* @param {Uint8Array} Q - Recipient public key
* @returns {Promise<{publicKey: Uint8Array, sharedKey: Uint8Array}>}
* @async
*/

30
src/crypto/public_key/elliptic/ecdsa.js
View File

@ -33,12 +33,12 @@ const nodeCrypto = util.getNodeCrypto();
/**
* Sign a message using the provided key
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {module:enums.hash} hash_algo Hash algorithm used to sign
* @param {Uint8Array} message Message to sign
* @param {Uint8Array} publicKey Public key
* @param {Uint8Array} privateKey Private key used to sign the message
* @param {Uint8Array} hashed The hashed message
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {module:enums.hash} hash_algo - Hash algorithm used to sign
* @param {Uint8Array} message - Message to sign
* @param {Uint8Array} publicKey - Public key
* @param {Uint8Array} privateKey - Private key used to sign the message
* @param {Uint8Array} hashed - The hashed message
* @returns {{r: Uint8Array,
* s: Uint8Array}} Signature of the message
* @async
@ -78,13 +78,13 @@ export async function sign(oid, hash_algo, message, publicKey, privateKey, hashe
/**
* Verifies if a signature is valid for a message
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {module:enums.hash} hash_algo Hash algorithm used in the signature
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {module:enums.hash} hash_algo - Hash algorithm used in the signature
* @param {{r: Uint8Array,
s: Uint8Array}} signature Signature to verify
* @param {Uint8Array} message Message to verify
* @param {Uint8Array} publicKey Public key used to verify the message
* @param {Uint8Array} hashed The hashed message
* @param {Uint8Array} message - Message to verify
* @param {Uint8Array} publicKey - Public key used to verify the message
* @param {Uint8Array} hashed - The hashed message
* @returns {Boolean}
* @async
*/
@ -116,10 +116,10 @@ export async function verify(oid, hash_algo, signature, message, publicKey, hash
/**
* Validate EcDSA parameters
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {Uint8Array} Q EcDSA public point
* @param {Uint8Array} d EcDSA secret scalar
* @returns {Promise<Boolean>} whether params are valid
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {Uint8Array} Q - EcDSA public point
* @param {Uint8Array} d - EcDSA secret scalar
* @returns {Promise<Boolean>} Whether params are valid.
* @async
*/
export async function validateParams(oid, Q, d) {

30
src/crypto/public_key/elliptic/eddsa.js
View File

@ -29,12 +29,12 @@ nacl.hash = bytes => new Uint8Array(sha512().update(bytes).digest());
/**
* Sign a message using the provided key
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {module:enums.hash} hash_algo Hash algorithm used to sign
* @param {Uint8Array} message Message to sign
* @param {Uint8Array} publicKey Public key
* @param {Uint8Array} privateKey Private key used to sign the message
* @param {Uint8Array} hashed The hashed message
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {module:enums.hash} hash_algo - Hash algorithm used to sign
* @param {Uint8Array} message - Message to sign
* @param {Uint8Array} publicKey - Public key
* @param {Uint8Array} privateKey - Private key used to sign the message
* @param {Uint8Array} hashed - The hashed message
* @returns {{r: Uint8Array,
* s: Uint8Array}} Signature of the message
* @async
@ -51,13 +51,13 @@ export async function sign(oid, hash_algo, message, publicKey, privateKey, hashe
/**
* Verifies if a signature is valid for a message
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {module:enums.hash} hash_algo Hash algorithm used in the signature
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {module:enums.hash} hash_algo - Hash algorithm used in the signature
* @param {{r: Uint8Array,
s: Uint8Array}} signature Signature to verify the message
* @param {Uint8Array} m Message to verify
* @param {Uint8Array} publicKey Public key used to verify the message
* @param {Uint8Array} hashed The hashed message
* @param {Uint8Array} m - Message to verify
* @param {Uint8Array} publicKey - Public key used to verify the message
* @param {Uint8Array} hashed - The hashed message
* @returns {Boolean}
* @async
*/
@ -67,10 +67,10 @@ export async function verify(oid, hash_algo, { r, s }, m, publicKey, hashed) {
}
/**
* Validate EdDSA parameters
* @param {module:type/oid} oid Elliptic curve object identifier
* @param {Uint8Array} Q EdDSA public point
* @param {Uint8Array} k EdDSA secret seed
* @returns {Promise<Boolean>} whether params are valid
* @param {module:type/oid} oid - Elliptic curve object identifier
* @param {Uint8Array} Q - EdDSA public point
* @param {Uint8Array} k - EdDSA secret seed
* @returns {Promise<Boolean>} Whether params are valid.
* @async
*/
export async function validateParams(oid, Q, k) {

22
src/crypto/public_key/prime.js
View File

@ -26,9 +26,9 @@ import { getRandomBigInteger } from '../random';
/**
* Probabilistic random number generator
* @param {Integer} bits Bit length of the prime
* @param {BigInteger} e Optional RSA exponent to check against the prime
* @param {Integer} k Optional number of iterations of Miller-Rabin test
* @param {Integer} bits - Bit length of the prime
* @param {BigInteger} e - Optional RSA exponent to check against the prime
* @param {Integer} k - Optional number of iterations of Miller-Rabin test
* @returns BigInteger
* @async
*/
@ -62,9 +62,9 @@ export async function randomProbablePrime(bits, e, k) {
/**
* Probabilistic primality testing
* @param {BigInteger} n Number to test
* @param {BigInteger} e Optional RSA exponent to check against the prime
* @param {Integer} k Optional number of iterations of Miller-Rabin test
* @param {BigInteger} n - Number to test
* @param {BigInteger} e - Optional RSA exponent to check against the prime
* @param {Integer} k - Optional number of iterations of Miller-Rabin test
* @returns {boolean}
* @async
*/
@ -89,8 +89,8 @@ export async function isProbablePrime(n, e, k) {
/**
* Tests whether n is probably prime or not using Fermat's test with b = 2.
* Fails if b^(n-1) mod n != 1.
* @param {BigInteger} n Number to test
* @param {BigInteger} b Optional Fermat test base
* @param {BigInteger} n - Number to test
* @param {BigInteger} b - Optional Fermat test base
* @returns {boolean}
*/
export async function fermat(n, b) {
@ -222,9 +222,9 @@ const smallPrimes = [
/**
* Tests whether n is probably prime or not using the Miller-Rabin test.
* See HAC Remark 4.28.
* @param {BigInteger} n Number to test
* @param {Integer} k Optional number of iterations of Miller-Rabin test
* @param {Function} rand Optional function to generate potential witnesses
* @param {BigInteger} n - Number to test
* @param {Integer} k - Optional number of iterations of Miller-Rabin test
* @param {Function} rand - Optional function to generate potential witnesses
* @returns {boolean}
* @async
*/

74
src/crypto/public_key/rsa.js
View File

@ -71,16 +71,16 @@ const RSAPublicKey = util.detectNode() ? asn1.define('RSAPubliceKey', function (
/* eslint-enable no-invalid-this */
/** Create signature
* @param {module:enums.hash} hash_algo Hash algorithm
* @param {Uint8Array} data message
* @param {Uint8Array} n RSA public modulus
* @param {Uint8Array} e RSA public exponent
* @param {Uint8Array} d RSA private exponent
* @param {Uint8Array} p RSA private prime p
* @param {Uint8Array} q RSA private prime q
* @param {Uint8Array} u RSA private coefficient
* @param {Uint8Array} hashed hashed message
* @returns {Uint8Array} RSA Signature
* @param {module:enums.hash} hash_algo - Hash algorithm
* @param {Uint8Array} data - Message
* @param {Uint8Array} n - RSA public modulus
* @param {Uint8Array} e - RSA public exponent
* @param {Uint8Array} d - RSA private exponent
* @param {Uint8Array} p - RSA private prime p
* @param {Uint8Array} q - RSA private prime q
* @param {Uint8Array} u - RSA private coefficient
* @param {Uint8Array} hashed - Hashed message
* @returns {Uint8Array} RSA Signature.
* @async
*/
export async function sign(hash_algo, data, n, e, d, p, q, u, hashed) {
@ -100,12 +100,12 @@ export async function sign(hash_algo, data, n, e, d, p, q, u, hashed) {
/**
* Verify signature
* @param {module:enums.hash} hash_algo Hash algorithm
* @param {Uint8Array} data message
* @param {Uint8Array} s signature
* @param {Uint8Array} n RSA public modulus
* @param {Uint8Array} e RSA public exponent
* @param {Uint8Array} hashed hashed message
* @param {module:enums.hash} hash_algo - Hash algorithm
* @param {Uint8Array} data - Message
* @param {Uint8Array} s - Signature
* @param {Uint8Array} n - RSA public modulus
* @param {Uint8Array} e - RSA public exponent
* @param {Uint8Array} hashed - Hashed message
* @returns {Boolean}
* @async
*/
@ -126,10 +126,10 @@ export async function verify(hash_algo, data, s, n, e, hashed) {
/**
* Encrypt message
* @param {Uint8Array} data message
* @param {Uint8Array} n RSA public modulus
* @param {Uint8Array} e RSA public exponent
* @returns {Uint8Array} RSA Ciphertext
* @param {Uint8Array} data - Message
* @param {Uint8Array} n - RSA public modulus
* @param {Uint8Array} e - RSA public exponent
* @returns {Uint8Array} RSA Ciphertext.
* @async
*/
export async function encrypt(data, n, e) {
@ -141,14 +141,14 @@ export async function encrypt(data, n, e) {
/**
* Decrypt RSA message
* @param {Uint8Array} m message
* @param {Uint8Array} n RSA public modulus
* @param {Uint8Array} e RSA public exponent
* @param {Uint8Array} d RSA private exponent
* @param {Uint8Array} p RSA private prime p
* @param {Uint8Array} q RSA private prime q
* @param {Uint8Array} u RSA private coefficient
* @returns {String} RSA Plaintext
* @param {Uint8Array} m - Message
* @param {Uint8Array} n - RSA public modulus
* @param {Uint8Array} e - RSA public exponent
* @param {Uint8Array} d - RSA private exponent
* @param {Uint8Array} p - RSA private prime p
* @param {Uint8Array} q - RSA private prime q
* @param {Uint8Array} u - RSA private coefficient
* @returns {String} RSA Plaintext.
* @async
*/
export async function decrypt(data, n, e, d, p, q, u) {
@ -164,8 +164,8 @@ export async function decrypt(data, n, e, d, p, q, u) {
* When possible, webCrypto or nodeCrypto is used. Otherwise, primes are generated using
* 40 rounds of the Miller-Rabin probabilistic random prime generation algorithm.
* @see module:crypto/public_key/prime
* @param {Integer} bits RSA bit length
* @param {Integer} e RSA public exponent
* @param {Integer} bits - RSA bit length
* @param {Integer} e - RSA public exponent
* @returns {{n, e, d,
* p, q ,u: Uint8Array}} RSA public modulus, RSA public exponent, RSA private exponent,
* RSA private prime p, RSA private prime q, u = p ** -1 mod q
@ -282,13 +282,13 @@ export async function generate(bits, e) {
/**
* Validate RSA parameters
* @param {Uint8Array} n RSA public modulus
* @param {Uint8Array} e RSA public exponent
* @param {Uint8Array} d RSA private exponent
* @param {Uint8Array} p RSA private prime p
* @param {Uint8Array} q RSA private prime q
* @param {Uint8Array} u RSA inverse of p w.r.t. q
* @returns {Promise<Boolean>} whether params are valid
* @param {Uint8Array} n - RSA public modulus
* @param {Uint8Array} e - RSA public exponent
* @param {Uint8Array} d - RSA private exponent
* @param {Uint8Array} p - RSA private prime p
* @param {Uint8Array} q - RSA private prime q
* @param {Uint8Array} u - RSA inverse of p w.r.t. q
* @returns {Promise<Boolean>} Whether params are valid.
* @async
*/
export async function validateParams(n, e, d, p, q, u) {

14
src/crypto/random.js
View File

@ -38,7 +38,7 @@ class RandomBuffer {
/**
* Initialize buffer
* @param {Integer} size size of buffer
* @param {Integer} size - size of buffer
*/
init(size, callback) {
this.buffer = new Uint8Array(size);
@ -68,7 +68,7 @@ class RandomBuffer {
/**
* Take numbers out of buffer and copy to array
* @param {Uint8Array} buf the destination array
* @param {Uint8Array} buf - The destination array
*/
async get(buf) {
if (!this.buffer) {
@ -95,8 +95,8 @@ class RandomBuffer {
/**
* Retrieve secure random byte array of the specified length
* @param {Integer} length Length in bytes to generate
* @returns {Uint8Array} Random byte array
* @param {Integer} length - Length in bytes to generate
* @returns {Uint8Array} Random byte array.
* @async
*/
export async function getRandomBytes(length) {
@ -118,9 +118,9 @@ export async function getRandomBytes(length) {
/**
* Create a secure random BigInteger that is greater than or equal to min and less than max.
* @param {module:BigInteger} min Lower bound, included
* @param {module:BigInteger} max Upper bound, excluded
* @returns {module:BigInteger} Random BigInteger
* @param {module:BigInteger} min - Lower bound, included
* @param {module:BigInteger} max - Upper bound, excluded
* @returns {module:BigInteger} Random BigInteger.
* @async
*/
export async function getRandomBigInteger(min, max) {

34
src/crypto/signature.js
View File

@ -14,9 +14,9 @@ import util from '../util';
* depends on the key params, hence we delegate the padding to the signature verification function.
* See {@link https://tools.ietf.org/html/rfc4880#section-9.1|RFC 4880 9.1}
* See {@link https://tools.ietf.org/html/rfc4880#section-5.2.2|RFC 4880 5.2.2.}
* @param {module:enums.publicKey} algo Public key algorithm
* @param {Uint8Array} signature Data for which the signature was created
* @returns {Object} True if signature is valid
* @param {module:enums.publicKey} algo - Public key algorithm
* @param {Uint8Array} signature - Data for which the signature was created
* @returns {Object} True if signature is valid.
* @async
*/
export function parseSignatureParams(algo, signature) {
@ -64,13 +64,13 @@ export function parseSignatureParams(algo, signature) {
* See {@link https://tools.ietf.org/html/rfc4880#section-9.1|RFC 4880 9.1}
* and {@link https://tools.ietf.org/html/rfc4880#section-9.4|RFC 4880 9.4}
* for public key and hash algorithms.
* @param {module:enums.publicKey} algo Public key algorithm
* @param {module:enums.hash} hashAlgo Hash algorithm
* @param {Object} signature Named algorithm-specific signature parameters
* @param {Object} publicParams Algorithm-specific public key parameters
* @param {Uint8Array} data Data for which the signature was created
* @param {Uint8Array} hashed The hashed data
* @returns {Boolean} True if signature is valid
* @param {module:enums.publicKey} algo - Public key algorithm
* @param {module:enums.hash} hashAlgo - Hash algorithm
* @param {Object} signature - Named algorithm-specific signature parameters
* @param {Object} publicParams - Algorithm-specific public key parameters
* @param {Uint8Array} data - Data for which the signature was created
* @param {Uint8Array} hashed - The hashed data
* @returns {Boolean} True if signature is valid.
* @async
*/
export async function verify(algo, hashAlgo, signature, publicParams, data, hashed) {
@ -110,13 +110,13 @@ export async function verify(algo, hashAlgo, signature, publicParams, data, hash
* See {@link https://tools.ietf.org/html/rfc4880#section-9.1|RFC 4880 9.1}
* and {@link https://tools.ietf.org/html/rfc4880#section-9.4|RFC 4880 9.4}
* for public key and hash algorithms.
* @param {module:enums.publicKey} algo Public key algorithm
* @param {module:enums.hash} hashAlgo Hash algorithm
* @param {Object} publicKeyParams Algorithm-specific public and private key parameters
* @param {Object} privateKeyParams Algorithm-specific public and private key parameters
* @param {Uint8Array} data Data to be signed
* @param {Uint8Array} hashed The hashed data
* @returns {Object} Signature Object containing named signature parameters
* @param {module:enums.publicKey} algo - Public key algorithm
* @param {module:enums.hash} hashAlgo - Hash algorithm
* @param {Object} publicKeyParams - Algorithm-specific public and private key parameters
* @param {Object} privateKeyParams - Algorithm-specific public and private key parameters
* @param {Uint8Array} data - Data to be signed
* @param {Uint8Array} hashed - The hashed data
* @returns {Object} Signature Object containing named signature parameters.
* @async
*/
export async function sign(algo, hashAlgo, publicKeyParams, privateKeyParams, data, hashed) {

30
src/encoding/armor.js
View File

@ -24,7 +24,7 @@ import defaultConfig from '../config';
/**
* Finds out which Ascii Armoring type is used. Throws error if unknown type.
* @param {String} text - ascii armored text
* @returns {Integer} 0 = MESSAGE PART n of m
* @returns {Integer} 0 = MESSAGE PART n of m.
* 1 = MESSAGE PART n
* 2 = SIGNED MESSAGE
* 3 = PGP MESSAGE
@ -88,8 +88,8 @@ function getType(text) {
* packet block.
* @author Alex
* @version 2011-12-16
* @param {String} [customComment] - additional comment to add to the armored string
* @returns {String} The header information
* @param {String} [customComment] - Additional comment to add to the armored string
* @returns {String} The header information.
* @private
*/
function addheader(customComment, config) {
@ -110,8 +110,8 @@ function addheader(customComment, config) {
/**
* Calculates a checksum over the given data and returns it base64 encoded
* @param {String | ReadableStream<String>} data Data to create a CRC-24 checksum for
* @returns {String | ReadableStream<String>} Base64 encoded checksum
* @param {String | ReadableStream<String>} data - Data to create a CRC-24 checksum for
* @returns {String | ReadableStream<String>} Base64 encoded checksum.
* @private
*/
function getCheckSum(data) {
@ -158,8 +158,8 @@ const isLittleEndian = (function() {
/**
* Internal function to calculate a CRC-24 checksum over a given string (data)
* @param {String | ReadableStream<String>} input Data to create a CRC-24 checksum for
* @returns {Uint8Array | ReadableStream<Uint8Array>} The CRC-24 checksum
* @param {String | ReadableStream<String>} input - Data to create a CRC-24 checksum for
* @returns {Uint8Array | ReadableStream<Uint8Array>} The CRC-24 checksum.
* @private
*/
function createcrc24(input) {
@ -185,7 +185,7 @@ function createcrc24(input) {
* Verify armored headers. RFC4880, section 6.3: "OpenPGP should consider improperly formatted
* Armor Headers to be corruption of the ASCII Armor."
* @private
* @param {Array<String>} headers Armor headers
* @param {Array<String>} headers - Armor headers
*/
function verifyHeaders(headers) {
for (let i = 0; i < headers.length; i++) {
@ -200,8 +200,8 @@ function verifyHeaders(headers) {
/**
* Splits a message into two parts, the body and the checksum. This is an internal function
* @param {String} text OpenPGP armored message part
* @returns {Object} An object with attribute "body" containing the body
* @param {String} text - OpenPGP armored message part
* @returns {Object} An object with attribute "body" containing the body.
* and an attribute "checksum" containing the checksum.
* @private
*/
@ -222,7 +222,7 @@ function splitChecksum(text) {
/**
* Dearmor an OpenPGP armored message; verify the checksum and return
* the encoded bytes
* @param {String} input OpenPGP armored message
* @param {String} input - OpenPGP armored message
* @returns {Promise<Object>} An object with attribute "text" containing the message text,
* an attribute "data" containing a stream of bytes and "type" for the ASCII armor type
* @async
@ -346,12 +346,12 @@ export function unarmor(input, config = defaultConfig) {
/**
* Armor an OpenPGP binary packet block
* @param {module:enums.armor} messageType type of the message
* @param {Uint8Array | ReadableStream<Uint8Array>} body the message body to armor
* @param {module:enums.armor} messageType - Type of the message
* @param {Uint8Array | ReadableStream<Uint8Array>} body - The message body to armor
* @param {Integer} [partIndex]
* @param {Integer} [partTotal]
* @param {String} [customComment] - additional comment to add to the armored string
* @returns {String | ReadableStream<String>} Armored text
* @param {String} [customComment] - Additional comment to add to the armored string
* @returns {String | ReadableStream<String>} Armored text.
* @static
*/
export function armor(messageType, body, partIndex, partTotal, customComment, config = defaultConfig) {

18
src/encoding/base64.js
View File

@ -36,8 +36,8 @@ if (Buffer) {
/**
* Convert binary array to radix-64
* @param {Uint8Array | ReadableStream<Uint8Array>} data Uint8Array to convert
* @returns {String | ReadableStream<String>} radix-64 version of input string
* @param {Uint8Array | ReadableStream<Uint8Array>} data - Uint8Array to convert
* @returns {String | ReadableStream<String>} Radix-64 version of input string.
* @static
*/
export function encode(data) {
@ -60,8 +60,8 @@ export function encode(data) {
/**
* Convert radix-64 to binary array
* @param {String | ReadableStream<String>} data radix-64 string to convert
* @returns {Uint8Array | ReadableStream<Uint8Array>} binary array version of input string
* @param {String | ReadableStream<String>} data - Radix-64 string to convert
* @returns {Uint8Array | ReadableStream<Uint8Array>} Binary array version of input string.
* @static
*/
export function decode(data) {
@ -96,8 +96,8 @@ export function decode(data) {
* Convert a Base-64 encoded string an array of 8-bit integer
*
* Note: accepts both Radix-64 and URL-safe strings
* @param {String} base64 Base-64 encoded string to convert
* @returns {Uint8Array} An array of 8-bit integers
* @param {String} base64 - Base-64 encoded string to convert
* @returns {Uint8Array} An array of 8-bit integers.
*/
export function b64ToUint8Array(base64) {
return decode(base64.replace(/-/g, '+').replace(/_/g, '/'));
@ -105,9 +105,9 @@ export function b64ToUint8Array(base64) {
/**
* 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
* @returns {String} Base-64 encoded string
* @param {Uint8Array} bytes - An array of 8-bit integers to convert
* @param {bool} url - If true, output is URL-safe
* @returns {String} Base-64 encoded string.
*/
export function uint8ArrayToB64(bytes, url) {
let encoded = encode(bytes).replace(/[\r\n]/g, '');

8
src/hkp.js
View File

@ -24,10 +24,10 @@ import defaultConfig from './config';
class HKP {
/**
* Initialize the HKP client and configure it with the key server url and fetch function.
* @param {String} keyServerBaseUrl (optional) The HKP key server base url including
* @param {String} [keyServerBaseUrl] - The HKP key server base url including
* the protocol to use, e.g. 'https://pgp.mit.edu'; defaults to
* openpgp.config.keyserver (https://keyserver.ubuntu.com)
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(keyServerBaseUrl, config = defaultConfig) {
this._baseUrl = keyServerBaseUrl || config.keyserver;
@ -39,7 +39,7 @@ class HKP {
* @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.
* @returns {Promise<String>} The ascii armored public key.
* @returns {Promise<String>} The ascii armored public key.
* @async
*/
lookup(options) {
@ -68,7 +68,7 @@ class HKP {
/**
* Upload a public key to the server.
* @param {String} publicKeyArmored An ascii armored public key to be uploaded.
* @param {String} publicKeyArmored - An ascii armored public key to be uploaded.
* @returns {Promise}
* @async
*/

20
src/key/factory.js
View File

@ -33,7 +33,7 @@ import { unarmor } from '../encoding/armor';
* @param {String} options.passphrase Passphrase used to encrypt the resulting private key
* @param {Number} options.keyExpirationTime (optional) Number of seconds from the key creation time after which the key expires
* @param {Date} options.date Creation date of the key and the key signatures
* @param {Object} config Full configuration
* @param {Object} config - Full configuration
* @param {Array<Object>} options.subkeys (optional) options for each subkey, default to main key options. e.g. [{sign: true, passphrase: '123'}]
* sign parameter defaults to false, and indicates whether the subkey should sign rather than encrypt
* @returns {Promise<Key>}
@ -58,7 +58,7 @@ export async function generate(options, config) {
* @param {Number} options.keyExpirationTime Number of seconds from the key creation time after which the key expires
* @param {Date} options.date Override the creation date of the key and the key signatures
* @param {Array<Object>} options.subkeys (optional) options for each subkey, default to main key options. e.g. [{sign: true, passphrase: '123'}]
* @param {Object} config Full configuration
* @param {Object} config - Full configuration
*
* @returns {Promise<Key>}
* @async
@ -245,10 +245,10 @@ async function wrapKeyObject(secretKeyPacket, secretSubkeyPackets, options, conf
/**
* Reads an (optionally armored) OpenPGP key and returns a key object
* @param {Object} options
* @param {String | ReadableStream<String>} [options.armoredKey] - armored key to be parsed
* @param {Uint8Array | ReadableStream<Uint8Array>} [options.binaryKey] - binary key to be parsed
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Key>} key object
* @param {String | ReadableStream<String>} [options.armoredKey] - Armored key to be parsed
* @param {Uint8Array | ReadableStream<Uint8Array>} [options.binaryKey] - Binary key to be parsed
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Key>} Key object.
* @async
* @static
*/
@ -275,10 +275,10 @@ export async function readKey({ armoredKey, binaryKey, config }) {
/**
* Reads an (optionally armored) OpenPGP key block and returns a list of key objects
* @param {Object} options
* @param {String | ReadableStream<String>} [options.armoredKeys] - armored keys to be parsed
* @param {Uint8Array | ReadableStream<Uint8Array>} [options.binaryKeys] - binary keys to be parsed
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Array<Key>>} key objects
* @param {String | ReadableStream<String>} [options.armoredKeys] - Armored keys to be parsed
* @param {Uint8Array | ReadableStream<Uint8Array>} [options.binaryKeys] - Binary keys to be parsed
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Array<Key>>} Key objects.
* @async
* @static
*/

80
src/key/helper.js
View File

@ -46,10 +46,10 @@ export async function generateSecretKey(options, config) {
/**
* Returns the valid and non-expired signature that has the latest creation date, while ignoring signatures created in the future.
* @param {Array<SignaturePacket>} signatures List of signatures
* @param {Date} date Use the given date instead of the current time
* @param {Object} config full configuration
* @returns {Promise<SignaturePacket>} The latest valid signature
* @param {Array<SignaturePacket>} signatures - List of signatures
* @param {Date} date - Use the given date instead of the current time
* @param {Object} config - full configuration
* @returns {Promise<SignaturePacket>} The latest valid signature.
* @async
*/
export async function getLatestValidSignature(signatures, primaryKey, signatureType, dataToVerify, date = new Date(), config) {
@ -92,10 +92,10 @@ export function isDataExpired(keyPacket, signature, date = new Date()) {
/**
* Create Binding signature to the key according to the {@link https://tools.ietf.org/html/rfc4880#section-5.2.1}
* @param {SecretSubkeyPacket} subkey Subkey key packet
* @param {SecretKeyPacket} primaryKey Primary key packet
* @param {SecretSubkeyPacket} subkey - Subkey key packet
* @param {SecretKeyPacket} primaryKey - Primary key packet
* @param {Object} options
* @param {Object} config full configuration
* @param {Object} config - Full configuration
*/
export async function createBindingSignature(subkey, primaryKey, options, config) {
const dataToSign = {};
@ -123,11 +123,11 @@ export async function createBindingSignature(subkey, primaryKey, options, config
/**
* Returns the preferred signature hash algorithm of a key
* @param {Key} key (optional) the key to get preferences from
* @param {SecretKeyPacket|SecretSubkeyPacket} keyPacket key packet used for signing
* @param {Date} date (optional) use the given date for verification instead of the current time
* @param {Object} userId (optional) user ID
* @param {Object} config full configuration
* @param {Key} [key] - The key to get preferences from
* @param {SecretKeyPacket|SecretSubkeyPacket} keyPacket - key packet used for signing
* @param {Date} [date] - Use the given date for verification instead of the current time
* @param {Object} [userId] - User ID
* @param {Object} config - full configuration
* @returns {Promise<String>}
* @async
*/
@ -160,12 +160,12 @@ export async function getPreferredHashAlgo(key, keyPacket, date = new Date(), us
/**
* Returns the preferred symmetric/aead algorithm for a set of keys
* @param {symmetric|aead} type Type of preference to return
* @param {Array<Key>} keys Set of keys
* @param {Date} date (optional) use the given date for verification instead of the current time
* @param {Array} userIds (optional) user IDs
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<module:enums.symmetric>} Preferred symmetric algorithm
* @param {symmetric|aead} type - Type of preference to return
* @param {Array<Key>} keys - Set of keys
* @param {Date} [date] - Use the given date for verification instead of the current time
* @param {Array} [userIds] - User IDs
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<module:enums.symmetric>} Preferred symmetric algorithm.
* @async
*/
export async function getPreferredAlgo(type, keys, date = new Date(), userIds = [], config = defaultConfig) {
@ -200,16 +200,16 @@ export async function getPreferredAlgo(type, keys, date = new Date(), userIds =
/**
* Create signature packet
* @param {Object} dataToSign Contains packets to be signed
* @param {Object} dataToSign - Contains packets to be signed
* @param {SecretKeyPacket|
* SecretSubkeyPacket} signingKeyPacket secret key packet for signing
* @param {Object} [signatureProperties] - properties to write on the signature packet before signing
* @param {Date} [date] - override the creationtime of the signature
* @param {Object} [userId] - user ID
* @param {Object} [detached] - whether to create a detached signature packet
* @param {Boolean} [streaming] - whether to process data as a stream
* @param {Object} config full configuration
* @returns {Promise<SignaturePacket>} signature packet
* @param {Object} [signatureProperties] - Properties to write on the signature packet before signing
* @param {Date} [date] - Override the creationtime of the signature
* @param {Object} [userId] - User ID
* @param {Object} [detached] - Whether to create a detached signature packet
* @param {Boolean} [streaming] - Whether to process data as a stream
* @param {Object} config - full configuration
* @returns {Promise<SignaturePacket>} Signature packet.
*/
export async function createSignaturePacket(dataToSign, privateKey, signingKeyPacket, signatureProperties, date, userId, detached = false, streaming = false, config) {
if (signingKeyPacket.isDummy()) {
@ -228,10 +228,10 @@ export async function createSignaturePacket(dataToSign, privateKey, signingKeyPa
/**
* Merges signatures from source[attr] to dest[attr]
* @param {Object} source
* @param {Object} dest
* @param {String} attr
* @param {Function} checkFn optional, signature only merged if true
* @param {Object} source
* @param {Object} dest
* @param {String} attr
* @param {Function} checkFn - optional, signature only merged if true
*/
export async function mergeSignatures(source, dest, attr, checkFn) {
source = source[attr];
@ -255,16 +255,16 @@ export async function mergeSignatures(source, dest, attr, checkFn) {
* Checks if a given certificate or binding signature is revoked
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {Object} dataToVerify The data to check
* @param {Array<SignaturePacket>} revocations The revocation signatures to check
* @param {SignaturePacket} signature The certificate or signature to check
* @param {Object} dataToVerify - The data to check
* @param {Array<SignaturePacket>} revocations - The revocation signatures to check
* @param {SignaturePacket} signature - The certificate or signature to check
* @param {PublicSubkeyPacket|
* SecretSubkeyPacket|
* PublicKeyPacket|
* SecretKeyPacket} key, optional The key packet to check the signature
* @param {Date} date Use the given date instead of the current time
* @param {Object} config full configuration
* @returns {Promise<Boolean>} True if the signature revokes the data
* @param {Date} date - Use the given date instead of the current time
* @param {Object} config - Full configuration
* @returns {Promise<Boolean>} True if the signature revokes the data.
* @async
*/
export async function isDataRevoked(primaryKey, signatureType, dataToVerify, revocations, signature, key, date = new Date(), config) {
@ -312,10 +312,10 @@ export function getExpirationTime(keyPacket, signature) {
/**
* Returns whether aead is supported by all keys in the set
* @param {Array<Key>} keys Set of keys
* @param {Date} date (optional) use the given date for verification instead of the current time
* @param {Array} userIds (optional) user IDs
* @param {Object} config full configuration
* @param {Array<Key>} keys - Set of keys
* @param {Date} [date] - Use the given date for verification instead of the current time
* @param {Array} [userIds] - User IDs
* @param {Object} config - full configuration
* @returns {Promise<Boolean>}
* @async
*/

124
src/key/key.js
View File

@ -40,7 +40,7 @@ import * as helper from './helper';
*/
class Key {
/**
* @param {PacketList} packetlist The packets that form this key
* @param {PacketList} packetlist - The packets that form this key
*/
constructor(packetlist) {
if (!(this instanceof Key)) {
@ -64,7 +64,7 @@ class Key {
/**
* Transforms packetlist to structured key data
* @param {PacketList} packetlist The packets that form a key
* @param {PacketList} packetlist - The packets that form a key
*/
packetlist2structure(packetlist) {
let user;
@ -142,7 +142,7 @@ class Key {
/**
* Transforms structured key data to packetlist
* @returns {PacketList} The packets that form a key
* @returns {PacketList} The packets that form a key.
*/
toPacketlist() {
const packetlist = new PacketList();
@ -156,7 +156,7 @@ class Key {
/**
* Clones the key object
* @returns {Promise<Key>} shallow clone of the key
* @returns {Promise<Key>} Shallow clone of the key.
* @async
*/
async clone() {
@ -166,7 +166,7 @@ class Key {
/**
* Returns an array containing all public or private subkeys matching keyId;
* If keyId is not present, returns all subkeys.
* @param {type/keyid} keyId
* @param {type/keyid} keyId
* @returns {Array<SubKey>}
*/
getSubkeys(keyId = null) {
@ -182,7 +182,7 @@ class Key {
/**
* Returns an array containing all public or private keys matching keyId.
* If keyId is not present, returns all keys starting with the primary key.
* @param {type/keyid} keyId
* @param {type/keyid} keyId
* @returns {Array<Key|SubKey>}
*/
getKeys(keyId = null) {
@ -203,7 +203,7 @@ class Key {
/**
* Returns userids
* @returns {Array<string>} array of userids
* @returns {Array<string>} Array of userids.
*/
getUserIds() {
return this.users.map(user => {
@ -229,8 +229,8 @@ class Key {
/**
* Returns key as public key (shallow copy)
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Key} new public Key
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Key} New public Key.
*/
toPublic() {
const packetlist = new PacketList();
@ -261,8 +261,8 @@ class Key {
/**
* Returns ASCII armored text of key
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {ReadableStream<String>} ASCII armor
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {ReadableStream<String>} ASCII armor.
*/
armor(config = defaultConfig) {
const type = this.isPublic() ? enums.armor.publicKey : enums.armor.privateKey;
@ -272,10 +272,10 @@ class Key {
/**
* Returns last created key or key by given keyId that is available for signing and verification
* @param {module:type/keyid~Keyid} keyId, optional
* @param {Date} date (optional) use the given date for verification instead of the current time
* @param {Date} [date] - Use the given date for verification instead of the current time
* @param {Object} userId, optional user ID
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Key|SubKey|null>} key or null if no signing key has been found
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Key|SubKey|null>} Key or null if no signing key has been found.
* @async
*/
async getSigningKey(keyId = null, date = new Date(), userId = {}, config = defaultConfig) {
@ -315,8 +315,8 @@ class Key {
* @param {module:type/keyid~Keyid} keyId, optional
* @param {Date} date, optional
* @param {String} userId, optional
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Key|SubKey|null>} key or null if no encryption key has been found
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Key|SubKey|null>} Key or null if no encryption key has been found.
* @async
*/
async getEncryptionKey(keyId, date = new Date(), userId = {}, config = defaultConfig) {
@ -354,8 +354,8 @@ class Key {
* @param {module:type/keyid~Keyid} keyId, optional
* @param {Date} date, optional
* @param {String} userId, optional
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Array<Key|SubKey>>} array of decryption keys
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<Key|SubKey>>} Array of decryption keys.
* @async
*/
async getDecryptionKeys(keyId, date = new Date(), userId = {}, config = defaultConfig) {
@ -385,9 +385,9 @@ class Key {
/**
* Encrypts all secret key and subkey packets matching keyId
* @param {String|Array<String>} passphrases - if multiple passphrases, then should be in same order as packets each should encrypt
* @param {module:type/keyid~Keyid} keyId
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {String|Array<String>} passphrases - If multiple passphrases, then should be in same order as packets each should encrypt
* @param {module:type/keyid~Keyid} keyId
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if encryption failed for any key or subkey
* @async
*/
@ -411,9 +411,9 @@ class Key {
/**
* Decrypts all secret key and subkey packets matching keyId
* @param {String|Array<String>} passphrases
* @param {module:type/keyid~Keyid} keyId
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {String|Array<String>} passphrases
* @param {module:type/keyid~Keyid} keyId
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if any matching key or subkey packets did not decrypt successfully
* @async
*/
@ -461,7 +461,7 @@ class Key {
* In case of gnu-dummy primary key, it is enough to validate any signing subkeys
* otherwise all encryption subkeys are validated
* If only gnu-dummy keys are found, we cannot properly validate so we throw an error
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if validation was not successful and the key cannot be trusted
* @async
*/
@ -514,14 +514,14 @@ class Key {
/**
* Checks if a signature on a key is revoked
* @param {SignaturePacket} signature The signature to verify
* @param {SignaturePacket} signature - The signature to verify
* @param {PublicSubkeyPacket|
* SecretSubkeyPacket|
* PublicKeyPacket|
* SecretKeyPacket} key, optional The key to verify the signature
* @param {Date} date Use the given date instead of the current time
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Boolean>} True if the certificate is revoked
* @param {Date} date - Use the given date instead of the current time
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Boolean>} True if the certificate is revoked.
* @async
*/
async isRevoked(signature, key, date = new Date(), config = defaultConfig) {
@ -533,9 +533,9 @@ class Key {
/**
* Verify primary key. Checks for revocation signatures, expiration time
* and valid self signature. Throws if the primary key is invalid.
* @param {Date} date (optional) use the given date for verification instead of the current time
* @param {Object} userId (optional) user ID
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Date} [date] - Use the given date for verification instead of the current time
* @param {Object} [userId] - User ID
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} If key verification failed
* @async
*/
@ -561,7 +561,7 @@ class Key {
* @param {encrypt|sign|encrypt_sign} capabilities, optional
* @param {module:type/keyid~Keyid} keyId, optional
* @param {Object} userId, optional user ID
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Date | Infinity | null>}
* @async
*/
@ -594,9 +594,9 @@ class Key {
* Returns primary user and most significant (latest valid) self signature
* - 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 (optional) use the given date for verification instead of the current time
* @param {Object} userId (optional) user ID to get instead of the primary user, if it exists
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Date} [date] - Use the given date for verification instead of the current time
* @param {Object} [userId] - User ID to get instead of the primary user, if it exists
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<{user: User,
* selfCertification: SignaturePacket}>} The primary user and the self signature
* @async
@ -651,8 +651,8 @@ class Key {
*
* If the specified key is a private key and the destination key is public,
* the destination key is transformed to a private key.
* @param {Key} key Source key to merge
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Key} key - Source key to merge
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<undefined>}
* @async
*/
@ -713,12 +713,12 @@ class Key {
/**
* Revokes the key
* @param {Object} reasonForRevocation optional, object indicating the reason for revocation
* @param {Object} reasonForRevocation - optional, object indicating the reason for revocation
* @param {module:enums.reasonForRevocation} reasonForRevocation.flag optional, flag indicating the reason for revocation
* @param {String} reasonForRevocation.string optional, string explaining the reason for revocation
* @param {Date} date optional, override the creationtime of the revocation signature
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Key>} new key with revocation signature
* @param {Date} date - optional, override the creationtime of the revocation signature
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Key>} New key with revocation signature.
* @async
*/
async revoke(
@ -745,9 +745,9 @@ class Key {
/**
* Get revocation certificate from a revoked key.
* (To get a revocation certificate for an unrevoked key, call revoke() first.)
* @param {Date} date Use the given date instead of the current time
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<String>} armored revocation certificate
* @param {Date} date - Use the given date instead of the current time
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<String>} Armored revocation certificate.
* @async
*/
async getRevocationCertificate(date = new Date(), config = defaultConfig) {
@ -762,9 +762,9 @@ class Key {
* Applies a revocation certificate to a key
* This adds the first signature packet in the armored text to the key,
* if it is a valid revocation signature.
* @param {String} revocationCertificate armored revocation certificate
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Key>} new revoked key
* @param {String} revocationCertificate - armored revocation certificate
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Key>} New revoked key.
* @async
*/
async applyRevocationCertificate(revocationCertificate, config = defaultConfig) {
@ -793,11 +793,11 @@ class Key {
/**
* Signs primary user of key
* @param {Array<Key>} privateKeys decrypted private keys for signing
* @param {Date} date (optional) use the given date for verification instead of the current time
* @param {Object} userId (optional) user ID to get instead of the primary user, if it exists
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Key>} new public key with new certificate signature
* @param {Array<Key>} privateKeys - decrypted private keys for signing
* @param {Date} [date] - Use the given date for verification instead of the current time
* @param {Object} [userId] - User ID to get instead of the primary user, if it exists
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Key>} New public key with new certificate signature.
* @async
*/
async signPrimaryUser(privateKeys, date, userId, config = defaultConfig) {
@ -810,9 +810,9 @@ class Key {
/**
* Signs all users of key
* @param {Array<Key>} privateKeys decrypted private keys for signing
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Key>} new public key with new certificate signature
* @param {Array<Key>} privateKeys - decrypted private keys for signing
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Key>} New public key with new certificate signature.
* @async
*/
async signAllUsers(privateKeys, config = defaultConfig) {
@ -828,10 +828,10 @@ class Key {
* Verifies primary user of key
* - if no arguments are given, verifies the self certificates;
* - otherwise, verifies all certificates signed with given keys.
* @param {Array<Key>} keys array of keys to verify certificate signatures
* @param {Date} date (optional) use the given date for verification instead of the current time
* @param {Object} userId (optional) user ID to get instead of the primary user, if it exists
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Array<Key>} keys - array of keys to verify certificate signatures
* @param {Date} [date] - Use the given date for verification instead of the current time
* @param {Object} [userId] - User ID to get instead of the primary user, if it exists
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<{keyid: module:type/keyid~Keyid,
* valid: Boolean}>>} List of signer's keyid and validity of signature
* @async
@ -848,8 +848,8 @@ class Key {
* Verifies all users of key
* - if no arguments are given, verifies the self certificates;
* - otherwise, verifies all certificates signed with given keys.
* @param {Array<Key>} keys array of keys to verify certificate signatures
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Array<Key>} keys - array of keys to verify certificate signatures
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<{userid: String,
* keyid: module:type/keyid~Keyid,
* valid: Boolean}>>} list of userid, signer's keyid and validity of signature

30
src/key/subkey.js
View File

@ -43,14 +43,14 @@ class SubKey {
* Checks if a binding signature of a subkey is revoked
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {SignaturePacket} signature The binding signature to verify
* @param {SignaturePacket} signature - The binding signature to verify
* @param {PublicSubkeyPacket|
* SecretSubkeyPacket|
* PublicKeyPacket|
* SecretKeyPacket} key, optional The key to verify the signature
* @param {Date} date Use the given date instead of the current time
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Boolean>} True if the binding signature is revoked
* @param {Date} date - Use the given date instead of the current time
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Boolean>} True if the binding signature is revoked.
* @async
*/
async isRevoked(primaryKey, signature, key, date = new Date(), config = defaultConfig) {
@ -67,8 +67,8 @@ class SubKey {
* and valid binding signature.
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {Date} date Use the given date instead of the current time
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Date} date - Use the given date instead of the current time
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<SignaturePacket>}
* @throws {Error} if the subkey is invalid.
* @async
@ -93,8 +93,8 @@ class SubKey {
* Returns null if the subkey is invalid.
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {Date} date Use the given date instead of the current time
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Date} date - Use the given date instead of the current time
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Date | Infinity | null>}
* @async
*/
@ -113,10 +113,10 @@ class SubKey {
/**
* Update subkey with new components from specified subkey
* @param {SubKey} subKey Source subkey to merge
* @param {SubKey} subKey - Source subkey to merge
* @param {SecretKeyPacket|
SecretSubkeyPacket} primaryKey primary key used for validation
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if update failed
* @async
*/
@ -156,13 +156,13 @@ class SubKey {
/**
* Revokes the subkey
* @param {SecretKeyPacket} primaryKey decrypted private primary key for revocation
* @param {Object} reasonForRevocation optional, object indicating the reason for revocation
* @param {SecretKeyPacket} primaryKey - decrypted private primary key for revocation
* @param {Object} reasonForRevocation - optional, object indicating the reason for revocation
* @param {module:enums.reasonForRevocation} reasonForRevocation.flag optional, flag indicating the reason for revocation
* @param {String} reasonForRevocation.string optional, string explaining the reason for revocation
* @param {Date} date optional, override the creationtime of the revocation signature
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<SubKey>} new subkey with revocation signature
* @param {Date} date - optional, override the creationtime of the revocation signature
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<SubKey>} New subkey with revocation signature.
* @async
*/
async revoke(

40
src/key/user.js
View File

@ -40,9 +40,9 @@ class User {
* Signs user
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {Array<Key>} privateKeys Decrypted private keys for signing
* @param {Object} config Full configuration
* @returns {Promise<Key>} New user with new certificate signatures
* @param {Array<Key>} privateKeys - Decrypted private keys for signing
* @param {Object} config - Full configuration
* @returns {Promise<Key>} New user with new certificate signatures.
* @async
*/
async sign(primaryKey, privateKeys, config) {
@ -74,14 +74,14 @@ class User {
* Checks if a given certificate of the user is revoked
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {SignaturePacket} certificate The certificate to verify
* @param {SignaturePacket} certificate - The certificate to verify
* @param {PublicSubkeyPacket|
* SecretSubkeyPacket|
* PublicKeyPacket|
* SecretKeyPacket} key, optional The key to verify the signature
* @param {Date} date Use the given date instead of the current time
* @param {Object} config Full configuration
* @returns {Promise<Boolean>} True if the certificate is revoked
* @param {Date} date - Use the given date instead of the current time
* @param {Object} config - Full configuration
* @returns {Promise<Boolean>} True if the certificate is revoked.
* @async
*/
async isRevoked(primaryKey, certificate, key, date = new Date(), config) {
@ -98,11 +98,11 @@ class User {
* Verifies the user certificate. Throws if the user certificate is invalid.
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {SignaturePacket} certificate A certificate of this user
* @param {Array<Key>} keys Array of keys to verify certificate signatures
* @param {Date} date Use the given date instead of the current time
* @param {Object} config Full configuration
* @returns {Promise<true|null>} status of the certificate
* @param {SignaturePacket} certificate - A certificate of this user
* @param {Array<Key>} keys - Array of keys to verify certificate signatures
* @param {Date} date - Use the given date instead of the current time
* @param {Object} config - Full configuration
* @returns {Promise<true|null>} Status of the certificate.
* @async
*/
async verifyCertificate(primaryKey, certificate, keys, date = new Date(), config) {
@ -138,9 +138,9 @@ class User {
* Verifies all user certificates
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {Array<Key>} keys Array of keys to verify certificate signatures
* @param {Date} date Use the given date instead of the current time
* @param {Object} config Full configuration
* @param {Array<Key>} keys - Array of keys to verify certificate signatures
* @param {Date} date - Use the given date instead of the current time
* @param {Object} config - Full configuration
* @returns {Promise<Array<{keyid: module:type/keyid~Keyid,
* valid: Boolean}>>} List of signer's keyid and validity of signature
* @async
@ -161,9 +161,9 @@ class User {
* and validity of self signature.
* @param {SecretKeyPacket|
* PublicKeyPacket} primaryKey The primary key packet
* @param {Date} date Use the given date instead of the current time
* @param {Object} config Full configuration
* @returns {Promise<true>} Status of user
* @param {Date} date - Use the given date instead of the current time
* @param {Object} config - Full configuration
* @returns {Promise<true>} Status of user.
* @throws {Error} if there are no valid self signatures.
* @async
*/
@ -203,10 +203,10 @@ class User {
/**
* Update user with new components from specified user
* @param {User} user Source user to merge
* @param {User} user - Source user to merge
* @param {SecretKeyPacket|
* SecretSubkeyPacket} primaryKey primary key used for validation
* @param {Object} config Full configuration
* @param {Object} config - Full configuration
* @returns {Promise<undefined>}
* @async
*/

48
src/keyring/keyring.js
View File

@ -24,7 +24,7 @@ import LocalStore from './localstore';
*/
class KeyArray {
/**
* @param {Array<Key>} keys The keys to store in this array
* @param {Array<Key>} keys - The keys to store in this array
*/
constructor(keys) {
this.keys = keys;
@ -32,7 +32,7 @@ class KeyArray {
/**
* Searches all keys in the KeyArray matching the address or address part of the user ids
* @param {String} email email address to search for
* @param {String} email - Email address to search for
* @returns {Array<Key>} The public keys associated with provided email address.
*/
getForAddress(email) {
@ -47,10 +47,10 @@ class KeyArray {
/**
* Searches the KeyArray for a key having the specified key id
* @param {String} keyId provided as string of lowercase hex number
* @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
* @returns {Key|null} key found or null
* @param {Boolean} deep - if true search also in subkeys
* @returns {Key|null} Key found or null.
*/
getForId(keyId, deep) {
for (let i = 0; i < this.keys.length; i++) {
@ -70,8 +70,8 @@ class KeyArray {
/**
* Imports a key from an ascii armored message
* @param {String} armored message to read the keys/key from
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {String} armored - Message to read the keys/key from
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @async
*/
async importKey(armored, config = defaultConfig) {
@ -91,8 +91,8 @@ class KeyArray {
/**
* Add key to KeyArray
* @param {Key} key The key that will be added to the keyring
* @returns {Number} The new length of the KeyArray
* @param {Key} key - The key that will be added to the keyring
* @returns {Number} The new length of the KeyArray.
*/
push(key) {
return this.keys.push(key);
@ -100,9 +100,9 @@ class KeyArray {
/**
* Removes a key with the specified keyid from the keyring
* @param {String} keyId provided as string of lowercase hex number
* @param {String} keyId - Provided as string of lowercase hex number
* withouth 0x prefix (can be 16-character key ID or fingerprint)
* @returns {Key|null} The key object which has been removed or null
* @returns {Key|null} The key object which has been removed or null.
*/
removeForId(keyId) {
for (let i = 0; i < this.keys.length; i++) {
@ -118,7 +118,7 @@ class Keyring {
/**
* Initialization routine for the keyring.
* @param {keyring/localstore} [storeHandler] class implementing loadPublic(), loadPrivate(), storePublic(), and storePrivate() methods
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(storeHandler, config = defaultConfig) {
this.storeHandler = storeHandler || new LocalStore(undefined, config);
@ -154,10 +154,10 @@ class Keyring {
/**
* Searches the keyring for keys having the specified key id
* @param {String} keyId provided as string of lowercase hex number
* @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
* @returns {Array<Key>|null} keys found or null
* @param {Boolean} deep - if true search also in subkeys
* @returns {Array<Key>|null} Keys found or null.
*/
getKeysForId(keyId, deep) {
let result = [];
@ -168,9 +168,9 @@ class Keyring {
/**
* Removes keys having the specified key id from the keyring
* @param {String} keyId provided as string of lowercase hex number
* @param {String} keyId - Provided as string of lowercase hex number
* withouth 0x prefix (can be 16-character key ID or fingerprint)
* @returns {Array<Key>|null} keys found or null
* @returns {Array<Key>|null} Keys found or null.
*/
removeKeysForId(keyId) {
let result = [];
@ -181,7 +181,7 @@ class Keyring {
/**
* Get all public and private keys
* @returns {Array<Key>} all keys
* @returns {Array<Key>} All keys.
*/
getAllKeys() {
return this.publicKeys.keys.concat(this.privateKeys.keys);
@ -191,9 +191,9 @@ class Keyring {
/**
* Checks a key to see if it matches the specified email address
* @private
* @param {String} email email address to search for
* @param {Key} key The key to be checked.
* @returns {Boolean} True if the email address is defined in the specified key
* @param {String} email - Email address to search for
* @param {Key} key - The key to be checked.
* @returns {Boolean} True if the email address is defined in the specified key.
*/
function emailCheck(email, key) {
email = email.toLowerCase();
@ -213,10 +213,10 @@ function emailCheck(email, key) {
/**
* Checks a key to see if it matches the specified keyid
* @private
* @param {String} keyId provided as string of lowercase hex number
* @param {String} keyId - Provided as string of lowercase hex number
* withouth 0x prefix (can be 16-character key ID or fingerprint)
* @param {Key|SubKey} key The key to be checked
* @returns {Boolean} True if key has the specified keyid
* @param {Key|SubKey} key - The key to be checked
* @returns {Boolean} True if key has the specified keyid.
* @private
*/
function keyIdCheck(keyId, key) {

18
src/keyring/localstore.js
View File

@ -31,8 +31,8 @@ import defaultConfig from '../config';
*/
class LocalStore {
/**
* @param {String} prefix prefix for itemnames in localstore
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {String} prefix - Prefix for itemnames in localstore
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(prefix, config = defaultConfig) {
prefix = prefix || 'openpgp-';
@ -47,7 +47,7 @@ class LocalStore {
/**
* Load the public keys from HTML5 local storage.
* @returns {Array<Key>} array of keys retrieved from localstore
* @returns {Array<Key>} Array of keys retrieved from localstore.
* @async
*/
async loadPublic(config = defaultConfig) {
@ -56,8 +56,8 @@ class LocalStore {
/**
* Load the private keys from HTML5 local storage.
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Array<Key>} array of keys retrieved from localstore
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Array<Key>} Array of keys retrieved from localstore.
* @async
*/
async loadPrivate(config = defaultConfig) {
@ -67,8 +67,8 @@ class LocalStore {
/**
* Saves the current state of the public keys to HTML5 local storage.
* The key array gets stringified using JSON
* @param {Array<Key>} keys array of keys to save in localstore
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Array<Key>} keys - Array of keys to save in localstore
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @async
*/
async storePublic(keys, config = defaultConfig) {
@ -78,8 +78,8 @@ class LocalStore {
/**
* Saves the current state of the private keys to HTML5 local storage.
* The key array gets stringified using JSON
* @param {Array<Key>} keys array of keys to save in localstore
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Array<Key>} keys - Array of keys to save in localstore
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @async
*/
async storePrivate(keys, config = defaultConfig) {

218
src/message.js
View File

@ -45,7 +45,7 @@ import { getPreferredHashAlgo, getPreferredAlgo, isAeadSupported, createSignatur
*/
export class Message {
/**
* @param {PacketList} packetlist The packets that form this message
* @param {PacketList} packetlist - The packets that form this message
*/
constructor(packetlist) {
this.packets = packetlist || new PacketList();
@ -53,7 +53,7 @@ export class Message {
/**
* Returns the key IDs of the keys to which the session key is encrypted
* @returns {Array<module:type/keyid~Keyid>} array of keyid objects
* @returns {Array<module:type/keyid~Keyid>} Array of keyid objects.
*/
getEncryptionKeyIds() {
const keyIds = [];
@ -66,7 +66,7 @@ export class Message {
/**
* Returns the key IDs of the keys that signed the message
* @returns {Array<module:type/keyid~Keyid>} array of keyid objects
* @returns {Array<module:type/keyid~Keyid>} Array of keyid objects.
*/
getSigningKeyIds() {
const keyIds = [];
@ -88,12 +88,12 @@ export class Message {
/**
* Decrypt the message. Either a private key, a session key, or a password must be specified.
* @param {Array<Key>} [privateKeys] - private keys with decrypted secret data
* @param {Array<String>} [passwords] - passwords used to decrypt
* @param {Array<Object>} [sessionKeys] - session keys in the form: { data:Uint8Array, algorithm:String, [aeadAlgorithm:String] }
* @param {Boolean} [streaming] - whether to process data as a stream
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<Message>} new message with decrypted content
* @param {Array<Key>} [privateKeys] - Private keys with decrypted secret data
* @param {Array<String>} [passwords] - Passwords used to decrypt
* @param {Array<Object>} [sessionKeys] - Session keys in the form: { data:Uint8Array, algorithm:String, [aeadAlgorithm:String] }
* @param {Boolean} [streaming] - Whether to process data as a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Message>} New message with decrypted content.
* @async
*/
async decrypt(privateKeys, passwords, sessionKeys, streaming, config = defaultConfig) {
@ -140,9 +140,9 @@ export class Message {
/**
* Decrypt encrypted session keys either with private keys or passwords.
* @param {Array<Key>} [privateKeys] - private keys with decrypted secret data
* @param {Array<String>} [passwords] - passwords used to decrypt
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Array<Key>} [privateKeys] - Private keys with decrypted secret data
* @param {Array<String>} [passwords] - Passwords used to decrypt
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<{ data: Uint8Array,
algorithm: String }>>} array of object with potential sessionKey, algorithm pairs
* @async
@ -242,7 +242,7 @@ export class Message {
/**
* Get literal data that is the body of the message
* @returns {(Uint8Array|null)} literal body of the message as Uint8Array
* @returns {(Uint8Array|null)} Literal body of the message as Uint8Array.
*/
getLiteralData() {
const msg = this.unwrapCompressed();
@ -252,7 +252,7 @@ export class Message {
/**
* Get filename from literal data packet
* @returns {(String|null)} filename of literal data packet as string
* @returns {(String|null)} Filename of literal data packet as string.
*/
getFilename() {
const msg = this.unwrapCompressed();
@ -262,7 +262,7 @@ export class Message {
/**
* Get literal data as text
* @returns {(String|null)} literal body of the message interpreted as text
* @returns {(String|null)} Literal body of the message interpreted as text.
*/
getText() {
const msg = this.unwrapCompressed();
@ -275,11 +275,11 @@ export class Message {
/**
* Generate a new session key object, taking the algorithm preferences of the passed public keys into account, if any.
* @param {Array<Key>} [keys] - public key(s) to select algorithm preferences for
* @param {Date} [date] - date to select algorithm preferences at
* @param {Array<Object>} [userIds] - user IDs to select algorithm preferences for
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<{ data: Uint8Array, algorithm: String }>} object with session key data and algorithm
* @param {Array<Key>} [keys] - Public key(s) to select algorithm preferences for
* @param {Date} [date] - Date to select algorithm preferences at
* @param {Array<Object>} [userIds] - User IDs to select algorithm preferences for
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<{ data: Uint8Array, algorithm: String }>} Object with session key data and algorithm.
* @async
*/
static async generateSessionKey(keys = [], date = new Date(), userIds = [], config = defaultConfig) {
@ -293,16 +293,16 @@ export class Message {
/**
* Encrypt the message either with public keys, passwords, or both at once.
* @param {Array<Key>} [keys] - public key(s) for message encryption
* @param {Array<String>} [passwords] - password(s) for message encryption
* @param {Object} [sessionKey] - session key in the form: { data:Uint8Array, algorithm:String, [aeadAlgorithm:String] }
* @param {Boolean} [wildcard] - use a key ID of 0 instead of the public key IDs
* @param {Array<module:type/keyid~Keyid>} [encryptionKeyIds] - array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i]
* @param {Date} [date] - override the creation date of the literal package
* @param {Array<Object>} [userIds] - user IDs to encrypt for, e.g. [{ name:'Robert Receiver', email:'robert@openpgp.org' }]
* @param {Boolean} [streaming] - whether to process data as a stream
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<Message>} new message with encrypted content
* @param {Array<Key>} [keys] - Public key(s) for message encryption
* @param {Array<String>} [passwords] - Password(s) for message encryption
* @param {Object} [sessionKey] - Session key in the form: { data:Uint8Array, algorithm:String, [aeadAlgorithm:String] }
* @param {Boolean} [wildcard] - Use a key ID of 0 instead of the public key IDs
* @param {Array<module:type/keyid~Keyid>} [encryptionKeyIds] - Array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i]
* @param {Date} [date] - Override the creation date of the literal package
* @param {Array<Object>} [userIds] - User IDs to encrypt for, e.g. [{ name:'Robert Receiver', email:'robert@openpgp.org' }]
* @param {Boolean} [streaming] - Whether to process data as a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Message>} New message with encrypted content.
* @async
*/
async encrypt(keys, passwords, sessionKey, wildcard = false, encryptionKeyIds = [], date = new Date(), userIds = [], streaming, config = defaultConfig) {
@ -342,17 +342,17 @@ export class Message {
/**
* Encrypt a session key either with public keys, passwords, or both at once.
* @param {Uint8Array} sessionKey session key for encryption
* @param {String} algorithm session key algorithm
* @param {String} [aeadAlgorithm] - aead algorithm, e.g. 'eax' or 'ocb'
* @param {Array<Key>} [publicKeys] - public key(s) for message encryption
* @param {Array<String>} [passwords] - for message encryption
* @param {Boolean} [wildcard] - use a key ID of 0 instead of the public key IDs
* @param {Array<module:type/keyid~Keyid>} [encryptionKeyIds] - array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i]
* @param {Date} [date] - override the date
* @param {Array} [userIds] - user IDs to encrypt for, e.g. [{ name:'Robert Receiver', email:'robert@openpgp.org' }]
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<Message>} new message with encrypted content
* @param {Uint8Array} sessionKey - session key for encryption
* @param {String} algorithm - session key algorithm
* @param {String} [aeadAlgorithm] - Aead algorithm, e.g. 'eax' or 'ocb'
* @param {Array<Key>} [publicKeys] - Public key(s) for message encryption
* @param {Array<String>} [passwords] - For message encryption
* @param {Boolean} [wildcard] - Use a key ID of 0 instead of the public key IDs
* @param {Array<module:type/keyid~Keyid>} [encryptionKeyIds] - Array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i]
* @param {Date} [date] - Override the date
* @param {Array} [userIds] - User IDs to encrypt for, e.g. [{ name:'Robert Receiver', email:'robert@openpgp.org' }]
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Message>} New message with encrypted content.
* @async
*/
static async encryptSessionKey(sessionKey, algorithm, aeadAlgorithm, publicKeys, passwords, wildcard = false, encryptionKeyIds = [], date = new Date(), userIds = [], config = defaultConfig) {
@ -413,14 +413,14 @@ export class Message {
/**
* Sign the message (the literal data packet of the message)
* @param {Array<Key>} privateKeys private keys with decrypted secret key data for signing
* @param {Signature} [signature] - any existing detached signature to add to the message
* @param {Array<module:type/keyid~Keyid>} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - override the creation time of the signature
* @param {Array} [userIds] - user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Boolean} [streaming] - whether to process data as a stream
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<Message>} new message with signed content
* @param {Array<Key>} privateKeys - private keys with decrypted secret key data for signing
* @param {Signature} [signature] - Any existing detached signature to add to the message
* @param {Array<module:type/keyid~Keyid>} [signingKeyIds] - Array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - Override the creation time of the signature
* @param {Array} [userIds] - User IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Boolean} [streaming] - Whether to process data as a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Message>} New message with signed content.
* @async
*/
async sign(privateKeys = [], signature = null, signingKeyIds = [], date = new Date(), userIds = [], streaming = false, config = defaultConfig) {
@ -480,8 +480,8 @@ export class Message {
/**
* Compresses the message (the literal and -if signed- signature data packets of the message)
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Message} new message with compressed content
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Message} New message with compressed content.
*/
compress(config = defaultConfig) {
if (config.compression === enums.compression.uncompressed) {
@ -499,14 +499,14 @@ export class Message {
/**
* Create a detached signature for the message (the literal data packet of the message)
* @param {Array<Key>} privateKeys private keys with decrypted secret key data for signing
* @param {Signature} [signature] - any existing detached signature
* @param {Array<module:type/keyid~Keyid>} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - override the creation time of the signature
* @param {Array} [userIds] - user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Boolean} [streaming] - whether to process data as a stream
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<Signature>} new detached signature of message content
* @param {Array<Key>} privateKeys - private keys with decrypted secret key data for signing
* @param {Signature} [signature] - Any existing detached signature
* @param {Array<module:type/keyid~Keyid>} [signingKeyIds] - Array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - Override the creation time of the signature
* @param {Array} [userIds] - User IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Boolean} [streaming] - Whether to process data as a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Signature>} New detached signature of message content.
* @async
*/
async signDetached(privateKeys = [], signature = null, signingKeyIds = [], date = new Date(), userIds = [], streaming = false, config = defaultConfig) {
@ -519,11 +519,11 @@ export class Message {
/**
* Verify message signatures
* @param {Array<Key>} 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
* @param {Boolean} streaming (optional) whether to process data as a stream
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Array<({keyid: module:type/keyid~Keyid, valid: Boolean})>>} list of signer's keyid and validity of signature
* @param {Array<Key>} keys - Array of keys to verify signatures
* @param {Date} [date] - Verify the signature against the given date, i.e. check signature creation time < date < expiration time
* @param {Boolean} [streaming] - Whether to process data as a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<({keyid: module:type/keyid~Keyid, valid: Boolean})>>} List of signer's keyid and validity of signature.
* @async
*/
async verify(keys, date = new Date(), streaming, config = defaultConfig) {
@ -572,11 +572,11 @@ export class Message {
/**
* Verify detached message signature
* @param {Array<Key>} keys array of keys to verify signatures
* @param {Array<Key>} 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
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {Promise<Array<({keyid: module:type/keyid~Keyid, valid: Boolean})>>} list of signer's keyid and validity of signature
* @param {Date} date - Verify the signature against the given date, i.e. check signature creation time < date < expiration time
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<({keyid: module:type/keyid~Keyid, valid: Boolean})>>} List of signer's keyid and validity of signature.
* @async
*/
verifyDetached(signature, keys, date = new Date(), streaming, config = defaultConfig) {
@ -591,7 +591,7 @@ export class Message {
/**
* Unwrap compressed message
* @returns {Message} message Content of compressed message
* @returns {Message} Message Content of compressed message.
*/
unwrapCompressed() {
const compressed = this.packets.filterByTag(enums.packet.compressedData);
@ -603,7 +603,7 @@ export class Message {
/**
* Append signature to unencrypted message object
* @param {String|Uint8Array} detachedSignature The detached ASCII-armored or Uint8Array PGP signature
* @param {String|Uint8Array} detachedSignature - The detached ASCII-armored or Uint8Array PGP signature
*/
async appendSignature(detachedSignature) {
await this.packets.read(util.isUint8Array(detachedSignature) ? detachedSignature : (await unarmor(detachedSignature)).data, { SignaturePacket });
@ -611,7 +611,7 @@ export class Message {
/**
* Returns binary encoded message
* @returns {ReadableStream<Uint8Array>} binary message
* @returns {ReadableStream<Uint8Array>} Binary message.
*/
write() {
return this.packets.write();
@ -619,20 +619,20 @@ export class Message {
/**
* Returns ASCII armored text of message
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {ReadableStream<String>} ASCII armor
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {ReadableStream<String>} ASCII armor.
*/
armor(config = defaultConfig) {
return armor(enums.armor.message, this.write(), null, null, null, config);
}
/**
* creates new message object from text
* Creates new message object from text.
* @param {String | ReadableStream<String>} text
* @param {String} filename (optional)
* @param {Date} date (optional)
* @param {utf8|binary|text|mime} type (optional) data packet type
* @returns {Message} new message object
* @param {String} [filename="msg.txt"]
* @param {Date} [date=current date]
* @param {utf8|binary|text|mime} [type] - Data packet type
* @returns {Message} New message object.
* @static
*/
static fromText(text, filename, date = new Date(), type = 'utf8') {
@ -654,12 +654,12 @@ export class Message {
}
/**
* creates new message object from binary data
* Creates new message object from binary data.
* @param {Uint8Array | ReadableStream<Uint8Array>} bytes
* @param {String} filename (optional)
* @param {Date} date (optional)
* @param {utf8|binary|text|mime} type (optional) data packet type
* @returns {Message} new message object
* @param {String} [filename="msg.txt"]
* @param {Date} [date=current date]
* @param {utf8|binary|text|mime} [type] - Data packet type
* @returns {Message} New message object.
* @static
*/
static fromBinary(bytes, filename, date = new Date(), type = 'binary') {
@ -686,16 +686,16 @@ export class Message {
/**
* Create signature packets for the message
* @param {LiteralDataPacket} literalDataPacket the literal data packet to sign
* @param {Array<Key>} privateKeys private keys with decrypted secret key data for signing
* @param {Signature} [signature] - any existing detached signature to append
* @param {Array<module:type/keyid~Keyid>} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - override the creationtime of the signature
* @param {Array} [userIds] - user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Boolean} [detached] - whether to create detached signature packets
* @param {Boolean} [streaming] - whether to process data as a stream
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {Promise<PacketList>} list of signature packets
* @param {LiteralDataPacket} literalDataPacket - the literal data packet to sign
* @param {Array<Key>} privateKeys - private keys with decrypted secret key data for signing
* @param {Signature} [signature] - Any existing detached signature to append
* @param {Array<module:type/keyid~Keyid>} [signingKeyIds] - Array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [date] - Override the creationtime of the signature
* @param {Array} [userIds] - User IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Boolean} [detached] - Whether to create detached signature packets
* @param {Boolean} [streaming] - Whether to process data as a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<PacketList>} List of signature packets.
* @async
* @private
*/
@ -726,13 +726,13 @@ export async function createSignaturePackets(literalDataPacket, privateKeys, sig
/**
* Create object containing signer's keyid and validity of signature
* @param {SignaturePacket} signature signature packets
* @param {Array<LiteralDataPacket>} literalDataList array of literal data packets
* @param {Array<Key>} keys array of keys to verify signatures
* @param {Date} date Verify the signature against the given date,
* @param {SignaturePacket} signature - Signature packets
* @param {Array<LiteralDataPacket>} literalDataList - Array of literal data packets
* @param {Array<Key>} keys - Array of keys to verify signatures
* @param {Date} date - Verify the signature against the given date,
* i.e. check signature creation time < date < expiration time
* @param {Boolean} detached (optional) whether to verify detached signature packets
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Boolean} [detached] - Whether to verify detached signature packets
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<{keyid: module:type/keyid~Keyid,
* valid: Boolean|null}>>} list of signer's keyid and validity of signature
* @async
@ -789,13 +789,13 @@ async function createVerificationObject(signature, literalDataList, keys, date =
/**
* Create list of objects containing signer's keyid and validity of signature
* @param {Array<SignaturePacket>} signatureList array of signature packets
* @param {Array<LiteralDataPacket>} literalDataList array of literal data packets
* @param {Array<Key>} keys array of keys to verify signatures
* @param {Date} date Verify the signature against the given date,
* @param {Array<SignaturePacket>} signatureList - Array of signature packets
* @param {Array<LiteralDataPacket>} literalDataList - Array of literal data packets
* @param {Array<Key>} keys - Array of keys to verify signatures
* @param {Date} date - Verify the signature against the given date,
* i.e. check signature creation time < date < expiration time
* @param {Boolean} detached (optional) whether to verify detached signature packets
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Boolean} [detached] - Whether to verify detached signature packets
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Array<{keyid: module:type/keyid~Keyid,
* valid: Boolean}>>} list of signer's keyid and validity of signature
* @async
@ -812,10 +812,10 @@ export async function createVerificationObjects(signatureList, literalDataList,
/**
* Reads an (optionally armored) OpenPGP message and returns a Message object
* @param {Object} options
* @param {String | ReadableStream<String>} [options.armoredMessage] - armored message to be parsed
* @param {Uint8Array | ReadableStream<Uint8Array>} [options.binaryMessage] - binary to be parsed
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Message>} new message object
* @param {String | ReadableStream<String>} [options.armoredMessage] - Armored message to be parsed
* @param {Uint8Array | ReadableStream<Uint8Array>} [options.binaryMessage] - Binary to be parsed
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Message>} New message object.
* @async
* @static
*/

244
src/openpgp.js
View File

@ -39,20 +39,20 @@ if (globalThis.ReadableStream) {
/**
* Generates a new OpenPGP key pair. Supports RSA and ECC keys. By default, primary and subkeys will be of same type.
* @param {Object} options
* @param {'ecc'|'rsa'} [options.type='ecc'] - The primary key algorithm type: ECC (default) or RSA
* @param {Object|Array<Object>} options.userIds - User IDs as objects: `{ name:'Jo Doe', email:'info@jo.com' }`
* @param {String} [options.passphrase] - The passphrase used to encrypt the resulting private key
* @param {Number} [options.rsaBits=4096] - Number of bits for RSA keys
* @param {String} [options.curve='curve25519'] - Elliptic curve for ECC keys:
* @param {Object} options
* @param {'ecc'|'rsa'} [options.type='ecc'] - The primary key algorithm type: ECC (default) or RSA
* @param {Object|Array<Object>} options.userIds - User IDs as objects: `{ name: 'Jo Doe', email: 'info@jo.com' }`
* @param {String} [options.passphrase=(not protected)] - The passphrase used to encrypt the generated private key
* @param {Number} [options.rsaBits=4096] - Number of bits for RSA keys
* @param {String} [options.curve='curve25519'] - Elliptic curve for ECC keys:
* curve25519 (default), p256, p384, p521, secp256k1,
* brainpoolP256r1, brainpoolP384r1, or brainpoolP512r1
* @param {Date} [options.date=current date] - Override the creation date of the key and the key signatures
* @param {Number} [options.keyExpirationTime=0 (never expires)] - Number of seconds from the key creation time after which the key expires
* @param {Array<Object>} [options.subkeys=a single encryption subkey] - Options for each subkey, default to main key options. e.g. [{sign: true, passphrase: '123'}]
* @param {Date} [options.date=current date] - Override the creation date of the key and the key signatures
* @param {Number} [options.keyExpirationTime=0 (never expires)] - Number of seconds from the key creation time after which the key expires
* @param {Array<Object>} [options.subkeys=a single encryption subkey] - Options for each subkey, default to main key options. e.g. `[{sign: true, passphrase: '123'}]`
* sign parameter defaults to false, and indicates whether the subkey should sign rather than encrypt
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} The generated key object in the form:
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} The generated key object in the form:
* { key:Key, privateKeyArmored:String, publicKeyArmored:String, revocationCertificate:String }
* @async
* @static
@ -82,13 +82,13 @@ export function generateKey({ userIds = [], passphrase = "", type = "ecc", rsaBi
/**
* Reformats signature packets for a key and rewraps key object.
* @param {Object} options
* @param {Key} options.privateKey - Private key to reformat
* @param {Object|Array<Object>} options.userIds - User IDs as objects: `{ name:'Jo Doe', email:'info@jo.com' }`
* @param {String} [options.passphrase="" (not protected)] - The passphrase used to encrypt the resulting private key
* @param {Number} [options.keyExpirationTime=0 (never expires)] - Number of seconds from the key creation time after which the key expires
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} The generated key object in the form:
* @param {Object} options
* @param {Key} options.privateKey - Private key to reformat
* @param {Object|Array<Object>} options.userIds - User IDs as objects: `{ name: 'Jo Doe', email: 'info@jo.com' }`
* @param {String} [options.passphrase=(not protected)] - The passphrase used to encrypt the generated private key
* @param {Number} [options.keyExpirationTime=0 (never expires)] - Number of seconds from the key creation time after which the key expires
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} The generated key object in the form:
* { key:Key, privateKeyArmored:String, publicKeyArmored:String, revocationCertificate:String }
* @async
* @static
@ -115,15 +115,15 @@ export function reformatKey({ privateKey, userIds = [], passphrase = "", keyExpi
/**
* Revokes a key. Requires either a private key or a revocation certificate.
* If a revocation certificate is passed, the reasonForRevocation parameters will be ignored.
* @param {Object} options
* @param {Key} options.key - public or private key to revoke
* @param {String} [options.revocationCertificate] - revocation certificate to revoke the key with
* @param {Object} [options.reasonForRevocation] - object indicating the reason for revocation
* @param {module:enums.reasonForRevocation} [options.reasonForRevocation.flag=[noReason]{@link module:enums.reasonForRevocation}] - flag indicating the reason for revocation
* @param {String} [options.reasonForRevocation.string=""] - string explaining the reason for revocation
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} The revoked key object in the form:
* If a revocation certificate is passed, the reasonForRevocation parameter will be ignored.
* @param {Object} options
* @param {Key} options.key - Public or private key to revoke
* @param {String} [options.revocationCertificate] - Revocation certificate to revoke the key with
* @param {Object} [options.reasonForRevocation] - Object indicating the reason for revocation
* @param {module:enums.reasonForRevocation} [options.reasonForRevocation.flag=[noReason]{@link module:enums.reasonForRevocation}] - Flag indicating the reason for revocation
* @param {String} [options.reasonForRevocation.string=""] - String explaining the reason for revocation
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} The revoked key object in the form:
* `{ privateKey:Key, privateKeyArmored:String, publicKey:Key, publicKeyArmored:String }`
* (if private key is passed) or `{ publicKey:Key, publicKeyArmored:String }` (otherwise)
* @async
@ -157,11 +157,11 @@ export function revokeKey({ key, revocationCertificate, reasonForRevocation, con
/**
* Unlock a private key with the given passphrase.
* This method does not change the original key.
* @param {Object} options
* @param {Key} options.privateKey - the private key to decrypt
* @param {String|Array<String>} options.passphrase - the user's passphrase(s)
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Key>} the unlocked key object
* @param {Object} options
* @param {Key} options.privateKey - The private key to decrypt
* @param {String|Array<String>} options.passphrase - The user's passphrase(s)
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Key>} The unlocked key object.
* @async
*/
export async function decryptKey({ privateKey, passphrase, config }) {
@ -186,11 +186,11 @@ export async function decryptKey({ privateKey, passphrase, config }) {
/**
* Lock a private key with the given passphrase.
* This method does not change the original key.
* @param {Object} options
* @param {Key} options.privateKey - the private key to encrypt
* @param {String|Array<String>} options.passphrase - if multiple passphrases, they should be in the same order as the packets each should encrypt
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Key>} the locked key object
* @param {Object} options
* @param {Key} options.privateKey - The private key to encrypt
* @param {String|Array<String>} options.passphrase - If multiple passphrases, they should be in the same order as the packets each should encrypt
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Key>} The locked key object.
* @async
*/
export async function encryptKey({ privateKey, passphrase, config }) {
@ -230,23 +230,23 @@ export async function encryptKey({ privateKey, passphrase, config }) {
/**
* Encrypts message text/data with public keys, passwords or both at once. At least either public keys or passwords
* must be specified. If private keys are specified, those will be used to sign the message.
* @param {Object} options
* @param {Message} options.message - message to be encrypted as created by {@link Message.fromText} or {@link Message.fromBinary}
* @param {Key|Array<Key>} [options.publicKeys] - array of keys or single key, used to encrypt the message
* @param {Key|Array<Key>} [options.privateKeys] - private keys for signing. If omitted message will not be signed
* @param {String|Array<String>} [options.passwords] - array of passwords or a single password to encrypt the message
* @param {Object} [options.sessionKey] - session key in the form: `{ data:Uint8Array, algorithm:String }`
* @param {Boolean} [options.armor=true] - whether the return values should be ascii armored (true, the default) or binary (false)
* @param {'web'|'ponyfill'|'node'|false} [options.streaming=type of stream `message` was created from, if any] - whether to return data as a stream
* @param {Signature} [options.signature] - a detached signature to add to the encrypted message
* @param {Boolean} [options.wildcard=false] - use a key ID of 0 instead of the public key IDs
* @param {Array<module:type/keyid~Keyid>} [options.signingKeyIds=latest-created valid signing (sub)keys] - array of key IDs to use for signing. Each `signingKeyIds[i]` corresponds to `privateKeys[i]`
* @param {Array<module:type/keyid~Keyid>} [options.encryptionKeyIds=latest-created valid encryption (sub)keys] - array of key IDs to use for encryption. Each `encryptionKeyIds[i]` corresponds to `publicKeys[i]`
* @param {Date} [options.date=current date] - override the creation date of the message signature
* @param {Array<Object>} [options.fromUserIds=primary user IDs] - array of user IDs to sign with, one per key in `privateKeys`, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Array<Object>} [options.toUserIds=primary user IDs] - array of user IDs to encrypt for, one per key in `publicKeys`, e.g. [{ name:'Robert Receiver', email:'robert@openpgp.org' }]
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<String|ReadableStream<String>|NodeStream<String>|Uint8Array|ReadableStream<Uint8Array>|NodeStream<Uint8Array>>} (String if `armor` was true, the default; Uint8Array if `armor` was false)
* @param {Object} options
* @param {Message} options.message - Message to be encrypted as created by {@link Message.fromText} or {@link Message.fromBinary}
* @param {Key|Array<Key>} [options.publicKeys] - Array of keys or single key, used to encrypt the message
* @param {Key|Array<Key>} [options.privateKeys] - Private keys for signing. If omitted message will not be signed
* @param {String|Array<String>} [options.passwords] - Array of passwords or a single password to encrypt the message
* @param {Object} [options.sessionKey] - Session key in the form: `{ data:Uint8Array, algorithm:String }`
* @param {Boolean} [options.armor=true] - Whether the return values should be ascii armored (true, the default) or binary (false)
* @param {'web'|'ponyfill'|'node'|false} [options.streaming=type of stream `message` was created from, if any] - Whether to return data as a stream
* @param {Signature} [options.signature] - A detached signature to add to the encrypted message
* @param {Boolean} [options.wildcard=false] - Use a key ID of 0 instead of the public key IDs
* @param {Array<module:type/keyid~Keyid>} [options.signingKeyIds=latest-created valid signing (sub)keys] - Array of key IDs to use for signing. Each `signingKeyIds[i]` corresponds to `privateKeys[i]`
* @param {Array<module:type/keyid~Keyid>} [options.encryptionKeyIds=latest-created valid encryption (sub)keys] - Array of key IDs to use for encryption. Each `encryptionKeyIds[i]` corresponds to `publicKeys[i]`
* @param {Date} [options.date=current date] - Override the creation date of the message signature
* @param {Array<Object>} [options.fromUserIds=primary user IDs] - Array of user IDs to sign with, one per key in `privateKeys`, e.g. `[{ name: 'Steve Sender', email: 'steve@openpgp.org' }]`
* @param {Array<Object>} [options.toUserIds=primary user IDs] - Array of user IDs to encrypt for, one per key in `publicKeys`, e.g. `[{ name: 'Robert Receiver', email: 'robert@openpgp.org' }]`
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<String|ReadableStream<String>|NodeStream<String>|Uint8Array|ReadableStream<Uint8Array>|NodeStream<Uint8Array>>} Encrypted message (string if `armor` was true, the default; Uint8Array if `armor` was false).
* @async
* @static
*/
@ -274,18 +274,18 @@ export function encrypt({ message, publicKeys, privateKeys, passwords, sessionKe
/**
* Decrypts a message with the user's private key, a session key or a password. Either a private key,
* a session key or a password must be specified.
* @param {Object} options
* @param {Message} options.message - the message object with the encrypted data
* @param {Key|Array<Key>} [options.privateKeys] - private keys with decrypted secret key data or session key
* @param {String|Array<String>} [options.passwords] - passwords to decrypt the message
* @param {Object|Array<Object>} [options.sessionKeys] - session keys in the form: { data:Uint8Array, algorithm:String }
* @param {Key|Array<Key>} [options.publicKeys] - array of public keys or single key, to verify signatures
* @param {'utf8'|'binary'} [options.format] - whether to return data as a string(Stream) or Uint8Array(Stream). If 'utf8' (the default), also normalize newlines.
* @param {'web'|'ponyfill'|'node'|false} [options.streaming=type of stream `message` was created from, if any] - whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @param {Signature} [options.signature] - detached signature for verification
* @param {Date} [options.date=current date] - use the given date for verification instead of the current time
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} Object containing decrypted and verified message in the form:
* @param {Object} options
* @param {Message} options.message - The message object with the encrypted data
* @param {Key|Array<Key>} [options.privateKeys] - Private keys with decrypted secret key data or session key
* @param {String|Array<String>} [options.passwords] - Passwords to decrypt the message
* @param {Object|Array<Object>} [options.sessionKeys] - Session keys in the form: { data:Uint8Array, algorithm:String }
* @param {Key|Array<Key>} [options.publicKeys] - Array of public keys or single key, to verify signatures
* @param {'utf8'|'binary'} [options.format='utf8'] - Whether to return data as a string(Stream) or Uint8Array(Stream). If 'utf8' (the default), also normalize newlines.
* @param {'web'|'ponyfill'|'node'|false} [options.streaming=type of stream `message` was created from, if any] - Whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @param {Signature} [options.signature] - Detached signature for verification
* @param {Date} [options.date=current date] - Use the given date for verification instead of the current time
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} Object containing decrypted and verified message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if format was 'utf8', the default)
@ -332,17 +332,17 @@ export function decrypt({ message, privateKeys, passwords, sessionKeys, publicKe
/**
* Signs a message.
* @param {Object} options
* @param {CleartextMessage|Message} options.message - (cleartext) message to be signed
* @param {Key|Array<Key>} options.privateKeys - array of keys or single key with decrypted secret key data to sign cleartext
* @param {Boolean} [options.armor=true] - whether the return values should be ascii armored (true, the default) or binary (false)
* @param {'web'|'ponyfill'|'node'|false} [options.streaming=type of stream `message` was created from, if any] - whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @param {Boolean} [options.detached=false] - if the return value should contain a detached signature
* @param {Array<module:type/keyid~Keyid>} [options.signingKeyIds=latest-created valid signing (sub)keys] - array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [options.date=current date] - override the creation date of the signature
* @param {Array<Object>} [options.fromUserIds=primary user IDs] - array of user IDs to sign with, one per key in `privateKeys`, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }]
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<String|ReadableStream<String>|NodeStream<String>|Uint8Array|ReadableStream<Uint8Array>|NodeStream<Uint8Array>>} (String if `armor` was true, the default; Uint8Array if `armor` was false)
* @param {Object} options
* @param {CleartextMessage|Message} options.message - (cleartext) message to be signed
* @param {Key|Array<Key>} options.privateKeys - Array of keys or single key with decrypted secret key data to sign cleartext
* @param {Boolean} [options.armor=true] - Whether the return values should be ascii armored (true, the default) or binary (false)
* @param {'web'|'ponyfill'|'node'|false} [options.streaming=type of stream `message` was created from, if any] - Whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @param {Boolean} [options.detached=false] - If the return value should contain a detached signature
* @param {Array<module:type/keyid~Keyid>} [options.signingKeyIds=latest-created valid signing (sub)keys] - Array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i]
* @param {Date} [options.date=current date] - Override the creation date of the signature
* @param {Array<Object>} [options.fromUserIds=primary user IDs] - Array of user IDs to sign with, one per key in `privateKeys`, e.g. `[{ name: 'Steve Sender', email: 'steve@openpgp.org' }]`
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<String|ReadableStream<String>|NodeStream<String>|Uint8Array|ReadableStream<Uint8Array>|NodeStream<Uint8Array>>} Signed message (string if `armor` was true, the default; Uint8Array if `armor` was false).
* @async
* @static
*/
@ -377,15 +377,15 @@ export function sign({ message, privateKeys, armor = true, streaming = message &
/**
* Verifies signatures of cleartext signed message
* @param {Object} options
* @param {Key|Array<Key>} options.publicKeys - array of publicKeys or single key, to verify signatures
* @param {CleartextMessage|Message} options.message - (cleartext) message object with signatures
* @param {'utf8'|'binary'} [options.format] - whether to return data as a string(Stream) or Uint8Array(Stream). If 'utf8' (the default), also normalize newlines.
* @param {'web'|'ponyfill'|'node'|false} [options.streaming=type of stream `message` was created from, if any] - whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @param {Signature} [options.signature] - detached signature for verification
* @param {Date} [options.date=current date] - use the given date for verification instead of the current time
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} Object containing verified message in the form:
* @param {Object} options
* @param {Key|Array<Key>} options.publicKeys - Array of publicKeys or single key, to verify signatures
* @param {CleartextMessage|Message} options.message - (cleartext) message object with signatures
* @param {'utf8'|'binary'} [options.format='utf8'] - Whether to return data as a string(Stream) or Uint8Array(Stream). If 'utf8' (the default), also normalize newlines.
* @param {'web'|'ponyfill'|'node'|false} [options.streaming=type of stream `message` was created from, if any] - Whether to return data as a stream. Defaults to the type of stream `message` was created from, if any.
* @param {Signature} [options.signature] - Detached signature for verification
* @param {Date} [options.date=current date] - Use the given date for verification instead of the current time
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object>} Object containing verified message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if `message` was a CleartextMessage)
@ -431,12 +431,12 @@ export function verify({ message, publicKeys, format = 'utf8', streaming = messa
/**
* Generate a new session key object, taking the algorithm preferences of the passed public keys into account.
* @param {Object} options
* @param {Key|Array<Key>} options.publicKeys - array of public keys or single key used to select algorithm preferences for
* @param {Date} [options.date=current date] - date to select algorithm preferences at
* @param {Array} [options.toUserIds=primary user IDs] - user IDs to select algorithm preferences for
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<{ data: Uint8Array, algorithm: String }>} object with session key data and algorithm
* @param {Object} options
* @param {Key|Array<Key>} options.publicKeys - Array of public keys or single key used to select algorithm preferences for
* @param {Date} [options.date=current date] - Date to select algorithm preferences at
* @param {Array} [options.toUserIds=primary user IDs] - User IDs to select algorithm preferences for
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<{ data: Uint8Array, algorithm: String }>} Object with session key data and algorithm.
* @async
* @static
*/
@ -454,19 +454,19 @@ export function generateSessionKey({ publicKeys, date = new Date(), toUserIds =
/**
* Encrypt a symmetric session key with public keys, passwords, or both at once. At least either public keys
* or passwords must be specified.
* @param {Object} options
* @param {Uint8Array} options.data - the session key to be encrypted e.g. 16 random bytes (for aes128)
* @param {String} options.algorithm - algorithm of the symmetric session key e.g. 'aes128' or 'aes256'
* @param {String} [options.aeadAlgorithm] - aead algorithm, e.g. 'eax' or 'ocb'
* @param {Key|Array<Key>} [options.publicKeys] - array of public keys or single key, used to encrypt the key
* @param {String|Array<String>} [options.passwords] - passwords for the message
* @param {Boolean} [options.armor=true] - whether the return values should be ascii armored (true, the default) or binary (false)
* @param {Boolean} [options.wildcard] - use a key ID of 0 instead of the public key IDs
* @param {Array<module:type/keyid~Keyid>} [options.encryptionKeyIds=latest-created valid encryption (sub)keys] - array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i]
* @param {Date} [options.date=current date] - override the date
* @param {Array} [options.toUserIds=primary user IDs] - array of user IDs to encrypt for, one per key in `publicKeys`, e.g. [{ name:'Phil Zimmermann', email:'phil@openpgp.org' }]
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<String|Uint8Array>} (String if `armor` was true, the default; Uint8Array if `armor` was false)
* @param {Object} options
* @param {Uint8Array} options.data - The session key to be encrypted e.g. 16 random bytes (for aes128)
* @param {String} options.algorithm - Algorithm of the symmetric session key e.g. 'aes128' or 'aes256'
* @param {String} [options.aeadAlgorithm] - Aead algorithm, e.g. 'eax' or 'ocb'
* @param {Key|Array<Key>} [options.publicKeys] - Array of public keys or single key, used to encrypt the key
* @param {String|Array<String>} [options.passwords] - Passwords for the message
* @param {Boolean} [options.armor=true] - Whether the return values should be ascii armored (true, the default) or binary (false)
* @param {Boolean} [options.wildcard=false] - Use a key ID of 0 instead of the public key IDs
* @param {Array<module:type/keyid~Keyid>} [options.encryptionKeyIds=latest-created valid encryption (sub)keys] - Array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i]
* @param {Date} [options.date=current date] - Override the date
* @param {Array} [options.toUserIds=primary user IDs] - Array of user IDs to encrypt for, one per key in `publicKeys`, e.g. `[{ name: 'Phil Zimmermann', email: 'phil@openpgp.org' }]`
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<String|Uint8Array>} Encrypted session keys (string if `armor` was true, the default; Uint8Array if `armor` was false).
* @async
* @static
*/
@ -485,12 +485,12 @@ export function encryptSessionKey({ data, algorithm, aeadAlgorithm, publicKeys,
/**
* Decrypt symmetric session keys with a private key or password. Either a private key or
* a password must be specified.
* @param {Object} options
* @param {Message} options.message - a message object containing the encrypted session key packets
* @param {Key|Array<Key>} [options.privateKeys] - private keys with decrypted secret key data
* @param {String|Array<String>} [options.passwords] - passwords to decrypt the session key
* @param {Object} [options.config] - custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object|undefined>} Array of decrypted session key, algorithm pairs in form:
* @param {Object} options
* @param {Message} options.message - A message object containing the encrypted session key packets
* @param {Key|Array<Key>} [options.privateKeys] - Private keys with decrypted secret key data
* @param {String|Array<String>} [options.passwords] - Passwords to decrypt the session key
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Promise<Object|undefined>} Array of decrypted session key, algorithm pairs in the form:
* { data:Uint8Array, algorithm:String }
* or 'undefined' if no key packets found
* @async
@ -542,8 +542,8 @@ function checkCleartextOrMessage(message) {
/**
* Normalize parameter to an array if it is not undefined.
* @param {Object} param the parameter to be normalized
* @returns {Array<Object>|undefined} the resulting array or undefined
* @param {Object} param - the parameter to be normalized
* @returns {Array<Object>|undefined} The resulting array or undefined.
* @private
*/
function toArray(param) {
@ -555,10 +555,10 @@ function toArray(param) {
/**
* Convert data to or from Stream
* @param {Object} data the data to convert
* @param {'web'|'ponyfill'|'node'|false} [options.streaming] - whether to return a ReadableStream, and of what type
* @param {'utf8'|'binary'} [options.encoding] - how to return data in Node Readable streams
* @returns {Object} the data in the respective format
* @param {Object} data - the data to convert
* @param {'web'|'ponyfill'|'node'|false} [options.streaming] - Whether to return a ReadableStream, and of what type
* @param {'utf8'|'binary'} [options.encoding] - How to return data in Node Readable streams
* @returns {Object} The data in the respective format.
* @private
*/
async function convertStream(data, streaming, encoding = 'utf8') {
@ -584,8 +584,8 @@ async function convertStream(data, streaming, encoding = 'utf8') {
/**
* Link result.data to the message stream for cancellation.
* Also, forward errors in the message to result.data.
* @param {Object} result the data to convert
* @param {Message} message message object
* @param {Object} result - the data to convert
* @param {Message} message - message object
* @returns {Object}
* @private
*/
@ -607,7 +607,7 @@ function linkStreams(result, message) {
/**
* Wait until signature objects have been verified
* @param {Object} signatures list of signatures
* @param {Object} signatures - list of signatures
* @private
*/
async function prepareSignatures(signatures) {
@ -626,8 +626,8 @@ async function prepareSignatures(signatures) {
/**
* Global error handler that logs the stack trace and rethrows a high lvl error message.
* @param {String} message A human readable high level error Message
* @param {Error} error The internal error that caused the failure
* @param {String} message - A human readable high level error Message
* @param {Error} error - The internal error that caused the failure
* @private
*/
function onError(message, error) {

24
src/packet/aead_encrypted_data.js
View File

@ -69,7 +69,7 @@ class AEADEncryptedDataPacket {
/**
* Write the encrypted payload of bytes in the order: version, IV, ciphertext (see specification)
* @returns {Uint8Array | ReadableStream<Uint8Array>} The encrypted payload
* @returns {Uint8Array | ReadableStream<Uint8Array>} The encrypted payload.
*/
write() {
return util.concat([new Uint8Array([this.version, this.cipherAlgo, this.aeadAlgo, this.chunkSizeByte]), this.iv, this.encrypted]);
@ -77,9 +77,9 @@ class AEADEncryptedDataPacket {
/**
* 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
* @param {Boolean} streaming Whether the top-level function will return a stream
* @param {String} sessionKeyAlgorithm - The session key's cipher algorithm e.g. 'aes128'
* @param {Uint8Array} key - The session key used to encrypt the payload
* @param {Boolean} streaming - Whether the top-level function will return a stream
* @throws {Error} if decryption was not successful
* @async
*/
@ -94,10 +94,10 @@ class AEADEncryptedDataPacket {
/**
* 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
* @param {Boolean} streaming Whether the top-level function will return a stream
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {String} sessionKeyAlgorithm - The session key's cipher algorithm e.g. 'aes128'
* @param {Uint8Array} key - The session key used to encrypt the payload
* @param {Boolean} streaming - Whether the top-level function will return a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if encryption was not successful
* @async
*/
@ -113,10 +113,10 @@ class AEADEncryptedDataPacket {
/**
* En/decrypt the payload.
* @param {encrypt|decrypt} fn Whether to encrypt or decrypt
* @param {Uint8Array} key The session key used to en/decrypt the payload
* @param {Uint8Array | ReadableStream<Uint8Array>} data The data to en/decrypt
* @param {Boolean} streaming Whether the top-level function will return a stream
* @param {encrypt|decrypt} fn - Whether to encrypt or decrypt
* @param {Uint8Array} key - The session key used to en/decrypt the payload
* @param {Uint8Array | ReadableStream<Uint8Array>} data - The data to en/decrypt
* @param {Boolean} streaming - Whether the top-level function will return a stream
* @returns {Uint8Array | ReadableStream<Uint8Array>}
* @async
*/

6
src/packet/all_packets.js
View File

@ -25,8 +25,8 @@ export { default as TrustPacket } from './trust.js';
/**
* Allocate a new packet
* @function newPacketFromTag
* @param {String} tag property name from {@link module:enums.packet}
* @returns {Object} new packet object with type based on tag
* @param {String} tag - Property name from {@link module:enums.packet}
* @returns {Object} New packet object with type based on tag.
*/
export function newPacketFromTag(tag, allowedPackets) {
const className = packetClassFromTagName(tag);
@ -38,7 +38,7 @@ export function newPacketFromTag(tag, allowedPackets) {
/**
* Convert tag name to class name
* @param {String} tag property name from {@link module:enums.packet}
* @param {String} tag - Property name from {@link module:enums.packet}
* @returns {String}
* @private
*/

6
src/packet/compressed_data.js
View File

@ -39,7 +39,7 @@ import {
*/
class CompressedDataPacket {
/**
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(config = defaultConfig) {
/**
@ -72,7 +72,7 @@ class CompressedDataPacket {
/**
* Parsing function for the packet.
* @param {Uint8Array | ReadableStream<Uint8Array>} bytes Payload of a tag 8 packet
* @param {Uint8Array | ReadableStream<Uint8Array>} bytes - Payload of a tag 8 packet
*/
async read(bytes, config, streaming) {
await stream.parse(bytes, async reader => {
@ -90,7 +90,7 @@ class CompressedDataPacket {
/**
* Return the compressed packet.
* @returns {Uint8Array | ReadableStream<Uint8Array>} binary compressed packet
* @returns {Uint8Array | ReadableStream<Uint8Array>} Binary compressed packet.
*/
write() {
if (this.compressed === null) {

30
src/packet/literal_data.js
View File

@ -28,7 +28,7 @@ import util from '../util';
*/
class LiteralDataPacket {
/**
* @param {Date} date the creation date of the literal package
* @param {Date} date - The creation date of the literal package
*/
constructor(date = new Date()) {
this.tag = enums.packet.literalData;
@ -42,8 +42,8 @@ class LiteralDataPacket {
/**
* Set the packet data to a javascript native string, end of line
* will be normalized to \r\n and by default text is converted to UTF8
* @param {String | ReadableStream<String>} text Any native javascript string
* @param {utf8|binary|text|mime} format (optional) The format of the string of bytes
* @param {String | ReadableStream<String>} text - Any native javascript string
* @param {utf8|binary|text|mime} [format] - The format of the string of bytes
*/
setText(text, format = 'utf8') {
this.format = format;
@ -54,8 +54,8 @@ class LiteralDataPacket {
/**
* Returns literal data packets as native JavaScript string
* with normalized end of line to \n
* @param {Boolean} clone (optional) Whether to return a clone so that getBytes/getText can be called again
* @returns {String | ReadableStream<String>} literal data as text
* @param {Boolean} [clone] - Whether to return a clone so that getBytes/getText can be called again
* @returns {String | ReadableStream<String>} Literal data as text.
*/
getText(clone = false) {
if (this.text === null || util.isStream(this.text)) { // Assume that this.text has been read
@ -66,8 +66,8 @@ class LiteralDataPacket {
/**
* Set the packet data to value represented by the provided string of bytes.
* @param {Uint8Array | ReadableStream<Uint8Array>} bytes The string of bytes
* @param {utf8|binary|text|mime} format The format of the string of bytes
* @param {Uint8Array | ReadableStream<Uint8Array>} bytes - The string of bytes
* @param {utf8|binary|text|mime} format - The format of the string of bytes
*/
setBytes(bytes, format) {
this.format = format;
@ -78,8 +78,8 @@ class LiteralDataPacket {
/**
* Get the byte sequence representing the literal packet data
* @param {Boolean} clone (optional) Whether to return a clone so that getBytes/getText can be called again
* @returns {Uint8Array | ReadableStream<Uint8Array>} A sequence of bytes
* @param {Boolean} [clone] - Whether to return a clone so that getBytes/getText can be called again
* @returns {Uint8Array | ReadableStream<Uint8Array>} A sequence of bytes.
*/
getBytes(clone = false) {
if (this.data === null) {
@ -95,7 +95,7 @@ class LiteralDataPacket {
/**
* Sets the filename of the literal packet data
* @param {String} filename Any native javascript string
* @param {String} filename - Any native javascript string
*/
setFilename(filename) {
this.filename = filename;
@ -104,7 +104,7 @@ class LiteralDataPacket {
/**
* Get the filename of the literal packet data
* @returns {String} filename
* @returns {String} Filename.
*/
getFilename() {
return this.filename;
@ -114,8 +114,8 @@ class LiteralDataPacket {
/**
* Parsing function for a literal data packet (tag 11).
*
* @param {Uint8Array | ReadableStream<Uint8Array>} input Payload of a tag 11 packet
* @returns {LiteralDataPacket} object representation
* @param {Uint8Array | ReadableStream<Uint8Array>} input - Payload of a tag 11 packet
* @returns {LiteralDataPacket} Object representation.
*/
async read(bytes) {
await stream.parse(bytes, async reader => {
@ -136,7 +136,7 @@ class LiteralDataPacket {
/**
* Creates a Uint8Array representation of the packet, excluding the data
*
* @returns {Uint8Array} Uint8Array representation of the packet
* @returns {Uint8Array} Uint8Array representation of the packet.
*/
writeHeader() {
const filename = util.encodeUtf8(this.filename);
@ -151,7 +151,7 @@ class LiteralDataPacket {
/**
* Creates a Uint8Array representation of the packet
*
* @returns {Uint8Array | ReadableStream<Uint8Array>} Uint8Array representation of the packet
* @returns {Uint8Array | ReadableStream<Uint8Array>} Uint8Array representation of the packet.
*/
write() {
const header = this.writeHeader();

4
src/packet/marker.js
View File

@ -38,13 +38,13 @@ class MarkerPacket {
/**
* Parsing function for a literal data packet (tag 10).
*
* @param {String} input Payload of a tag 10 packet
* @param {String} input - Payload of a tag 10 packet
* @param {Integer} position
* Position to start reading from the input string
* @param {Integer} len
* Length of the packet or the remaining length of
* input at position
* @returns {MarkerPacket} Object representation
* @returns {MarkerPacket} Object representation.
*/
read(bytes) {
if (bytes[0] === 0x50 && // P

6
src/packet/one_pass_signature.js
View File

@ -68,8 +68,8 @@ class OnePassSignaturePacket {
/**
* parsing function for a one-pass signature packet (tag 4).
* @param {Uint8Array} bytes payload of a tag 4 packet
* @returns {OnePassSignaturePacket} object representation
* @param {Uint8Array} bytes - Payload of a tag 4 packet
* @returns {OnePassSignaturePacket} Object representation.
*/
read(bytes) {
let mypos = 0;
@ -101,7 +101,7 @@ class OnePassSignaturePacket {
/**
* creates a string representation of a one-pass signature packet
* @returns {Uint8Array} a Uint8Array representation of a one-pass signature packet
* @returns {Uint8Array} A Uint8Array representation of a one-pass signature packet.
*/
write() {
const start = new Uint8Array([3, enums.write(enums.signature, this.signatureType),

18
src/packet/packet.js
View File

@ -54,8 +54,8 @@ export function readSimpleLength(bytes) {
* Encodes a given integer of length to the openpgp length specifier to a
* string
*
* @param {Integer} length The length to encode
* @returns {Uint8Array} String with openpgp length representation
* @param {Integer} length - The length to encode
* @returns {Uint8Array} String with openpgp length representation.
*/
export function writeSimpleLength(length) {
if (length < 192) {
@ -86,9 +86,9 @@ export function writeTag(tag_type) {
* Writes a packet header version 4 with the given tag_type and length to a
* string
*
* @param {Integer} tag_type Tag type
* @param {Integer} length Length of the payload
* @returns {String} String of the header
* @param {Integer} tag_type - Tag type
* @param {Integer} length - Length of the payload
* @returns {String} String of the header.
*/
export function writeHeader(tag_type, length) {
/* we're only generating v4 packet headers here */
@ -97,8 +97,8 @@ export function writeHeader(tag_type, length) {
/**
* Whether the packet type supports partial lengths per RFC4880
* @param {Integer} tag_type Tag type
* @returns {Boolean} String of the header
* @param {Integer} tag_type - Tag type
* @returns {Boolean} String of the header.
*/
export function supportsStreaming(tag_type) {
return [
@ -113,8 +113,8 @@ export function supportsStreaming(tag_type) {
/**
* Generic static Packet Parser function
*
* @param {Uint8Array | ReadableStream<Uint8Array>} input Input stream as string
* @param {Function} callback Function to call with the parsed packet
* @param {Uint8Array | ReadableStream<Uint8Array>} input - Input stream as string
* @param {Function} callback - Function to call with the parsed packet
* @returns {Boolean} Returns false if the stream was empty and parsing is done, and true otherwise.
*/
export async function readPackets(input, streaming, callback) {

6
src/packet/packetlist.js
View File

@ -18,7 +18,7 @@ import defaultConfig from '../config';
class PacketList extends Array {
/**
* Reads a stream of binary data and interprets it as a list of packets.
* @param {Uint8Array | ReadableStream<Uint8Array>} bytes A Uint8Array of bytes.
* @param {Uint8Array | ReadableStream<Uint8Array>} bytes - A Uint8Array of bytes.
*/
async read(bytes, allowedPackets, streaming, config = defaultConfig) {
this.stream = stream.transformPair(bytes, async (readable, writable) => {
@ -117,7 +117,7 @@ class PacketList extends Array {
/**
* Adds a packet to the list. This is the only supported method of doing so;
* writing to packetlist[i] directly will result in an error.
* @param {Object} packet Packet to push
* @param {Object} packet - Packet to push
*/
push(packet) {
if (!packet) {
@ -148,7 +148,7 @@ class PacketList extends Array {
/**
* Traverses packet tree and returns first matching packet
* @param {module:enums.packet} type The packet type
* @param {module:enums.packet} type - The packet type
* @returns {Packet|undefined}
*/
findPacket(type) {

20
src/packet/public_key.js
View File

@ -38,8 +38,8 @@ import util from '../util';
*/
class PublicKeyPacket {
/**
* @param {Date} [date] - creation date
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Date} [date] - Creation date
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(date = new Date(), config = defaultConfig) {
/**
@ -87,8 +87,8 @@ class PublicKeyPacket {
/**
* 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&lt;num&gt;
* @param {Uint8Array} bytes Input array to read the packet from
* @returns {Object} This object with attributes set by the parser
* @param {Uint8Array} bytes - Input array to read the packet from
* @returns {Object} This object with attributes set by the parser.
*/
read(bytes) {
let pos = 0;
@ -125,7 +125,7 @@ class PublicKeyPacket {
/**
* Creates an OpenPGP public key packet for the given key.
* @returns {Uint8Array} Bytes encoding the public key OpenPGP packet
* @returns {Uint8Array} Bytes encoding the public key OpenPGP packet.
*/
write() {
const arr = [];
@ -176,7 +176,7 @@ class PublicKeyPacket {
/**
* Calculates the key id of the key
* @returns {module:type/keyid~Keyid} A 8 byte key id
* @returns {module:type/keyid~Keyid} A 8 byte key id.
*/
getKeyId() {
if (this.keyid) {
@ -193,7 +193,7 @@ class PublicKeyPacket {
/**
* Calculates the fingerprint of the key
* @returns {Uint8Array} A Uint8Array containing the fingerprint
* @returns {Uint8Array} A Uint8Array containing the fingerprint.
*/
getFingerprintBytes() {
if (this.fingerprint) {
@ -210,7 +210,7 @@ class PublicKeyPacket {
/**
* Calculates the fingerprint of the key
* @returns {String} A string containing the fingerprint in lowercase hex
* @returns {String} A string containing the fingerprint in lowercase hex.
*/
getFingerprint() {
return util.uint8ArrayToHex(this.getFingerprintBytes());
@ -218,7 +218,7 @@ class PublicKeyPacket {
/**
* Calculates whether two keys have the same fingerprint without actually calculating the fingerprint
* @returns {Boolean} Whether the two keys have the same version and public key data
* @returns {Boolean} Whether the two keys have the same version and public key data.
*/
hasSameFingerprintAs(other) {
return this.version === other.version && util.equalsUint8Array(this.writePublicKey(), other.writePublicKey());
@ -226,7 +226,7 @@ class PublicKeyPacket {
/**
* Returns algorithm information
* @returns {Object} An object of the form {algorithm: String, bits:int, curve:String}
* @returns {Object} An object of the form {algorithm: String, bits:int, curve:String}.
*/
getAlgorithmInfo() {
const result = {};

6
src/packet/public_key_encrypted_session_key.js
View File

@ -54,7 +54,7 @@ class PublicKeyEncryptedSessionKeyPacket {
/**
* Parsing function for a publickey encrypted session key packet (tag 1).
*
* @param {Uint8Array} bytes Payload of a tag 1 packet
* @param {Uint8Array} bytes - Payload of a tag 1 packet
*/
read(bytes) {
this.version = bytes[0];
@ -68,7 +68,7 @@ class PublicKeyEncryptedSessionKeyPacket {
/**
* Create a binary representation of a tag 1 packet
*
* @returns {Uint8Array} The Uint8Array representation
* @returns {Uint8Array} The Uint8Array representation.
*/
write() {
const algo = enums.write(enums.publicKey, this.publicKeyAlgorithm);
@ -85,7 +85,7 @@ class PublicKeyEncryptedSessionKeyPacket {
/**
* Encrypt session key packet
* @param {PublicKeyPacket} key Public key
* @param {PublicKeyPacket} key - Public key
* @returns {Promise<Boolean>}
* @async
*/

4
src/packet/public_subkey.js
View File

@ -28,8 +28,8 @@ import enums from '../enums';
*/
class PublicSubkeyPacket extends PublicKeyPacket {
/**
* @param {Date} [date] - creation date
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Date} [date] - Creation date
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(date, config) {
super(date, config);

14
src/packet/secret_key.js
View File

@ -30,8 +30,8 @@ import defaultConfig from '../config';
*/
class SecretKeyPacket extends PublicKeyPacket {
/**
* @param {Date} [date] - creation date
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Date} [date] - Creation date
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(date = new Date(), config = defaultConfig) {
super(date, config);
@ -80,7 +80,7 @@ class SecretKeyPacket extends PublicKeyPacket {
/**
* Internal parser for private keys as specified in
* {@link https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-04#section-5.5.3|RFC4880bis-04 section 5.5.3}
* @param {String} bytes Input string to read the packet from
* @param {String} bytes - Input string to read the packet from
*/
read(bytes) {
// - A Public-Key or Public-Subkey packet, as described above.
@ -166,7 +166,7 @@ class SecretKeyPacket extends PublicKeyPacket {
/**
* Creates an OpenPGP key packet for the given key.
* @returns {Uint8Array} A string of bytes containing the secret key OpenPGP packet
* @returns {Uint8Array} A string of bytes containing the secret key OpenPGP packet.
*/
write() {
const arr = [this.writePublicKey()];
@ -242,7 +242,7 @@ class SecretKeyPacket extends PublicKeyPacket {
/**
* Remove private key material, converting the key to a dummy one.
* The resulting key cannot be used for signing/decrypting but can still verify signatures.
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
makeDummy(config = defaultConfig) {
if (this.isDummy()) {
@ -267,7 +267,7 @@ class SecretKeyPacket extends PublicKeyPacket {
* and the passphrase is empty or undefined, the key will be set as not encrypted.
* This can be used to remove passphrase protection after calling decrypt().
* @param {String} passphrase
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if encryption was not successful
* @async
*/
@ -315,7 +315,7 @@ class SecretKeyPacket extends PublicKeyPacket {
* Decrypts the private key params which are needed to use the key.
* {@link SecretKeyPacket.isDecrypted} should be false, as
* otherwise calls to this function will throw an error.
* @param {String} passphrase The passphrase for this private key as string
* @param {String} passphrase - The passphrase for this private key as string
* @throws {Error} if decryption was not successful
* @async
*/

4
src/packet/secret_subkey.js
View File

@ -26,8 +26,8 @@ import defaultConfig from '../config';
*/
class SecretSubkeyPacket extends SecretKeyPacket {
/**
* @param {Date} [date] - creation date
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @param {Date} [date] - Creation date
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(date = new Date(), config = defaultConfig) {
super(date, config);

42
src/packet/signature.js
View File

@ -33,7 +33,7 @@ import defaultConfig from '../config';
*/
class SignaturePacket {
/**
* @param {Date} date the creation date of the signature
* @param {Date} date - The creation date of the signature
*/
constructor(date = new Date()) {
this.tag = enums.packet.signature;
@ -88,9 +88,9 @@ class SignaturePacket {
/**
* parsing function for a signature packet (tag 2).
* @param {String} bytes payload of a tag 2 packet
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @returns {SignaturePacket} object representation
* @param {String} bytes - Payload of a tag 2 packet
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {SignaturePacket} Object representation.
*/
read(bytes, config = defaultConfig) {
let i = 0;
@ -148,10 +148,10 @@ class SignaturePacket {
/**
* Signs provided data. This needs to be done prior to serialization.
* @param {SecretKeyPacket} key private key used to sign the message.
* @param {Object} data Contains packets to be signed.
* @param {Boolean} detached (optional) whether to create a detached signature
* @param {Boolean} streaming (optional) whether to process data as a stream
* @param {SecretKeyPacket} key - Private key used to sign the message.
* @param {Object} data - Contains packets to be signed.
* @param {Boolean} [detached] - Whether to create a detached signature
* @param {Boolean} [streaming] - Whether to process data as a stream
* @throws {Error} if signing failed
* @async
*/
@ -196,7 +196,7 @@ class SignaturePacket {
/**
* Creates Uint8Array of bytes of all subpacket data except Issuer and Embedded Signature subpackets
* @returns {Uint8Array} subpacket data
* @returns {Uint8Array} Subpacket data.
*/
write_hashed_sub_packets() {
const sub = enums.signatureSubpacket;
@ -299,7 +299,7 @@ class SignaturePacket {
/**
* Creates Uint8Array of bytes of Issuer and Embedded Signature subpackets
* @returns {Uint8Array} subpacket data
* @returns {Uint8Array} Subpacket data.
*/
write_unhashed_sub_packets() {
const sub = enums.signatureSubpacket;
@ -658,11 +658,11 @@ class SignaturePacket {
* verifies the signature packet. Note: not all signature types are implemented
* @param {PublicSubkeyPacket|PublicKeyPacket|
* SecretSubkeyPacket|SecretKeyPacket} key the public key to verify the signature
* @param {module:enums.signature} signatureType expected signature type
* @param {String|Object} data data which on the signature applies
* @param {Boolean} detached (optional) whether to verify a detached signature
* @param {Boolean} streaming (optional) whether to process data as a stream
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {module:enums.signature} signatureType - Expected signature type
* @param {String|Object} data - Data which on the signature applies
* @param {Boolean} [detached] - Whether to verify a detached signature
* @param {Boolean} [streaming] - Whether to process data as a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if signature validation failed
* @async
*/
@ -713,8 +713,8 @@ class SignaturePacket {
/**
* Verifies signature expiration date
* @param {Date} date (optional) use the given date for verification instead of the current time
* @returns {Boolean} true if expired
* @param {Date} [date] - Use the given date for verification instead of the current time
* @returns {Boolean} True if expired.
*/
isExpired(date = new Date()) {
const normDate = util.normalizeDate(date);
@ -727,7 +727,7 @@ class SignaturePacket {
/**
* Returns the expiration time of the signature or Infinity if signature does not expire
* @returns {Date} expiration time
* @returns {Date} Expiration time.
*/
getExpirationTime() {
return !this.signatureNeverExpires ? new Date(this.created.getTime() + this.signatureExpirationTime * 1000) : Infinity;
@ -738,9 +738,9 @@ class SignaturePacket {
* Creates a string representation of a sub signature packet
* @see {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.1|RFC4880 5.2.3.1}
* @see {@link https://tools.ietf.org/html/rfc4880#section-5.2.3.2|RFC4880 5.2.3.2}
* @param {Integer} type subpacket signature type.
* @param {String} data data to be included
* @returns {String} a string-representation of a sub signature packet
* @param {Integer} type - Subpacket signature type.
* @param {String} data - Data to be included
* @returns {String} A string-representation of a sub signature packet.
* @private
*/
function write_sub_packet(type, data) {

16
src/packet/sym_encrypted_integrity_protected_data.js
View File

@ -76,10 +76,10 @@ class SymEncryptedIntegrityProtectedDataPacket {
/**
* 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
* @param {Boolean} streaming Whether to set this.encrypted to a stream
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @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
* @param {Boolean} streaming - Whether to set this.encrypted to a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Boolean>}
* @async
*/
@ -99,10 +99,10 @@ class SymEncryptedIntegrityProtectedDataPacket {
/**
* 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
* @param {Boolean} streaming Whether to read this.encrypted as a stream
* @param {Object} [config] - full configuration, defaults to openpgp.config
* @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
* @param {Boolean} streaming - Whether to read this.encrypted as a stream
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {Promise<Boolean>}
* @async
*/

12
src/packet/sym_encrypted_session_key.js
View File

@ -36,7 +36,7 @@ import util from '../util';
*/
class SymEncryptedSessionKeyPacket {
/**
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(config = defaultConfig) {
this.tag = enums.packet.symEncryptedSessionKey;
@ -53,7 +53,7 @@ class SymEncryptedSessionKeyPacket {
/**
* Parsing function for a symmetric encrypted session key packet (tag 3).
*
* @param {Uint8Array} bytes Payload of a tag 3 packet
* @param {Uint8Array} bytes - Payload of a tag 3 packet
*/
read(bytes) {
let offset = 0;
@ -94,7 +94,7 @@ class SymEncryptedSessionKeyPacket {
/**
* Create a binary representation of a tag 3 packet
*
* @returns {Uint8Array} The Uint8Array representation
* @returns {Uint8Array} The Uint8Array representation.
*/
write() {
const algo = this.encrypted === null ?
@ -118,7 +118,7 @@ class SymEncryptedSessionKeyPacket {
/**
* Decrypts the session key
* @param {String} passphrase The passphrase in string form
* @param {String} passphrase - The passphrase in string form
* @throws {Error} if decryption was not successful
* @async
*/
@ -147,8 +147,8 @@ class SymEncryptedSessionKeyPacket {
/**
* Encrypts the session key
* @param {String} passphrase The passphrase in string form
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {String} passphrase - The passphrase in string form
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if encryption was not successful
* @async
*/

12
src/packet/symmetrically_encrypted_data.js
View File

@ -66,9 +66,9 @@ class SymmetricallyEncryptedDataPacket {
/**
* Decrypt the symmetrically-encrypted packet data
* See {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC 4880 9.2} for algorithms.
* @param {module:enums.symmetric} sessionKeyAlgorithm Symmetric key algorithm to use
* @param {Uint8Array} key The key of cipher blocksize length to be used
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {module:enums.symmetric} sessionKeyAlgorithm - Symmetric key algorithm to use
* @param {Uint8Array} key - The key of cipher blocksize length to be used
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if decryption was not successful
* @async
@ -96,9 +96,9 @@ class SymmetricallyEncryptedDataPacket {
/**
* Encrypt the symmetrically-encrypted packet data
* See {@link https://tools.ietf.org/html/rfc4880#section-9.2|RFC 4880 9.2} for algorithms.
* @param {module:enums.symmetric} sessionKeyAlgorithm Symmetric key algorithm to use
* @param {Uint8Array} key The key of cipher blocksize length to be used
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {module:enums.symmetric} sessionKeyAlgorithm - Symmetric key algorithm to use
* @param {Uint8Array} key - The key of cipher blocksize length to be used
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @throws {Error} if encryption was not successful
* @async
*/

2
src/packet/trust.js
View File

@ -25,7 +25,7 @@ class TrustPacket {
/**
* Parsing function for a trust packet (tag 12).
* Currently not implemented as we ignore trust packets
* @param {String} byptes payload of a tag 12 packet
* @param {String} byptes - Payload of a tag 12 packet
*/
read() {} // TODO
}

8
src/packet/user_attribute.js
View File

@ -44,7 +44,7 @@ class UserAttributePacket {
/**
* parsing function for a user attribute packet (tag 17).
* @param {Uint8Array} input payload of a tag 17 packet
* @param {Uint8Array} input - Payload of a tag 17 packet
*/
read(bytes) {
let i = 0;
@ -59,7 +59,7 @@ class UserAttributePacket {
/**
* Creates a binary representation of the user attribute packet
* @returns {Uint8Array} string representation
* @returns {Uint8Array} String representation.
*/
write() {
const arr = [];
@ -72,8 +72,8 @@ class UserAttributePacket {
/**
* Compare for equality
* @param {UserAttributePacket} usrAttr
* @returns {Boolean} true if equal
* @param {UserAttributePacket} usrAttr
* @returns {Boolean} True if equal.
*/
equals(usrAttr) {
if (!usrAttr || !(usrAttr instanceof UserAttributePacket)) {

6
src/packet/userid.js
View File

@ -46,7 +46,7 @@ class UserIDPacket {
/**
* Create UserIDPacket instance from object
* @param {Object} userId object specifying userId name, email and comment
* @param {Object} userId - Object specifying userId name, email and comment
* @returns {UserIDPacket}
* @static
*/
@ -69,7 +69,7 @@ class UserIDPacket {
/**
* Parsing function for a user id packet (tag 13).
* @param {Uint8Array} input payload of a tag 13 packet
* @param {Uint8Array} input - Payload of a tag 13 packet
*/
read(bytes, config = defaultConfig) {
const userid = util.decodeUtf8(bytes);
@ -87,7 +87,7 @@ class UserIDPacket {
/**
* Creates a binary representation of the user id packet
* @returns {Uint8Array} binary representation
* @returns {Uint8Array} Binary representation.
*/
write() {
return util.encodeUtf8(this.userid);

17
src/signature.js
View File

@ -25,7 +25,7 @@ import defaultConfig from './config';
*/
export class Signature {
/**
* @param {PacketList} packetlist The signature packets
* @param {PacketList} packetlist - The signature packets
*/
constructor(packetlist) {
this.packets = packetlist || new PacketList();
@ -33,7 +33,7 @@ export class Signature {
/**
* Returns binary encoded signature
* @returns {ReadableStream<Uint8Array>} binary signature
* @returns {ReadableStream<Uint8Array>} Binary signature.
*/
write() {
return this.packets.write();
@ -41,8 +41,8 @@ export class Signature {
/**
* Returns ASCII armored text of signature
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @returns {ReadableStream<String>} ASCII armor
* @param {Object} [config] - Full configuration, defaults to openpgp.config
* @returns {ReadableStream<String>} ASCII armor.
*/
armor(config = defaultConfig) {
return armor(enums.armor.signature, this.write(), undefined, undefined, undefined, config);
@ -51,10 +51,11 @@ export class Signature {
/**
* reads an (optionally armored) OpenPGP signature and returns a signature object
* @param {String | ReadableStream<String>} armoredSignature armored signature to be parsed
* @param {Uint8Array | ReadableStream<Uint8Array>} binarySignature binary signature to be parsed
* @param {Object} config (optional) custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Signature} new signature object
* @param {Object} options
* @param {String | ReadableStream<String>} [options.armoredSignature] - Armored signature to be parsed
* @param {Uint8Array | ReadableStream<Uint8Array>} [options.binarySignature] - Binary signature to be parsed
* @param {Object} [options.config] - Custom configuration settings to overwrite those in [config]{@link module:config}
* @returns {Signature} New signature object.
* @async
* @static
*/

4
src/type/ecdh_symkey.js
View File

@ -38,8 +38,8 @@ class ECDHSymmetricKey {
/**
* Read an ECDHSymmetricKey from an Uint8Array
* @param {Uint8Array} input Where to read the encoded symmetric key from
* @returns {Number} Number of read bytes
* @param {Uint8Array} input - Where to read the encoded symmetric key from
* @returns {Number} Number of read bytes.
*/
read(input) {
if (input.length >= 1) {

8
src/type/kdf_params.js
View File

@ -29,8 +29,8 @@
class KDFParams {
/**
* @param {enums.hash} hash Hash algorithm
* @param {enums.symmetric} cipher Symmetric algorithm
* @param {enums.hash} hash - Hash algorithm
* @param {enums.symmetric} cipher - Symmetric algorithm
*/
constructor(data) {
if (data) {
@ -45,8 +45,8 @@ class KDFParams {
/**
* Read KDFParams from an Uint8Array
* @param {Uint8Array} input Where to read the KDFParams from
* @returns {Number} Number of read bytes
* @param {Uint8Array} input - Where to read the KDFParams from
* @returns {Number} Number of read bytes.
*/
read(input) {
if (input.length < 4 || input[0] !== 3 || input[1] !== 1) {

12
src/type/keyid.js
View File

@ -38,7 +38,7 @@ class Keyid {
/**
* Parsing method for a key id
* @param {Uint8Array} bytes Input to read the key id from
* @param {Uint8Array} bytes - Input to read the key id from
*/
read(bytes) {
this.bytes = util.uint8ArrayToStr(bytes.subarray(0, 8));
@ -46,7 +46,7 @@ class Keyid {
/**
* Serializes the Key ID
* @returns {Uint8Array} Key ID as a Uint8Array
* @returns {Uint8Array} Key ID as a Uint8Array.
*/
write() {
return util.strToUint8Array(this.bytes);
@ -54,7 +54,7 @@ class Keyid {
/**
* Returns the Key ID represented as a hexadecimal string
* @returns {String} Key ID as a hexadecimal string
* @returns {String} Key ID as a hexadecimal string.
*/
toHex() {
return util.strToHex(this.bytes);
@ -63,7 +63,7 @@ class Keyid {
/**
* Checks equality of Key ID's
* @param {Keyid} keyid
* @param {Boolean} matchWildcard Indicates whether to check if either keyid is a wildcard
* @param {Boolean} matchWildcard - Indicates whether to check if either keyid is a wildcard
*/
equals(keyid, matchWildcard = false) {
return (matchWildcard && (keyid.isWildcard() || this.isWildcard())) || this.bytes === keyid.bytes;
@ -71,7 +71,7 @@ class Keyid {
/**
* Checks to see if the Key ID is unset
* @returns {Boolean} true if the Key ID is null
* @returns {Boolean} True if the Key ID is null.
*/
isNull() {
return this.bytes === '';
@ -79,7 +79,7 @@ class Keyid {
/**
* Checks to see if the Key ID is a "wildcard" Key ID (all zeros)
* @returns {Boolean} true if this is a wildcard Key ID
* @returns {Boolean} True if this is a wildcard Key ID.
*/
isWildcard() {
return /^0+$/.test(this.toHex());

10
src/type/oid.js
View File

@ -57,8 +57,8 @@ class OID {
/**
* Method to read an OID object
* @param {Uint8Array} input Where to read the OID from
* @returns {Number} Number of read bytes
* @param {Uint8Array} input - Where to read the OID from
* @returns {Number} Number of read bytes.
*/
read(input) {
if (input.length >= 1) {
@ -73,7 +73,7 @@ class OID {
/**
* Serialize an OID object
* @returns {Uint8Array} Array with the serialized value the OID
* @returns {Uint8Array} Array with the serialized value the OID.
*/
write() {
return util.concatUint8Array([new Uint8Array([this.oid.length]), this.oid]);
@ -81,7 +81,7 @@ class OID {
/**
* Serialize an OID object as a hex string
* @returns {string} String with the hex value of the OID
* @returns {string} String with the hex value of the OID.
*/
toHex() {
return util.uint8ArrayToHex(this.oid);
@ -89,7 +89,7 @@ class OID {
/**
* If a known curve object identifier, return the canonical name of the curve
* @returns {string} String with the canonical name of the curve
* @returns {string} String with the canonical name of the curve.
*/
getName() {
const hex = this.toHex();

12
src/type/s2k.js
View File

@ -35,7 +35,7 @@ import util from '../util.js';
class S2K {
/**
* @param {Object} config (optional) full configuration, defaults to openpgp.config
* @param {Object} [config] - Full configuration, defaults to openpgp.config
*/
constructor(config = defaultConfig) {
/** @type {module:enums.hash} */
@ -59,8 +59,8 @@ class S2K {
/**
* Parsing function for a string-to-key specifier ({@link https://tools.ietf.org/html/rfc4880#section-3.7|RFC 4880 3.7}).
* @param {String} bytes Payload of string-to-key specifier
* @returns {Integer} Actual length of the object
* @param {String} bytes - Payload of string-to-key specifier
* @returns {Integer} Actual length of the object.
*/
read(bytes) {
let i = 0;
@ -111,7 +111,7 @@ class S2K {
/**
* Serializes s2k information
* @returns {Uint8Array} binary representation of s2k
* @returns {Uint8Array} Binary representation of s2k.
*/
write() {
if (this.type === 'gnu-dummy') {
@ -142,8 +142,8 @@ class S2K {
/**
* Produces a key using the specified passphrase and the defined
* hashAlgorithm
* @param {String} passphrase Passphrase containing user input
* @returns {Uint8Array} Produced key with a length corresponding to
* @param {String} passphrase - Passphrase containing user input
* @returns {Uint8Array} Produced key with a length corresponding to.
* hashAlgorithm hash length
*/
async produce_key(passphrase, numBytes) {

92
src/util.js
View File

@ -55,7 +55,7 @@ const util = {
/**
* Convert MessagePorts back to ReadableStreams
* @param {Object} obj
* @param {Object} obj
* @returns {Object}
*/
restoreStreams: function(obj, streaming) {
@ -128,8 +128,8 @@ const util = {
/**
* Create hex string from a binary
* @param {String} str String to convert
* @returns {String} String containing the hexadecimal values
* @param {String} str - String to convert
* @returns {String} String containing the hexadecimal values.
*/
strToHex: function (str) {
if (str === null) {
@ -151,7 +151,7 @@ const util = {
/**
* Create binary string from a hex encoded string
* @param {String} str Hex string to convert
* @param {String} str - Hex string to convert
* @returns {String}
*/
hexToStr: function (hex) {
@ -164,8 +164,8 @@ const util = {
/**
* Read one MPI from bytes in input
* @param {Uint8Array} bytes input data to parse
* @returns {Uint8Array} parsed MPI
* @param {Uint8Array} bytes - Input data to parse
* @returns {Uint8Array} Parsed MPI.
*/
readMPI: function (bytes) {
const bits = (bytes[0] << 8) | bytes[1];
@ -175,9 +175,9 @@ const util = {
/**
* Left-pad Uint8Array to length by adding 0x0 bytes
* @param {Uint8Array} bytes data to pad
* @param {Number} length padded length
* @return {Uint8Array} padded bytes
* @param {Uint8Array} bytes - Data to pad
* @param {Number} length - Padded length
* @returns {Uint8Array} Padded bytes.
*/
leftPad(bytes, length) {
const padded = new Uint8Array(length);
@ -188,8 +188,8 @@ const util = {
/**
* Convert a Uint8Array to an MPI-formatted Uint8Array.
* @param {Uint8Array} bin An array of 8-bit integers to convert
* @returns {Uint8Array} MPI-formatted Uint8Array
* @param {Uint8Array} bin - An array of 8-bit integers to convert
* @returns {Uint8Array} MPI-formatted Uint8Array.
*/
uint8ArrayToMpi: function (bin) {
let i; // index of leading non-zero byte
@ -205,8 +205,8 @@ const util = {
/**
* Convert a hex string to an array of 8-bit integers
* @param {String} hex A hex string to convert
* @returns {Uint8Array} An array of 8-bit integers
* @param {String} hex - A hex string to convert
* @returns {Uint8Array} An array of 8-bit integers.
*/
hexToUint8Array: function (hex) {
const result = new Uint8Array(hex.length >> 1);
@ -218,8 +218,8 @@ const util = {
/**
* Convert an array of 8-bit integers to a hex string
* @param {Uint8Array} bytes Array of 8-bit integers to convert
* @returns {String} Hexadecimal representation of the array
* @param {Uint8Array} bytes - Array of 8-bit integers to convert
* @returns {String} Hexadecimal representation of the array.
*/
uint8ArrayToHex: function (bytes) {
const r = [];
@ -238,8 +238,8 @@ const util = {
/**
* Convert a string to an array of 8-bit integers
* @param {String} str String to convert
* @returns {Uint8Array} An array of 8-bit integers
* @param {String} str - String to convert
* @returns {Uint8Array} An array of 8-bit integers.
*/
strToUint8Array: function (str) {
return stream.transform(str, str => {
@ -257,8 +257,8 @@ const util = {
/**
* Convert an array of 8-bit integers to a string
* @param {Uint8Array} bytes An array of 8-bit integers to convert
* @returns {String} String representation of the array
* @param {Uint8Array} bytes - An array of 8-bit integers to convert
* @returns {String} String representation of the array.
*/
uint8ArrayToStr: function (bytes) {
bytes = new Uint8Array(bytes);
@ -274,8 +274,8 @@ const util = {
/**
* Convert a native javascript string to a Uint8Array of utf8 bytes
* @param {String|ReadableStream} str The string to convert
* @returns {Uint8Array|ReadableStream} A valid squence of utf8 bytes
* @param {String|ReadableStream} str - The string to convert
* @returns {Uint8Array|ReadableStream} A valid squence of utf8 bytes.
*/
encodeUtf8: function (str) {
const encoder = new TextEncoder('utf-8');
@ -288,8 +288,8 @@ const util = {
/**
* Convert a Uint8Array of utf8 bytes to a native javascript string
* @param {Uint8Array|ReadableStream} utf8 A valid squence of utf8 bytes
* @returns {String|ReadableStream} A native javascript string
* @param {Uint8Array|ReadableStream} utf8 - A valid squence of utf8 bytes
* @returns {String|ReadableStream} A native javascript string.
*/
decodeUtf8: function (utf8) {
const decoder = new TextDecoder('utf-8');
@ -303,23 +303,23 @@ const util = {
/**
* Concat a list of Uint8Arrays, Strings or Streams
* The caller must not mix Uint8Arrays with Strings, but may mix Streams with non-Streams.
* @param {Array<Uint8Array|String|ReadableStream>} Array of Uint8Arrays/Strings/Streams to concatenate
* @returns {Uint8Array|String|ReadableStream} Concatenated array
* @param {Array<Uint8Array|String|ReadableStream>} Array - Of Uint8Arrays/Strings/Streams to concatenate
* @returns {Uint8Array|String|ReadableStream} Concatenated array.
*/
concat: stream.concat,
/**
* Concat Uint8Arrays
* @param {Array<Uint8Array>} Array of Uint8Arrays to concatenate
* @returns {Uint8Array} Concatenated array
* @param {Array<Uint8Array>} Array - Of Uint8Arrays to concatenate
* @returns {Uint8Array} Concatenated array.
*/
concatUint8Array: stream.concatUint8Array,
/**
* Check Uint8Array equality
* @param {Uint8Array} array1 first array
* @param {Uint8Array} array2 second array
* @returns {Boolean} equality
* @param {Uint8Array} array1 - First array
* @param {Uint8Array} array2 - Second array
* @returns {Boolean} Equality.
*/
equalsUint8Array: function (array1, array2) {
if (!util.isUint8Array(array1) || !util.isUint8Array(array2)) {
@ -341,8 +341,8 @@ const util = {
/**
* Calculates a 16bit sum of a Uint8Array by adding each character
* codes modulus 65535
* @param {Uint8Array} Uint8Array to create a sum of
* @returns {Uint8Array} 2 bytes containing the sum of all charcodes % 65535
* @param {Uint8Array} Uint8Array - To create a sum of
* @returns {Uint8Array} 2 bytes containing the sum of all charcodes % 65535.
*/
writeChecksum: function (text) {
let s = 0;
@ -355,7 +355,7 @@ const util = {
/**
* Helper function to print a debug message. Debug
* messages are only printed if
* @param {String} str String of the debug message
* @param {String} str - String of the debug message
*/
printDebug: function (str) {
if (debugMode) {
@ -367,7 +367,7 @@ const util = {
* Helper function to print a debug message. Debug
* messages are only printed if
* Different than print_debug because will call Uint8ArrayToHex iff necessary.
* @param {String} str String of the debug message
* @param {String} str - String of the debug message
*/
printDebugHexArrayDump: function (str, arrToHex) {
if (debugMode) {
@ -380,7 +380,7 @@ const util = {
* Helper function to print a debug message. Debug
* messages are only printed if
* Different than print_debug because will call strToHex iff necessary.
* @param {String} str String of the debug message
* @param {String} str - String of the debug message
*/
printDebugHexStrDump: function (str, strToHex) {
if (debugMode) {
@ -392,7 +392,7 @@ const util = {
/**
* Helper function to print a debug error. Debug
* messages are only printed if
* @param {String} str String of the debug message
* @param {String} str - String of the debug message
*/
printDebugError: function (error) {
if (debugMode) {
@ -402,9 +402,9 @@ const util = {
/**
* Read a stream to the end and print it to the console when it's closed.
* @param {String} str String of the debug message
* @param {ReadableStream|Uint8array|String} input Stream to print
* @param {Function} concat Function to concatenate chunks of the stream (defaults to util.concat).
* @param {String} str - String of the debug message
* @param {ReadableStream|Uint8array|String} input - Stream to print
* @param {Function} concat - Function to concatenate chunks of the stream (defaults to util.concat).
*/
printEntireStream: function (str, input, concat) {
stream.readToEnd(stream.clone(input), concat).then(result => {
@ -464,8 +464,8 @@ const util = {
/**
* Shift a Uint8Array to the right by n bits
* @param {Uint8Array} array The array to shift
* @param {Integer} bits Amount of bits to shift (MUST be smaller
* @param {Uint8Array} array - The array to shift
* @param {Integer} bits - Amount of bits to shift (MUST be smaller
* than 8)
* @returns {String} Resulting array.
*/
@ -483,7 +483,7 @@ const util = {
/**
* Get native Web Cryptography api, only the current version of the spec.
* @returns {Object} The SubtleCrypto api or 'undefined'
* @returns {Object} The SubtleCrypto api or 'undefined'.
*/
getWebCrypto: function() {
return typeof globalThis !== 'undefined' && globalThis.crypto && globalThis.crypto.subtle;
@ -513,7 +513,7 @@ const util = {
/**
* Get native Node.js crypto api.
* @returns {Object} The crypto module or 'undefined'
* @returns {Object} The crypto module or 'undefined'.
*/
getNodeCrypto: function() {
return require('crypto');
@ -526,7 +526,7 @@ const util = {
/**
* Get native Node.js Buffer constructor. This should be used since
* Buffer is not available under browserify.
* @returns {Function} The Buffer constructor or 'undefined'
* @returns {Function} The Buffer constructor or 'undefined'.
*/
getNodeBuffer: function() {
return (require('buffer') || {}).Buffer;
@ -654,8 +654,8 @@ const util = {
* Encode input buffer using Z-Base32 encoding.
* See: https://tools.ietf.org/html/rfc6189#section-5.1.6
*
* @param {Uint8Array} data The binary data to encode
* @returns {String} Binary data encoded using Z-Base32
* @param {Uint8Array} data - The binary data to encode
* @returns {String} Binary data encoded using Z-Base32.
*/
encodeZBase32: function(data) {
if (data.length === 0) {