GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

js: documentation cleanup

Browse Source 
--
This commit is contained in:
Maximilian Krambach 2018-09-05 18:46:28 +02:00
parent 879cc1f84f
commit 1c618166fc
11 changed files with 215 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
lang/js/jsdoc.conf
View File

@ -4,7 +4,7 @@
"dictionaries": ["jsdoc"]
},
"source": {
"include": ["./src"],
"include": ["jsdoc_index.md", "./src"],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},

50
lang/js/jsdoc_index.md Normal file
View File

@ -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}

11
lang/js/src/Connection.js
View File

@ -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{

10
lang/js/src/Errors.js
View File

@ -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{

24
lang/js/src/Helpers.js
View File

@ -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;

69
lang/js/src/Key.js
View File

@ -21,6 +21,7 @@
* Maximilian Krambach <mkrambach@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
*/

10
lang/js/src/Keyring.js
View File

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

16
lang/js/src/Message.js
View File

@ -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
*/
@ -113,7 +115,8 @@ export class GPGME_Message {
* {@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 (){

11
lang/js/src/Signature.js
View File

@ -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',

99
lang/js/src/gpgmejs.js
View File

@ -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:
* <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)){

8
lang/js/src/index.js
View File

@ -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 (){