|
Packit Service |
30b792 |
gpgme.js - JavaScript for GPGME
|
|
Packit Service |
30b792 |
-------------------------------
|
|
Packit Service |
30b792 |
Initially developed for integration with the Mailvelope Web Extension.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
Overview
|
|
Packit Service |
30b792 |
--------
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
gpgme.js is a javascript library for direct use of GnuPG in browsers.
|
|
Packit Service |
30b792 |
It interacts with GPGME through nativeMessaging and gpgme-json.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
It is meant to be distributed directly by its downstream users in
|
|
Packit Service |
30b792 |
their extension package. As such it is not integrated in the
|
|
Packit Service |
30b792 |
autotools build system. See build instructions below.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
gpgme-json
|
|
Packit Service |
30b792 |
----------
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
gpgme-json (see core src/gpgme-json.c) the json to GPGME bridge is
|
|
Packit Service |
30b792 |
required as native messaging backend for gpgme.js to work.
|
|
Packit Service |
30b792 |
It needs to be installed and registered as native messaging
|
|
Packit Service |
30b792 |
backend with the browser.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
See gpgme-mozilla.json and gpgme-chrome.json examples in
|
|
Packit Service |
30b792 |
the top level doc/examples as example manifests.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
Any web extension using gpgme.js will need to be whitelisted in the manifest
|
|
Packit Service |
30b792 |
file by its id.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
Distributors are encouraged to create manifest packages for their
|
|
Packit Service |
30b792 |
distributions.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
Building gpgme.js
|
|
Packit Service |
30b792 |
-----------------
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
gpgme.js uses webpack, and thus depends on Node.js for building.
|
|
Packit Service |
30b792 |
All dependencies will be installed (in a local subdirectory) with the command
|
|
Packit Service |
30b792 |
`npm install`.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
To create a current version of the package, the command is
|
|
Packit Service |
30b792 |
`npx webpack --config webpack.conf.js`.
|
|
Packit Service |
30b792 |
If you want a more debuggable (i.e. not minified) build, just change the mode
|
|
Packit Service |
30b792 |
in webpack.conf.js.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
Demo and Test WebExtension:
|
|
Packit Service |
30b792 |
---------------------------
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
The Demo Extension shows simple examples of the usage of gpgme.js.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
The BrowsertestExtension runs more intensive tests (using the mocha and chai
|
|
Packit Service |
30b792 |
frameworks). Tests from BrowserTestExtension/tests will be run against the
|
|
Packit Service |
30b792 |
gpgmejs.bundle.js itself. They aim to test the outward facing functionality
|
|
Packit Service |
30b792 |
and API.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
Unittests as defined in ./unittests.js will be bundled in
|
|
Packit Service |
30b792 |
gpgmejs_unittests.bundle.js, and test the separate components of gpgme.js,
|
|
Packit Service |
30b792 |
which mostly are not exported.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
The file `build_extension.sh` may serve as a pointer on how to build and
|
|
Packit Service |
30b792 |
assemble these two Extensions and their dependencies. It can directly
|
|
Packit Service |
30b792 |
be used in most linux systems.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
The resulting folders can just be included in the extensions tab of the browser
|
|
Packit Service |
30b792 |
in questions (extension debug mode needs to be active). For chrome, selecting
|
|
Packit Service |
30b792 |
the folder is sufficient, for firefox, the manifest.json needs to be selected.
|
|
Packit Service |
30b792 |
Please note that it is just for demonstration/debug purposes!
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
For the Extensions to successfully communicate with gpgme-json, a manifest file
|
|
Packit Service |
30b792 |
is needed.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
- `~/.config/chromium/NativeMessagingHosts/gpgmejson.json`
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
In the browsers' nativeMessaging configuration folder a file 'gpgmejs.json'
|
|
Packit Service |
30b792 |
is needed, with the following content:
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
- For Chrome/Chromium:
|
|
Packit Service |
30b792 |
```
|
|
Packit Service |
30b792 |
{
|
|
Packit Service |
30b792 |
"name": "gpgmejson",
|
|
Packit Service |
30b792 |
"description": "This is a test application for gpgme.js",
|
|
Packit Service |
30b792 |
"path": "/usr/bin/gpgme-json",
|
|
Packit Service |
30b792 |
"type": "stdio",
|
|
Packit Service |
30b792 |
"allowed_origins": ["chrome-extension://ExtensionIdentifier/"]
|
|
Packit Service |
30b792 |
}
|
|
Packit Service |
30b792 |
```
|
|
Packit Service |
30b792 |
The usual path for Linux is similar to:
|
|
Packit Service |
30b792 |
`~/.config/chromium/NativeMessagingHosts/gpgmejson.json` for
|
|
Packit Service |
30b792 |
For Windows, the path to the manifest needs to be placed in
|
|
Packit Service |
30b792 |
`HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\gpgmejson`
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
- For firefox:
|
|
Packit Service |
30b792 |
```
|
|
Packit Service |
30b792 |
{
|
|
Packit Service |
30b792 |
"name": "gpgmejson",
|
|
Packit Service |
30b792 |
"description": "This is a test application for gpgme.js",
|
|
Packit Service |
30b792 |
"path": "/usr/bin/gpgme-json",
|
|
Packit Service |
30b792 |
"type": "stdio",
|
|
Packit Service |
30b792 |
"allowed_extensions": ["ExtensionIdentifier@temporary-addon"]
|
|
Packit Service |
30b792 |
}
|
|
Packit Service |
30b792 |
```
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
The ExtensionIdentifier can be seen as Extension ID on the about:addons page
|
|
Packit Service |
30b792 |
if addon-debugging is active. In firefox, the temporary addon is removed once
|
|
Packit Service |
30b792 |
firefox exits, and the identifier will need to be changed more often.
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
The manifest for linux is usually placed at:
|
|
Packit Service |
30b792 |
`~/.mozilla/native-messaging-hosts/gpgmejson.json`
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
Documentation
|
|
Packit Service |
30b792 |
-------------
|
|
Packit Service |
30b792 |
|
|
Packit Service |
30b792 |
The documentation can be built by jsdoc. It currently uses the command
|
|
Packit Service |
30b792 |
`./node_modules/.bin/jsdoc -c jsdoc.conf`.
|