suzanne.soy/fork-openpgpjs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Daniel Huigens 2018-08-14 15:45:06 +02:00
parent 6134b0dcaf
commit e055d86062
6 changed files with 111 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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<Uint8Array>} Value derived from session
* @async
*/
async function decrypt(oid, cipher_algo, hash_algo, V, C, d, fingerprint) {

2
src/encoding/armor.js
View File

@ -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<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
* @static

60
src/key.js
View File

@ -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<SubKey>}
* @returns {Array<module:key~SubKey>}
*/
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<Key|SubKey>}
* @returns {Array<module:key.Key|module:key~SubKey>}
*/
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<module:type/keyid>}
*/
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|SubKey|null>} key or null if no signing key has been found
* @returns {Promise<module:key.Key|module:key~SubKey|null>} 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|SubKey|null>} key or null if no encryption key has been found
* @returns {Promise<module:key.Key|module:key~SubKey|null>} 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<undefined>}
* @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<module:key.Key>} 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<module:key.Key>} 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<undefined>}
* @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<undefined>}
* @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<module:key~SubKey>} 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<module:key.Key>,
* err: (Array<Error>|null)}} result object with key and error arrays
* @returns {Promise<{keys: Array<module:key.Key>,
* err: (Array<Error>|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<String>} armoredText text to be parsed
* @returns {{keys: Array<module:key.Key>,
* err: (Array<Error>|null)}} result object with key and error arrays
* @returns {Promise<{keys: Array<module:key.Key>,
* err: (Array<Error>|null)}>} result object with key and error arrays
* @async
* @static
*/

4
src/message.js
View File

@ -679,7 +679,7 @@ Message.prototype.armor = function() {
/**
* reads an OpenPGP armored message and returns a message object
* @param {String | ReadableStream<String>} armoredText text to be parsed
* @returns {module:message.Message} new message object
* @returns {Promise<module:message.Message>} 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<Uint8Array>} input binary message
* @param {Boolean} fromStream whether the message was created from a Stream
* @returns {module:message.Message} new message object
* @returns {Promise<module:message.Message>} new message object
* @async
* @static
*/

89
src/openpgp.js
View File

@ -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<Object>} The revoked key object in the form:
* @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)
* @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<Object>} 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>} Object containing encrypted (and optionally signed) message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if `armor` was true, the default)
* message: Message, (if `armor` was false)
* signature: String|ReadableStream<String>|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<Object>} sessionKeys (optional) session keys in the form: { data:Uint8Array, algorithm:String }
* @param {Key|Array<Key>} 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<Object>} decrypted and verified message in the form:
* { data:Uint8Array|String, filename:String, signatures:[{ keyid:String, valid:Boolean }] }
* @returns {Promise<Object>} Object containing decrypted and verified message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if format was 'utf8', the default)
* data: Uint8Array|ReadableStream<Uint8Array>|NodeStream, (if format was 'binary')
* filename: String,
* signatures: [
* {
* keyid: module:type/keyid,
* verified: Promise<Boolean>,
* 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<Key>} 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<Object>} 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<Key>} 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>} Object containing signed message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if `armor` was true, the default)
* message: Message (if `armor` was false)
* }
*
* Or, if `detached` was true:
*
* {
* signature: String|ReadableStream<String>|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<Key>} 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<Object>} cleartext with status of verified signatures in the form of:
* { data:String, signatures: [{ keyid:String, valid:Boolean }] }
* @param {Key|Array<Key>} 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>} Object containing verified message in the form:
*
* {
* data: String|ReadableStream<String>|NodeStream, (if `message` was a CleartextMessage)
* data: Uint8Array|ReadableStream<Uint8Array>|NodeStream, (if `message` was a Message)
* signatures: [
* {
* keyid: module:type/keyid,
* verified: Promise<Boolean>,
* valid: Boolean (if `streaming` was false)
* }, ...
* ]
* }
* @async
* @static
*/

2
src/packet/public_key.js
View File

@ -233,7 +233,7 @@ PublicKey.prototype.getFingerprint = function () {
/**
* Returns algorithm information
* @returns {Promise<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}
*/
PublicKey.prototype.getAlgorithmInfo = function () {
const result = {};