Skip to content
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
BrowserTestExtension 05a0e97f5c12c06082fbeab0fba6f86ddbfbe6b2 Oct 25, 2018
DemoExtension 05a0e97f5c12c06082fbeab0fba6f86ddbfbe6b2 Oct 25, 2018
build 94a0ed361ea04c2a0a2e144877b0e17b9fea35a2 Aug 22, 2018
src 05a0e97f5c12c06082fbeab0fba6f86ddbfbe6b2 Oct 25, 2018
.babelrc
.eslintrc.json 138e1dde027338358a8da19ff8592b7369494534 Aug 24, 2018
CHECKLIST 10f2106404f01e7bb369fc66a597875fb455cd27 Jul 4, 2018
CHECKLIST_build 10f2106404f01e7bb369fc66a597875fb455cd27 Jul 4, 2018
Makefile
Makefile.am 53d69af01492873337a7b819e003a8f63698be1e Sep 8, 2018
Makefile.in 1420c3bd681648b032d756536311621a3627bedb Aug 29, 2018
README 6d720137dd9564931bf313a7e7078e63fb00287c Aug 21, 2018
build_extensions.sh 10f2106404f01e7bb369fc66a597875fb455cd27 Jul 4, 2018
jsdoc.conf 53d69af01492873337a7b819e003a8f63698be1e Sep 8, 2018
jsdoc_index.md 53d69af01492873337a7b819e003a8f63698be1e Sep 8, 2018
package.json 10f2106404f01e7bb369fc66a597875fb455cd27 Jul 4, 2018
unittest_inputvalues.js 6d720137dd9564931bf313a7e7078e63fb00287c Aug 21, 2018
unittests.js 05a0e97f5c12c06082fbeab0fba6f86ddbfbe6b2 Oct 25, 2018
webpack.conf.js 05a0e97f5c12c06082fbeab0fba6f86ddbfbe6b2 Oct 25, 2018
webpack.conf_unittests.js 05a0e97f5c12c06082fbeab0fba6f86ddbfbe6b2 Oct 25, 2018

README

gpgme.js - JavaScript for GPGME
-------------------------------
Initially developed for integration with the Mailvelope Web Extension.

Overview
--------

gpgme.js is a javascript library for direct use of GnuPG in browsers.
It interacts with GPGME through nativeMessaging and gpgme-json.

It is meant to be distributed directly by its downstream users in
their extension package. As such it is not integrated in the
autotools build system. See build instructions below.


gpgme-json
----------

gpgme-json (see core src/gpgme-json.c) the json to GPGME bridge is
required as native messaging backend for gpgme.js to work.
It needs to be installed and registered as native messaging
backend with the browser.

See gpgme-mozilla.json and gpgme-chrome.json examples in
the top level doc/examples as example manifests.

Any web extension using gpgme.js will need to be whitelisted in the manifest
file by its id.

Distributors are encouraged to create manifest packages for their
distributions.


Building gpgme.js
-----------------

gpgme.js uses webpack, and thus depends on Node.js for building.
All dependencies will be installed (in a local subdirectory) with the command
`npm install`.

To create a current version of the package, the command is
`npx webpack --config webpack.conf.js`.
If you want a more debuggable (i.e. not minified) build, just change the mode
in webpack.conf.js.


Demo and Test WebExtension:
---------------------------

The Demo Extension shows simple examples of the usage of gpgme.js.

The BrowsertestExtension runs more intensive tests (using the mocha and chai
frameworks). Tests from BrowserTestExtension/tests will be run against the
gpgmejs.bundle.js itself. They aim to test the outward facing functionality
and API.

Unittests as defined in ./unittests.js will be bundled in
gpgmejs_unittests.bundle.js, and test the separate components of gpgme.js,
which mostly are not exported.

The file `build_extension.sh` may serve as a pointer on how to build and
assemble these two Extensions and their dependencies. It can directly
be used in most linux systems.

The resulting folders can just be included in the extensions tab of the browser
in questions (extension debug mode needs to be active). For chrome, selecting
the folder is sufficient, for firefox, the manifest.json needs to be selected.
Please note that it is just for demonstration/debug purposes!

For the Extensions to successfully communicate with gpgme-json, a manifest file
is needed.

- `~/.config/chromium/NativeMessagingHosts/gpgmejson.json`

In the browsers' nativeMessaging configuration folder a file 'gpgmejs.json'
is needed, with the following content:

- For Chrome/Chromium:
  ```
  {
    "name": "gpgmejson",
    "description": "This is a test application for gpgme.js",
    "path": "/usr/bin/gpgme-json",
    "type": "stdio",
    "allowed_origins": ["chrome-extension://ExtensionIdentifier/"]
  }
  ```
  The usual path for Linux is similar to:
  `~/.config/chromium/NativeMessagingHosts/gpgmejson.json` for
  For Windows, the path to the manifest needs to be placed in
  `HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\gpgmejson`

  - For firefox:
  ```
  {
    "name": "gpgmejson",
    "description": "This is a test application for gpgme.js",
    "path": "/usr/bin/gpgme-json",
    "type": "stdio",
    "allowed_extensions": ["ExtensionIdentifier@temporary-addon"]
  }
  ```

  The ExtensionIdentifier can be seen as Extension ID on the about:addons page
  if addon-debugging is active. In firefox, the temporary addon is removed once
  firefox exits, and the identifier will need to be changed more often.

  The manifest for linux is usually placed at:
    `~/.mozilla/native-messaging-hosts/gpgmejson.json`


Documentation
-------------

The documentation can be built by jsdoc. It currently uses the command
`./node_modules/.bin/jsdoc -c jsdoc.conf`.
You can’t perform that action at this time.