diff --git a/src/crypto/public_key/elliptic/ecdh.js b/src/crypto/public_key/elliptic/ecdh.js index ccbfa30a..db8195bb 100644 --- a/src/crypto/public_key/elliptic/ecdh.js +++ b/src/crypto/public_key/elliptic/ecdh.js @@ -67,7 +67,7 @@ function kdf(hash_algo, X, length, param) { * @param {module:type/mpi} m Value derived from session key (RFC 6637) * @param {Uint8Array} Q Recipient public key * @param {String} fingerprint Recipient fingerprint - * @returns {{V: BN, C: BN}} Returns ephemeral key and encoded session key + * @returns {Promise<{V: BN, C: BN}>} Returns ephemeral key and encoded session key * @async */ async function encrypt(oid, cipher_algo, hash_algo, m, Q, fingerprint) { @@ -95,7 +95,7 @@ async function encrypt(oid, cipher_algo, hash_algo, m, Q, fingerprint) { * @param {Uint8Array} C Encrypted and wrapped value derived from session key * @param {Uint8Array} d Recipient private key * @param {String} fingerprint Recipient fingerprint - * @returns {Uint8Array} Value derived from session + * @returns {Promise} Value derived from session * @async */ async function decrypt(oid, cipher_algo, hash_algo, V, C, d, fingerprint) { diff --git a/src/encoding/armor.js b/src/encoding/armor.js index fab22e9a..53fdd49a 100644 --- a/src/encoding/armor.js +++ b/src/encoding/armor.js @@ -196,7 +196,7 @@ function verifyHeaders(headers) { * DeArmor an OpenPGP armored message; verify the checksum and return * the encoded bytes * @param {String} text OpenPGP armored message - * @returns {Object} An object with attribute "text" containing the message text, + * @returns {Promise} 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 * @static diff --git a/src/key.js b/src/key.js index 0a428a2d..90e8e92b 100644 --- a/src/key.js +++ b/src/key.js @@ -37,6 +37,11 @@ import util from './util'; * @classdesc Class that represents an OpenPGP key. Must contain a primary key. * Can contain additional subkeys, signatures, user ids, user attributes. * @param {module:packet.List} packetlist The packets that form this key + * @borrows module:packet.PublicKey#getKeyId as Key#getKeyId + * @borrows module:packet.PublicKey#getFingerprint as Key#getFingerprint + * @borrows module:packet.PublicKey#getAlgorithmInfo as Key#getAlgorithmInfo + * @borrows module:packet.PublicKey#getCreationTime as Key#getCreationTime + * @borrows module:packet.PublicKey#isDecrypted as Key#isDecrypted */ export function Key(packetlist) { if (!(this instanceof Key)) { @@ -152,10 +157,10 @@ Key.prototype.toPacketlist = function() { }; /** - * Returns packetlist containing all public or private subkey packets matching keyId; - * If keyId is not present, returns all subkey packets. + * Returns an array containing all public or private subkeys matching keyId; + * If keyId is not present, returns all subkeys. * @param {type/keyid} keyId - * @returns {Array} + * @returns {Array} */ Key.prototype.getSubkeys = function(keyId=null) { const subKeys = []; @@ -168,10 +173,10 @@ Key.prototype.getSubkeys = function(keyId=null) { }; /** - * Returns a packetlist containing all public or private key packets matching keyId. - * If keyId is not present, returns all key packets starting with the primary 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 - * @returns {Array} + * @returns {Array} */ Key.prototype.getKeys = function(keyId=null) { const keys = []; @@ -182,7 +187,7 @@ Key.prototype.getKeys = function(keyId=null) { }; /** - * Returns key IDs of all key packets + * Returns key IDs of all keys * @returns {Array} */ Key.prototype.getKeyIds = function() { @@ -287,7 +292,7 @@ function isValidSigningKeyPacket(keyPacket, signature, date=new Date()) { * @param {module:type/keyid} keyId, optional * @param {Date} date use the given date for verification instead of the current time * @param {Object} userId, optional user ID - * @returns {Promise} key or null if no signing key has been found + * @returns {Promise} key or null if no signing key has been found * @async */ Key.prototype.getSigningKey = async function (keyId=null, date=new Date(), userId={}) { @@ -330,7 +335,7 @@ function isValidEncryptionKeyPacket(keyPacket, signature, date=new Date()) { * @param {module:type/keyid} keyId, optional * @param {Date} date, optional * @param {String} userId, optional - * @returns {Promise} key or null if no encryption key has been found + * @returns {Promise} key or null if no encryption key has been found * @async */ Key.prototype.getEncryptionKey = async function(keyId, date=new Date(), userId={}) { @@ -553,6 +558,8 @@ Key.prototype.getPrimaryUser = async function(date=new Date(), userId={}) { * If the specified key is a private key and the destination key is public, * the destination key is transformed to a private key. * @param {module:key.Key} key Source key to merge + * @returns {Promise} + * @async */ Key.prototype.update = async function(key) { if (await key.verifyPrimaryKey() === enums.keyStatus.invalid) { @@ -644,7 +651,8 @@ async function mergeSignatures(source, dest, attr, checkFn) { * @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 - * @return {module:key~Key} new key with revocation signature + * @returns {Promise} new key with revocation signature + * @async */ Key.prototype.revoke = async function({ flag: reasonForRevocationFlag=enums.reasonForRevocation.no_reason, @@ -666,7 +674,7 @@ Key.prototype.revoke = async function({ /** * Get revocation certificate from a revoked key. * (To get a revocation certificate for an unrevoked key, call revoke() first.) - * @return {String} armored revocation certificate + * @returns {String} armored revocation certificate */ Key.prototype.getRevocationCertificate = function() { if (this.revocationSignatures.length) { @@ -681,7 +689,8 @@ Key.prototype.getRevocationCertificate = function() { * 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 - * @return {module:key~Key} new revoked key + * @returns {Promise} new revoked key + * @async */ Key.prototype.applyRevocationCertificate = async function(revocationCertificate) { const input = await armor.decode(revocationCertificate); @@ -880,7 +889,7 @@ User.prototype.isRevoked = async function(primaryKey, certificate, key, date=new * @param {Object} signatureProperties (optional) properties to write on the signature packet before signing * @param {Date} date (optional) override the creationtime of the signature * @param {Object} userId (optional) user ID - * @return {module:packet/signature} signature packet + * @returns {module:packet/signature} signature packet */ export async function createSignaturePacket(dataToSign, privateKey, signingKeyPacket, signatureProperties, date, userId) { if (!signingKeyPacket.isDecrypted()) { @@ -991,6 +1000,8 @@ User.prototype.verify = async function(primaryKey) { * @param {module:key.User} user Source user to merge * @param {module:packet.SecretKey| * module:packet.SecretSubkey} primaryKey primary key used for validation + * @returns {Promise} + * @async */ User.prototype.update = async function(user, primaryKey) { const dataToVerify = { @@ -1013,6 +1024,11 @@ User.prototype.update = async function(user, primaryKey) { /** * @class * @classdesc Class that represents a subkey packet and the relevant signatures. + * @borrows module:packet.PublicSubkey#getKeyId as SubKey#getKeyId + * @borrows module:packet.PublicSubkey#getFingerprint as SubKey#getFingerprint + * @borrows module:packet.PublicSubkey#getAlgorithmInfo as SubKey#getAlgorithmInfo + * @borrows module:packet.PublicSubkey#getCreationTime as SubKey#getCreationTime + * @borrows module:packet.PublicSubkey#isDecrypted as SubKey#isDecrypted */ function SubKey(subKeyPacket) { if (!(this instanceof SubKey)) { @@ -1100,9 +1116,11 @@ SubKey.prototype.getExpirationTime = function(date=new Date()) { /** * Update subkey with new components from specified subkey - * @param {module:key.SubKey} subKey Source subkey to merge + * @param {module:key~SubKey} subKey Source subkey to merge * @param {module:packet.SecretKey| module:packet.SecretSubkey} primaryKey primary key used for validation + * @returns {Promise} + * @async */ SubKey.prototype.update = async function(subKey, primaryKey) { if (await subKey.verify(primaryKey) === enums.keyStatus.invalid) { @@ -1146,7 +1164,8 @@ SubKey.prototype.update = async function(subKey, primaryKey) { * @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 - * @return {module:key~SubKey} new subkey with revocation signature + * @returns {Promise} new subkey with revocation signature + * @async */ SubKey.prototype.revoke = async function(primaryKey, { flag: reasonForRevocationFlag=enums.reasonForRevocation.no_reason, @@ -1163,6 +1182,8 @@ SubKey.prototype.revoke = async function(primaryKey, { return subKey; }; +/** + */ ['getKeyId', 'getFingerprint', 'getAlgorithmInfo', 'getCreationTime', 'isDecrypted'].forEach(name => { Key.prototype[name] = SubKey.prototype[name] = @@ -1174,8 +1195,9 @@ SubKey.prototype.revoke = async function(primaryKey, { /** * Reads an unarmored OpenPGP key list and returns one or multiple key objects * @param {Uint8Array} data to be parsed - * @returns {{keys: Array, - * err: (Array|null)}} result object with key and error arrays + * @returns {Promise<{keys: Array, + * err: (Array|null)}>} result object with key and error arrays + * @async * @static */ export async function read(data) { @@ -1208,8 +1230,8 @@ export async function read(data) { /** * Reads an OpenPGP armored text and returns one or multiple key objects * @param {String | ReadableStream} armoredText text to be parsed - * @returns {{keys: Array, - * err: (Array|null)}} result object with key and error arrays + * @returns {Promise<{keys: Array, + * err: (Array|null)}>} result object with key and error arrays * @async * @static */ diff --git a/src/message.js b/src/message.js index 3156bb93..3a727f66 100644 --- a/src/message.js +++ b/src/message.js @@ -679,7 +679,7 @@ Message.prototype.armor = function() { /** * reads an OpenPGP armored message and returns a message object * @param {String | ReadableStream} armoredText text to be parsed - * @returns {module:message.Message} new message object + * @returns {Promise} new message object * @async * @static */ @@ -698,7 +698,7 @@ export async function readArmored(armoredText) { * reads an OpenPGP message as byte array and returns a message object * @param {Uint8Array | ReadableStream} input binary message * @param {Boolean} fromStream whether the message was created from a Stream - * @returns {module:message.Message} new message object + * @returns {Promise} new message object * @async * @static */ diff --git a/src/openpgp.js b/src/openpgp.js index ba45df3d..e9540a55 100644 --- a/src/openpgp.js +++ b/src/openpgp.js @@ -182,7 +182,7 @@ export function reformatKey({privateKey, userIds=[], passphrase="", keyExpiratio * @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 - * @return {Promise} The revoked key object in the form: + * @returns {Promise} 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) * @static @@ -281,7 +281,7 @@ export function encryptKey({ privateKey, passphrase }) { * @param {Object} sessionKey (optional) session key in the form: { data:Uint8Array, algorithm:String } * @param {module:enums.compression} compression (optional) which compression algorithm to compress the message with, defaults to what is specified in config * @param {Boolean} armor (optional) if the return values should be ascii armored or the message/signature objects - * @param {'web'|'node'|false} streaming (optional) whether to return data as a ReadableStream. Defaults to true if data is a Stream. + * @param {'web'|'node'|false} streaming (optional) whether to return data as a stream. Defaults to the type of stream `message` was created from, if any. * @param {Boolean} detached (optional) if the signature should be detached (if true, signature will be added to returned object) * @param {Signature} signature (optional) a detached signature to add to the encrypted message * @param {Boolean} returnSessionKey (optional) if the unencrypted session key should be added to returned object @@ -289,9 +289,15 @@ export function encryptKey({ privateKey, passphrase }) { * @param {Date} date (optional) override the creation date of the message signature * @param {Object} fromUserId (optional) user ID to sign with, e.g. { name:'Steve Sender', email:'steve@openpgp.org' } * @param {Object} toUserId (optional) user ID to encrypt for, e.g. { name:'Robert Receiver', email:'robert@openpgp.org' } - * @returns {Promise} encrypted (and optionally signed message) in the form: - * {data: ASCII armored message if 'armor' is true, - * message: full Message object if 'armor' is false, signature: detached signature if 'detached' is true} + * @returns {Promise} Object containing encrypted (and optionally signed) message in the form: + * + * { + * data: String|ReadableStream|NodeStream, (if `armor` was true, the default) + * message: Message, (if `armor` was false) + * signature: String|ReadableStream|NodeStream, (if `detached` was true and `armor` was true) + * signature: Signature (if `detached` was true and `armor` was false) + * sessionKey: { data, algorithm, aeadAlgorithm } (if `returnSessionKey` was true) + * } * @async * @static */ @@ -339,11 +345,23 @@ export function encrypt({ message, publicKeys, privateKeys, passwords, sessionKe * @param {Object|Array} sessionKeys (optional) session keys in the form: { data:Uint8Array, algorithm:String } * @param {Key|Array} publicKeys (optional) array of public keys or single key, to verify signatures * @param {String} format (optional) return data format either as 'utf8' or 'binary' - * @param {'web'|'node'|false} streaming (optional) whether to return data as a ReadableStream. Defaults to true if message was created from a Stream. + * @param {'web'|'node'|false} streaming (optional) whether to return data as a stream. Defaults to the type of stream `message` was created from, if any. * @param {Signature} signature (optional) detached signature for verification * @param {Date} date (optional) use the given date for verification instead of the current time - * @returns {Promise} decrypted and verified message in the form: - * { data:Uint8Array|String, filename:String, signatures:[{ keyid:String, valid:Boolean }] } + * @returns {Promise} Object containing decrypted and verified message in the form: + * + * { + * data: String|ReadableStream|NodeStream, (if format was 'utf8', the default) + * data: Uint8Array|ReadableStream|NodeStream, (if format was 'binary') + * filename: String, + * signatures: [ + * { + * keyid: module:type/keyid, + * verified: Promise, + * valid: Boolean (if streaming was false) + * }, ... + * ] + * } * @async * @static */ @@ -380,16 +398,26 @@ export function decrypt({ message, privateKeys, passwords, sessionKeys, publicKe /** * Signs a cleartext message. - * @param {CleartextMessage | Message} message (cleartext) message to be signed - * @param {Key|Array} privateKeys array of keys or single key with decrypted secret key data to sign cleartext - * @param {Boolean} armor (optional) if the return value should be ascii armored or the message object - * @param {'web'|'node'|false} streaming (optional) whether to return data as a ReadableStream. Defaults to true if data is a Stream. - * @param {Boolean} detached (optional) if the return value should contain a detached signature - * @param {Date} date (optional) override the creation date of the signature - * @param {Object} fromUserId (optional) user ID to sign with, e.g. { name:'Steve Sender', email:'steve@openpgp.org' } - * @returns {Promise} signed cleartext in the form: - * {data: ASCII armored message if 'armor' is true, - * message: full Message object if 'armor' is false, signature: detached signature if 'detached' is true} + * @param {CleartextMessage|Message} message (cleartext) message to be signed + * @param {Key|Array} privateKeys array of keys or single key with decrypted secret key data to sign cleartext + * @param {Boolean} armor (optional) if the return value should be ascii armored or the message object + * @param {'web'|'node'|false} streaming (optional) whether to return data as a stream. Defaults to the type of stream `message` was created from, if any. + * @param {Boolean} detached (optional) if the return value should contain a detached signature + * @param {Date} date (optional) override the creation date of the signature + * @param {Object} fromUserId (optional) user ID to sign with, e.g. { name:'Steve Sender', email:'steve@openpgp.org' } + * @returns {Promise} Object containing signed message in the form: + * + * { + * data: String|ReadableStream|NodeStream, (if `armor` was true, the default) + * message: Message (if `armor` was false) + * } + * + * Or, if `detached` was true: + * + * { + * signature: String|ReadableStream|NodeStream, (if `armor` was true, the default) + * signature: Signature (if `armor` was false) + * } * @async * @static */ @@ -422,13 +450,24 @@ export function sign({ message, privateKeys, armor=true, streaming=message&&mess /** * Verifies signatures of cleartext signed message - * @param {Key|Array} publicKeys array of publicKeys or single key, to verify signatures - * @param {CleartextMessage} message cleartext message object with signatures - * @param {'web'|'node'|false} streaming (optional) whether to return data as a ReadableStream. Defaults to true if message was created from a Stream. - * @param {Signature} signature (optional) detached signature for verification - * @param {Date} date (optional) use the given date for verification instead of the current time - * @returns {Promise} cleartext with status of verified signatures in the form of: - * { data:String, signatures: [{ keyid:String, valid:Boolean }] } + * @param {Key|Array} publicKeys array of publicKeys or single key, to verify signatures + * @param {CleartextMessage|Message} message (cleartext) message object with signatures + * @param {'web'|'node'|false} streaming (optional) whether to return data as a stream. Defaults to the type of stream `message` was created from, if any. + * @param {Signature} signature (optional) detached signature for verification + * @param {Date} date (optional) use the given date for verification instead of the current time + * @returns {Promise} Object containing verified message in the form: + * + * { + * data: String|ReadableStream|NodeStream, (if `message` was a CleartextMessage) + * data: Uint8Array|ReadableStream|NodeStream, (if `message` was a Message) + * signatures: [ + * { + * keyid: module:type/keyid, + * verified: Promise, + * valid: Boolean (if `streaming` was false) + * }, ... + * ] + * } * @async * @static */ diff --git a/src/packet/public_key.js b/src/packet/public_key.js index 927f7e04..87d9c219 100644 --- a/src/packet/public_key.js +++ b/src/packet/public_key.js @@ -233,7 +233,7 @@ PublicKey.prototype.getFingerprint = function () { /** * Returns algorithm information - * @returns {Promise} An object of the form {algorithm: String, bits:int, curve:String} + * @returns {Object} An object of the form {algorithm: String, bits:int, curve:String} */ PublicKey.prototype.getAlgorithmInfo = function () { const result = {};