[git] GPGME - branch, master, updated. gpgme-1.11.1-269-g1c61816
by Maximilian Krambach
cvs at cvs.gnupg.org
Wed Sep 5 18:44:48 CEST 2018
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GnuPG Made Easy".
The branch, master has been updated
via 1c618166fcd296b4e95f3a6ea9c415d3dca5ce0a (commit)
from 879cc1f84fbf09cb4eeb78bce16f52a1a36032ba (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 1c618166fcd296b4e95f3a6ea9c415d3dca5ce0a
Author: Maximilian Krambach <maximilian.krambach at intevation.de>
Date: Wed Sep 5 18:46:28 2018 +0200
js: documentation cleanup
--
diff --git a/lang/js/jsdoc.conf b/lang/js/jsdoc.conf
index 12ae35e..976f4e4 100644
--- a/lang/js/jsdoc.conf
+++ b/lang/js/jsdoc.conf
@@ -4,7 +4,7 @@
"dictionaries": ["jsdoc"]
},
"source": {
- "include": ["./src"],
+ "include": ["jsdoc_index.md", "./src"],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
diff --git a/lang/js/jsdoc_index.md b/lang/js/jsdoc_index.md
new file mode 100644
index 0000000..b7371ad
--- /dev/null
+++ b/lang/js/jsdoc_index.md
@@ -0,0 +1,50 @@
+Using gpgme.js
+---------------
+At first, make sure that the environment you want to use gpgme.js in has access
+and permissions for nativeMessaging, and gpgme-json installed. For details,
+see the README.
+
+The library itself is started via the {@link init} method. This will test the
+nativeMessaging connection, and then resolve into an Object offering
+the top level API:
+
+* [encrypt]{@link GpgME#encrypt}
+* [decrypt]{@link GpgME#decrypt}
+* [sign]{@link GpgME#sign}
+* [verify]{@link GpgME#verify}
+* [Keyring]{@link GPGME_Keyring}
+
+```
+gpgmejs.init()
+ .then(function(GPGME) {
+ // using GPGME
+ }, function(error){
+ // error handling;
+ })
+```
+
+All methods that require communication with nativeMessaging are asynchronous,
+using Promises. Rejections will be instances of {@link GPGME_Error}.
+
+An exaeption are Keys, which can be initialized in a 'sync' mode, allowing them
+to be cached and used synchronously until manually refreshed.
+
+Keyring and Keys
+----------------
+The gnupg keys can be accessed via the [Keyring]{@link GPGME_Keyring}.
+
+The Keyring offers the methods for accessing information on all Keys known to
+gnupg.
+
+**Due to security constraints, the javascript-binding currently only offers
+limited support for secret-Key interaction.**
+
+The existance of secret Keys is not secret, and those secret Keys can be used
+for signing, but Operations that may expose, modify or delete secret Keys are
+not supported.
+
+* [getKeysArmored]{@link GPGME_Keyring#getKeysArmored}
+* [getKeys]{@link GPGME_Keyring#getKeys}
+* [getDefaultKey]{@link GPGME_Keyring#getDefaultKey}
+* [generateKey]{@link GPGME_Keyring#generateKey}
+* [deleteKey]{@link GPGME_Keyring#deleteKey}
diff --git a/lang/js/src/Connection.js b/lang/js/src/Connection.js
index a421985..4055da6 100644
--- a/lang/js/src/Connection.js
+++ b/lang/js/src/Connection.js
@@ -35,6 +35,7 @@ import { decode, atobArray, Utf8ArrayToStr } from './Helpers';
* are finished. For a new request, a new port will open, to avoid mixing
* contexts.
* @class
+ * @private
*/
export class Connection{
@@ -58,6 +59,7 @@ export class Connection{
* @property {String} gpgme Version number of gpgme
* @property {Array<Object>} info Further information about the backend
* and the used applications (Example:
+ * <pre>
* {
* "protocol": "OpenPGP",
* "fname": "/usr/bin/gpg",
@@ -65,6 +67,7 @@ export class Connection{
* "req_version": "1.4.0",
* "homedir": "default"
* }
+ * </pre>
*/
/**
@@ -99,12 +102,14 @@ export class Connection{
}
/**
- * Sends a {@link GPGME_Message} via tghe nativeMessaging port. It
+ * Sends a {@link GPGME_Message} via the nativeMessaging port. It
* resolves with the completed answer after all parts have been
* received and reassembled, or rejects with an {@link GPGME_Error}.
*
* @param {GPGME_Message} message
- * @returns {Promise<Object>} The collected answer
+ * @returns {Promise<*>} The collected answer, depending on the messages'
+ * operation
+ * @private
* @async
*/
post (message){
@@ -182,7 +187,7 @@ export class Connection{
/**
* A class for answer objects, checking and processing the return messages of
* the nativeMessaging communication.
- * @protected
+ * @private
*/
class Answer{
diff --git a/lang/js/src/Errors.js b/lang/js/src/Errors.js
index 145c3a5..2f66c83 100644
--- a/lang/js/src/Errors.js
+++ b/lang/js/src/Errors.js
@@ -120,8 +120,9 @@ export const err_list = {
/**
* Checks the given error code and returns an {@link GPGME_Error} error object
* with some information about meaning and origin
- * @param {*} code Error code. Should be in err_list or 'GNUPG_ERROR'
- * @param {*} info Error message passed through if code is 'GNUPG_ERROR'
+ * @param {String} code Error code as defined in {@link err_list}.
+ * @param {String} info Possible additional error message to pass through.
+ * Currently used for errors sent as answer by gnupg via a native Message port
* @returns {GPGME_Error}
*/
export function gpgme_error (code = 'GENERIC_ERROR', info){
@@ -144,10 +145,13 @@ export function gpgme_error (code = 'GENERIC_ERROR', info){
/**
* An error class with additional info about the origin of the error, as string
+ * It is created by {@link gpgme_error}, and its' codes are defined in
+ * {@link err_list}.
+ *
* @property {String} code Short description of origin and type of the error
* @property {String} msg Additional info
- * @class
* @protected
+ * @class
* @extends Error
*/
class GPGME_Error extends Error{
diff --git a/lang/js/src/Helpers.js b/lang/js/src/Helpers.js
index 952c09f..f370fe6 100644
--- a/lang/js/src/Helpers.js
+++ b/lang/js/src/Helpers.js
@@ -24,11 +24,12 @@
import { gpgme_error } from './Errors';
/**
- * Tries to return an array of fingerprints, either from input fingerprints or
- * from Key objects (openpgp Keys or GPGME_Keys are both accepted).
+ * Helper function that tries to return an array of fingerprints, either from
+ * input fingerprints or from Key objects (openpgp Keys or GPGME_Keys are both
+ * accepted).
*
- * @param {Object | Array<Object> | String | Array<String>} input
- * @returns {Array<String>} Array of fingerprints, or an empty array
+ * @param {Object | Object[] | String | String[] } input
+ * @returns {String[]} Array of fingerprints, or an empty array
*/
export function toKeyIdArray (input){
if (!input){
@@ -90,7 +91,7 @@ function hextest (key, len){
}
/**
- * check if the input is a valid Fingerprint
+ * Checks if the input is a valid Fingerprint
* (Hex string with a length of 40 characters)
* @param {String} value to check
* @returns {Boolean} true if value passes test
@@ -110,8 +111,9 @@ export function isLongId (value){
}
/**
- * Recursively decodes input (utf8) to output (utf-16; javascript) strings
+ * Recursively decodes input (utf8) to output (utf-16; javascript) strings.
* @param {Object | Array | String} property
+ * @private
*/
export function decode (property){
if (typeof property === 'string'){
@@ -145,9 +147,10 @@ export function decode (property){
/**
* Turns a base64 encoded string into an uint8 array
+ * adapted from https://gist.github.com/borismus/1032746
* @param {String} base64 encoded String
* @returns {Uint8Array}
- * adapted from https://gist.github.com/borismus/1032746
+ * @private
*/
export function atobArray (base64) {
if (typeof (base64) !== 'string'){
@@ -164,8 +167,7 @@ export function atobArray (base64) {
/**
* Turns a Uint8Array into an utf8-String
- * @param {*} array Uint8Array
- * @returns {String}
+ * <pre>
* Taken and slightly adapted from
* http://www.onicos.com/staff/iz/amuse/javascript/expert/utf.txt
* (original header:
@@ -176,6 +178,10 @@ export function atobArray (base64) {
* LastModified: Dec 25 1999
* This library is free. You can redistribute it and/or modify it.
* )
+ * </pre>
+ * @param {*} array Uint8Array
+ * @returns {String}
+ * @private
*/
export function Utf8ArrayToStr (array) {
let out, i, len, c, char2, char3;
diff --git a/lang/js/src/Key.js b/lang/js/src/Key.js
index d0f87ed..7f0554c 100644
--- a/lang/js/src/Key.js
+++ b/lang/js/src/Key.js
@@ -21,6 +21,7 @@
* Maximilian Krambach <mkrambach at intevation.de>
*/
+
import { isFingerprint, isLongId } from './Helpers';
import { gpgme_error } from './Errors';
import { createMessage } from './Message';
@@ -50,11 +51,26 @@ export function createKey (fingerprint, async = false, data){
}
/**
- * Represents the Keys as stored in the gnupg backend
- * It allows to query almost all information defined in gpgme Key Objects
- * Refer to {@link validKeyProperties} for available information, and the gpgme
- * documentation on their meaning
- * (https://www.gnupg.org/documentation/manuals/gpgme/Key-objects.html)
+ * Represents the Keys as stored in the gnupg backend. A key is defined by a
+ * fingerprint.
+ * A key cannot be directly created via the new operator, please use
+ * {@link createKey} instead.
+ * A GPGME_Key object allows to query almost all information defined in gpgme
+ * Keys. It offers two modes, async: true/false. In async mode, Key properties
+ * with the exception of the fingerprint will be queried from gnupg on each
+ * call, making the operation up-to-date, the answers will be Promises, and
+ * the performance will likely suffer. In Sync modes, all information except
+ * for the armored Key export will be cached and can be refreshed by
+ * [refreshKey]{@link GPGME_Key#refreshKey}.
+ *
+ * <pre>
+ * see also:
+ * {@link GPGME_UserId} user Id objects
+ * {@link GPGME_Subkey} subKey objects
+ * </pre>
+ * For other Key properteis, refer to {@link validKeyProperties},
+ * and to the [gpgme documentation]{@link https://www.gnupg.org/documentation/manuals/gpgme/Key-objects.html}
+ * for meanings and further details.
*
* @class
*/
@@ -63,7 +79,8 @@ class GPGME_Key {
constructor (fingerprint, async, data){
/**
- * @property {Boolean} If true, most answers will be asynchronous
+ * @property {Boolean} _async If true, the Key was initialized without
+ * cached data
*/
this._async = async;
@@ -79,10 +96,13 @@ class GPGME_Key {
* Query any property of the Key listed in {@link validKeyProperties}
* @param {String} property property to be retreived
* @returns {Boolean| String | Date | Array | Object}
- * the value of the property. If the Key is set to Async, the value
- * will be fetched from gnupg and resolved as a Promise. If Key is not
- * async, the armored property is not available (it can still be
- * retrieved asynchronously by {@link Key.getArmor})
+ * @returns {Promise<Boolean| String | Date | Array | Object>} (if in async
+ * mode)
+ * <pre>
+ * Returns the value of the property requested. If the Key is set to async,
+ * the value will be fetched from gnupg and resolved as a Promise. If Key
+ * is not async, the armored property is not available (it can still be
+ * retrieved asynchronously by [getArmor]{@link GPGME_Key#getArmor})
*/
get (property) {
if (this._async === true) {
@@ -108,11 +128,11 @@ class GPGME_Key {
}
/**
- * Reloads the Key information from gnupg. This is only useful if you
+ * Reloads the Key information from gnupg. This is only useful if the Key
* use the GPGME_Keys cached. Note that this is a performance hungry
* operation. If you desire more than a few refreshs, it may be
- * advisable to run {@link Keyring.getKeys} instead.
- * @returns {Promise<GPGME_Key|GPGME_Error>}
+ * advisable to run [Keyring.getKeys]{@link Keyring#getKeys} instead.
+ * @returns {Promise<GPGME_Key>}
* @async
*/
refreshKey () {
@@ -155,7 +175,7 @@ class GPGME_Key {
* Query the armored block of the Key directly from gnupg. Please note
* that this will not get you any export of the secret/private parts of
* a Key
- * @returns {Promise<String|GPGME_Error>}
+ * @returns {Promise<String>}
* @async
*/
getArmor () {
@@ -179,10 +199,10 @@ class GPGME_Key {
* Find out if the Key is part of a Key pair including public and
* private key(s). If you want this information about more than a few
* Keys in synchronous mode, it may be advisable to run
- * {@link Keyring.getKeys} instead, as it performs faster in bulk
- * querying this state.
- * @returns {Promise<Boolean|GPGME_Error>} True if a private Key is
- * available in the gnupg Keyring.
+ * [Keyring.getKeys]{@link Keyring#getKeys} instead, as it performs faster
+ * in bulk querying.
+ * @returns {Promise<Boolean>} True if a private Key is available in the
+ * gnupg Keyring.
* @async
*/
getGnupgSecretState (){
@@ -216,9 +236,10 @@ class GPGME_Key {
/**
* Deletes the (public) Key from the GPG Keyring. Note that a deletion
- * of a secret key is not supported by the native backend.
- * @returns {Promise<Boolean|GPGME_Error>} Success if key was deleted,
- * rejects with a GPG error otherwise.
+ * of a secret key is not supported by the native backend, and gnupg will
+ * refuse to delete a Key if there is still a secret/private Key present
+ * to that public Key
+ * @returns {Promise<Boolean>} Success if key was deleted.
*/
delete (){
const me = this;
@@ -245,7 +266,8 @@ class GPGME_Key {
}
/**
- * Representing a subkey of a Key.
+ * Representing a subkey of a Key. See {@link validSubKeyProperties} for
+ * possible properties.
* @class
* @protected
*/
@@ -300,7 +322,8 @@ class GPGME_Subkey {
}
/**
- * Representing user attributes associated with a Key or subkey
+ * Representing user attributes associated with a Key or subkey. See
+ * {@link validUserIdProperties} for possible properties.
* @class
* @protected
*/
diff --git a/lang/js/src/Keyring.js b/lang/js/src/Keyring.js
index 0c64f33..e223284 100644
--- a/lang/js/src/Keyring.js
+++ b/lang/js/src/Keyring.js
@@ -45,7 +45,7 @@ export class GPGME_Keyring {
* information can be updated with the {@link Key.refresh} method.
* @param {Boolean} options.search (optional) retrieve Keys from external
* servers with the method(s) defined in gnupg (e.g. WKD/HKP lookup)
- * @returns {Promise<Array<GPGME_Key>>}
+ * @returns {Promise<GPGME_Key[]>}
* @static
* @async
*/
@@ -138,7 +138,7 @@ export class GPGME_Keyring {
* search for
* @param {Boolean} options.with_secret_fpr also return a list of
* fingerprints for the keys that have a secret key available
- * @returns {Promise<exportResult|GPGME_Error>} Object containing the
+ * @returns {Promise<exportResult>} Object containing the
* armored Key(s) and additional information.
* @static
* @async
@@ -175,7 +175,7 @@ export class GPGME_Keyring {
* It looks up the gpg configuration if set, or the first key that
* contains a secret key.
*
- * @returns {Promise<GPGME_Key|GPGME_Error>}
+ * @returns {Promise<GPGME_Key>}
* @async
* @static
*/
@@ -360,10 +360,10 @@ export class GPGME_Keyring {
}
/**
- * Convenience function for deleting a Key. See {@link Key.delete} for
+ * Convenience function for deleting a Key. See {@link Key#delete} for
* further information about the return values.
* @param {String} fingerprint
- * @returns {Promise<Boolean|GPGME_Error>}
+ * @returns {Promise<Boolean>}
* @async
* @static
*/
diff --git a/lang/js/src/Message.js b/lang/js/src/Message.js
index fff20fb..9f6abb7 100644
--- a/lang/js/src/Message.js
+++ b/lang/js/src/Message.js
@@ -45,9 +45,10 @@ export function createMessage (operation){
/**
* A Message collects, validates and handles all information required to
* successfully establish a meaningful communication with gpgme-json via
- * {@link Connection.post}. The definition on which communication is available
- * can be found in {@link permittedOperations}.
+ * [Connection.post]{@link Connection#post}. The definition on which
+ * communication is available can be found in {@link permittedOperations}.
* @class
+ * @protected
*/
export class GPGME_Message {
@@ -73,7 +74,7 @@ export class GPGME_Message {
return this._expected;
}
/**
- * The maximum size of responses from gpgme in bytes. As of July 2018,
+ * The maximum size of responses from gpgme in bytes. As of September 2018,
* most browsers will only accept answers up to 1 MB of size.
* Everything above that threshold will not pass through
* nativeMessaging; answers that are larger need to be sent in parts.
@@ -96,7 +97,8 @@ export class GPGME_Message {
}
/**
- * Returns the prepared message with parameters and completeness checked
+ * Returns the prepared message after their parameters and the completion
+ * of required parameters have been checked.
* @returns {Object|null} Object to be posted to gnupg, or null if
* incomplete
*/
@@ -110,10 +112,11 @@ export class GPGME_Message {
/**
* Sets a parameter for the message. It validates with
- * {@link permittedOperations}
+ * {@link permittedOperations}
* @param {String} param Parameter to set
* @param {any} value Value to set
- * @returns {Boolean} If the parameter was set successfully
+ * @returns {Boolean} True if the parameter was set successfully.
+ * Throws errors if the parameters don't match the message operation
*/
setParameter ( param,value ){
if (!param || typeof (param) !== 'string'){
@@ -213,9 +216,10 @@ export class GPGME_Message {
}
return true;
}
+
/**
* Sends the Message via nativeMessaging and resolves with the answer.
- * @returns {Promise<Object|GPGME_Error>}
+ * @returns {Promise<Object>} GPGME response
* @async
*/
post (){
diff --git a/lang/js/src/Signature.js b/lang/js/src/Signature.js
index 530590f..7f24f32 100644
--- a/lang/js/src/Signature.js
+++ b/lang/js/src/Signature.js
@@ -29,6 +29,7 @@ import { gpgme_error } from './Errors';
* of the expected values are to be found in {@link expKeys}, {@link expSum},
* {@link expNote}.
* @returns {GPGME_Signature|GPGME_Error} Signature Object
+ * @private
*/
export function createSignature (sigObject){
if (
@@ -131,10 +132,9 @@ class GPGME_Signature {
}
/**
- * gives more information on non-valid signatures. Refer to the gpgme
- * docs https://www.gnupg.org/documentation/manuals/gpgme/Verify.html
+ * Object with boolean properties giving more information on non-valid
+ * signatures. Refer to the [gpgme docs]{@link https://www.gnupg.org/documentation/manuals/gpgme/Verify.html}
* for details on the values.
- * @returns {Object} Object with boolean properties
*/
get errorDetails (){
let properties = ['revoked', 'key-expired', 'sig-expired',
@@ -151,7 +151,8 @@ class GPGME_Signature {
}
/**
- * Keys and their value's type for the signature Object
+ * Expected keys and their value's type for the signature Object
+ * @private
*/
const expKeys = {
'wrong_key_usage': 'boolean',
@@ -175,6 +176,7 @@ const expKeys = {
/**
* Keys and their value's type for the summary
+ * @private
*/
const expSum = {
'valid': 'boolean',
@@ -193,6 +195,7 @@ const expSum = {
/**
* Keys and their value's type for notations objects
+ * @private
*/
const expNote = {
'human_readable': 'boolean',
diff --git a/lang/js/src/gpgmejs.js b/lang/js/src/gpgmejs.js
index 7b835ac..9105724 100644
--- a/lang/js/src/gpgmejs.js
+++ b/lang/js/src/gpgmejs.js
@@ -30,16 +30,16 @@ import { createSignature } from './Signature';
/**
* @typedef {Object} decrypt_result
- * @property {String|Uint8Array} data The decrypted data
+ * @property {String|Uint8Array} data The decrypted data.
* @property {String} format Indicating how the data was converted after being
- * received from gpgme.
+ * received from gpgme:
+ * <pre>
* 'ascii': Data was ascii-encoded and no further processed
* 'string': Data was decoded into an utf-8 string,
* 'base64': Data was not processed and is a base64 string
* 'uint8': data was turned into a Uint8Array
- *
- * @property {Boolean} is_mime (optional) the data claims to be a MIME
- * object.
+ * </pre>
+ * @property {Boolean} is_mime (optional) the data claims to be a MIME object.
* @property {String} file_name (optional) the original file name
* @property {signatureDetails} signatures Verification details for
* signatures
@@ -47,22 +47,29 @@ import { createSignature } from './Signature';
/**
* @typedef {Object} signatureDetails
- * @property {Boolean} all_valid Summary if all signatures are fully valid
- * @property {Number} count Number of signatures found
- * @property {Number} failures Number of invalid signatures
- * @property {Array<GPGME_Signature>} signatures.good All valid signatures
- * @property {Array<GPGME_Signature>} signatures.bad All invalid signatures
+ * @property {Boolean} all_valid Quick summary. True if all signatures are
+ * fully valid according to gnupg.
+ * @property {Number} count Number of signatures parsed.
+ * @property {Number} failures Number of signatures not passing as valid. This
+ * may imply bad signatures, or signatures with e.g. the public Key not being
+ * available.
+ * @property {GPGME_Signature[]} signatures.good Array of all signatures
+ * considered valid.
+ * @property {GPGME_Signature[]} signatures.bad All invalid signatures.
*/
/**
- * @typedef {Object} encrypt_result The result of an encrypt operation
- * @property {String} data The encrypted message
+ * @typedef {Object} encrypt_result The result of an encrypt operation,
+ * containing the encrypted data and some additional information.
+ * @property {String} data The encrypted message.
* @property {String} format Indicating how the data was converted after being
* received from gpgme.
+ * <pre>
* 'ascii': Data was ascii-encoded and no further processed
* 'string': Data was decoded into an utf-8 string,
* 'base64': Data was not processed and is a base64 string
* 'uint8': Data was turned into a Uint8Array
+ * </pre>
*/
/**
@@ -77,7 +84,8 @@ import { createSignature } from './Signature';
* @typedef {Object} signResult The result of a signing operation
* @property {String} data The resulting data. Includes the signature in
* clearsign mode
- * @property {String} signature The detached signature (if in detached mode)
+ * @property {String} signature The detached signature (only present in in
+ * detached mode)
*/
/** @typedef {Object} verifyResult The result of a verification
@@ -98,17 +106,15 @@ export class GpgME {
this._Keyring = null;
}
- /**
- * setter for {@link setKeyring}.
- * @param {GPGME_Keyring} keyring A Keyring to use
- */
set Keyring (keyring){
if (keyring && keyring instanceof GPGME_Keyring){
this._Keyring = keyring;
}
}
+
/**
- * Accesses the {@link GPGME_Keyring}.
+ * Accesses the {@link GPGME_Keyring}. From the Keyring, all Keys can be
+ * accessed.
*/
get Keyring (){
if (!this._Keyring){
@@ -118,27 +124,29 @@ export class GpgME {
}
/**
- * Encrypt (and optionally sign) data
+ * Encrypt data for the recipients specified in publicKeys. If privateKeys
+ * are submitted, the data will be signed by those Keys.
* @param {Object} options
* @param {String|Object} options.data text/data to be encrypted as String.
- * Also accepts Objects with a getText method
+ * Also accepts Objects with a getText method.
* @param {inputKeys} options.publicKeys
* Keys used to encrypt the message
- * @param {inputKeys} opions.secretKeys (optional) Keys used to sign the
+ * @param {inputKeys} options.secretKeys (optional) Keys used to sign the
* message. If Keys are present, the operation requested is assumed
* to be 'encrypt and sign'
- * @param {Boolean} options.base64 (optional) The data will be interpreted
- * as base64 encoded data.
- * @param {Boolean} options.armor (optional) Request the output as armored
- * block.
- * @param {Boolean} options.wildcard (optional) If true, recipient
- * information will not be added to the message.
- * @param {Boolean} always_trust (optional, default true) This assumes that
- * used keys are fully trusted. If set to false, encryption to a key not
- * fully trusted in gnupg will fail
- * @param {String} expect in case of armored:false, request how to return
- * the binary result. Accepts 'base64' or 'uint8', defaults to 'base64'.
- * @param {Object} additional use additional valid gpg options as
+ * @param {Boolean} options.base64 (optional, default: false) The data will
+ * be interpreted as base64 encoded data.
+ * @param {Boolean} options.armor (optional, default: true) Request the
+ * output as armored block.
+ * @param {Boolean} options.wildcard (optional, default: false) If true,
+ * recipient information will not be added to the message.
+ * @param {Boolean} options.always_trust (optional, default true) This
+ * assumes that used keys are fully trusted. If set to false, encryption to
+ * a key not fully trusted in gnupg will fail.
+ * @param {String} options.expect (default: 'base64') In case of
+ * armored:false, request how to return the binary result.
+ * Accepts 'base64' or 'uint8'
+ * @param {Object} options.additional use additional valid gpg options as
* defined in {@link permittedOperations}
* @returns {Promise<encrypt_result>} Object containing the encrypted
* message and additional info.
@@ -206,15 +214,21 @@ export class GpgME {
}
/**
- * Decrypts a Message
+ * Decrypts (and verifies, if applicable) a message.
* @param {Object} options
* @param {String|Object} options.data text/data to be decrypted. Accepts
- * Strings and Objects with a getText method
- * @param {Boolean} options.base64 (optional) false if the data is an
- * armored block, true if it is base64 encoded binary data
- * @param {String} options.expect (optional) can be set to 'uint8' or
- * 'base64'. Does no extra decoding on the data, and returns the decoded
- * data as either Uint8Array or unprocessed(base64 encoded) string.
+ * Strings and Objects with a getText method.
+ * @param {Boolean} options.base64 (optional, default: false). Indicate that
+ * the input given is base64-encoded binary instead of an armored block in
+ * gpg armored form.
+ * @param {String} options.expect (optional). By default, the output is
+ * expected to be a string compatible with javascript. In cases of binary
+ * data the decryption may fail due to encoding problems. For data expected
+ * to return as binary data, the decroding after decryption can be bypassed:
+ * <pre>
+ * 'uint8': Return as Uint8Array
+ * 'base64': Return as unprocessed (base64 encoded) string.
+ * </pre>
* @returns {Promise<decrypt_result>} Decrypted Message and information
* @async
*/
@@ -269,14 +283,16 @@ export class GpgME {
}
/**
- * Sign a Message
+ * Sign a Message.
* @param {Object} options Signing options
* @param {String|Object} options.data text/data to be signed. Accepts
* Strings and Objects with a getText method.
* @param {inputKeys} options.keys The key/keys to use for signing
* @param {String} options.mode The signing mode. Currently supported:
- * 'clearsign':The Message is embedded into the signature;
- * 'detached': The signature is stored separately
+ * <pre>
+ * 'clearsign':The Message is embedded into the signature;
+ * 'detached': The signature is stored separately
+ * </pre>
* @param {Boolean} options.base64 input is considered base64
* @returns {Promise<signResult>}
* @async
@@ -415,6 +431,7 @@ function putData (message, data){
* Parses, validates and converts incoming objects into signatures.
* @param {Array<Object>} sigs
* @returns {signatureDetails} Details about the signatures
+ * @private
*/
function collectSignatures (sigs){
if (!Array.isArray(sigs)){
diff --git a/lang/js/src/index.js b/lang/js/src/index.js
index cf6e2d0..c52460c 100644
--- a/lang/js/src/index.js
+++ b/lang/js/src/index.js
@@ -27,9 +27,11 @@ import { gpgme_error } from './Errors';
import { Connection } from './Connection';
/**
- * Initializes gpgme.js by testing the nativeMessaging connection once.
- * @returns {Promise<GpgME> | GPGME_Error}
- *
+ * Main entry point for gpgme.js. It initializes by testing the nativeMessaging
+ * connection once, and then offers the available functions as method of the
+ * response object.
+ * An unsuccessful attempt will reject as a GPGME_Error.
+ * @returns {Promise<GpgME>}
* @async
*/
function init (){
-----------------------------------------------------------------------
Summary of changes:
lang/js/jsdoc.conf | 2 +-
lang/js/jsdoc_index.md | 50 ++++++++++++++++++++++
lang/js/src/Connection.js | 11 +++--
lang/js/src/Errors.js | 10 +++--
lang/js/src/Helpers.js | 24 +++++++----
lang/js/src/Key.js | 69 ++++++++++++++++++++-----------
lang/js/src/Keyring.js | 10 ++---
lang/js/src/Message.js | 18 ++++----
lang/js/src/Signature.js | 11 +++--
lang/js/src/gpgmejs.js | 103 +++++++++++++++++++++++++++-------------------
lang/js/src/index.js | 8 ++--
11 files changed, 215 insertions(+), 101 deletions(-)
create mode 100644 lang/js/jsdoc_index.md
hooks/post-receive
--
GnuPG Made Easy
http://git.gnupg.org
More information about the Gnupg-commits
mailing list