diff --git a/README.md b/README.md index dcfd19cd..4ef15963 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,18 @@ OpenPGP.js [![BrowserStack Status](https://automate.browserstack.com/badge.svg?badge_key=eEkxVVM1TytwOGJNWEdnTjk4Y0VNUUNyR3pXcEtJUGRXOVFBRjVNT1JpUT0tLTZYUlZaMWdtQWs4Z0ROS3grRXc2bFE9PQ==--4a9cac0d6ea009d81aff66de0dbb239edd1aef3c)](https://automate.browserstack.com/public-build/eEkxVVM1TytwOGJNWEdnTjk4Y0VNUUNyR3pXcEtJUGRXOVFBRjVNT1JpUT0tLTZYUlZaMWdtQWs4Z0ROS3grRXc2bFE9PQ==--4a9cac0d6ea009d81aff66de0dbb239edd1aef3c) [![Join the chat on Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/openpgpjs/openpgpjs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ========== -[OpenPGP.js](https://openpgpjs.org/) is a JavaScript implementation of the OpenPGP protocol. This is defined in [RFC 4880](https://tools.ietf.org/html/rfc4880). +[OpenPGP.js](https://openpgpjs.org/) is a JavaScript implementation of the OpenPGP protocol. It implements [RFC4880](https://tools.ietf.org/html/rfc4880) and parts of [RFC4880bis](https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-10). - **Table of Contents** - [OpenPGP.js](#openpgpjs) - [Platform Support](#platform-support) - [Performance](#performance) - [Getting started](#getting-started) - - [Npm](#npm) - - [Bower](#bower) + - [Node.js](#nodejs) + - [Browser (webpack)](#browser-webpack) + - [Browser (plain files)](#browser-plain-files) - [Examples](#examples) - - [Set up](#set-up) - [Encrypt and decrypt *Uint8Array* data with a password](#encrypt-and-decrypt-uint8array-data-with-a-password) - [Encrypt and decrypt *String* data with PGP keys](#encrypt-and-decrypt-string-data-with-pgp-keys) - [Encrypt with compression](#encrypt-with-compression) @@ -32,9 +31,6 @@ OpenPGP.js [![BrowserStack Status](https://automate.browserstack.com/badge.svg?b - [Development](#development) - [How do I get involved?](#how-do-i-get-involved) - [License](#license) - - [Resources](#resources) - - ### Platform Support @@ -58,26 +54,29 @@ library to convert back and forth between them. ### Performance -* Version 3.0.0 of the library introduces support for public-key cryptography using [elliptic curves](https://wiki.gnupg.org/ECC). We use native implementations on browsers and Node.js when available or [Elliptic](https://github.com/indutny/elliptic) otherwise. Elliptic curve cryptography provides stronger security per bits of key, which allows for much faster operations. Currently the following curves are supported (* = when available): +* Version 3.0.0 of the library introduces support for public-key cryptography using [elliptic curves](https://wiki.gnupg.org/ECC). We use native implementations on browsers and Node.js when available. Elliptic curve cryptography provides stronger security per bits of key, which allows for much faster operations. Currently the following curves are supported: + | Curve | Encryption | Signature | NodeCrypto | WebCrypto | Constant-Time | + |:---------------:|:----------:|:---------:|:----------:|:---------:|:-----------------:| + | curve25519 | ECDH | N/A | No | No | Algorithmically** | + | ed25519 | N/A | EdDSA | No | No | Algorithmically** | + | p256 | ECDH | ECDSA | Yes* | Yes* | If native*** | + | p384 | ECDH | ECDSA | Yes* | Yes* | If native*** | + | p521 | ECDH | ECDSA | Yes* | Yes* | If native*** | + | brainpoolP256r1 | ECDH | ECDSA | Yes* | No | If native*** | + | brainpoolP384r1 | ECDH | ECDSA | Yes* | No | If native*** | + | brainpoolP512r1 | ECDH | ECDSA | Yes* | No | If native*** | + | secp256k1 | ECDH | ECDSA | Yes* | No | If native*** | - | Curve | Encryption | Signature | Elliptic | NodeCrypto | WebCrypto | - |:--------------- |:----------:|:---------:|:--------:|:----------:|:---------:| - | p256 | ECDH | ECDSA | Yes | Yes* | Yes* | - | p384 | ECDH | ECDSA | Yes | Yes* | Yes* | - | p521 | ECDH | ECDSA | Yes | Yes* | Yes* | - | secp256k1 | ECDH | ECDSA | Yes | Yes* | No | - | brainpoolP256r1 | ECDH | ECDSA | Yes | Yes* | No | - | brainpoolP384r1 | ECDH | ECDSA | Yes | Yes* | No | - | brainpoolP512r1 | ECDH | ECDSA | Yes | Yes* | No | - | curve25519 | ECDH | N/A | Yes | No | No | - | ed25519 | N/A | EdDSA | Yes | No | No | + \* when available + \** the curve25519 and ed25519 implementations are algorithmically constant-time, but may not be constant-time after optimizations of the JavaScript compiler + \*** these curves are only constant-time if the underlying native implementation is available and constant-time * Version 2.x of the library has been built from the ground up with Uint8Arrays. This allows for much better performance and memory usage than strings. * If the user's browser supports [native WebCrypto](https://caniuse.com/#feat=cryptography) via the `window.crypto.subtle` API, this will be used. Under Node.js the native [crypto module](https://nodejs.org/api/crypto.html#crypto_crypto) is used. -* The library implements the [IETF proposal](https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-07) for authenticated encryption using native AES-EAX, OCB, or GCM. This makes symmetric encryption up to 30x faster on supported platforms. Since the specification has not been finalized and other OpenPGP implementations haven't adopted it yet, the feature is currently behind a flag. **Note: activating this setting can break compatibility with other OpenPGP implementations, and also with future versions of OpenPGP.js. Don't use it with messages you want to store on disk or in a database.** You can enable it by setting `openpgp.config.aeadProtect = true`. +* The library implements the [IETF proposal](https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-10) for authenticated encryption using native AES-EAX, OCB, or GCM. This makes symmetric encryption up to 30x faster on supported platforms. Since the specification has not been finalized and other OpenPGP implementations haven't adopted it yet, the feature is currently behind a flag. **Note: activating this setting can break compatibility with other OpenPGP implementations, and also with future versions of OpenPGP.js. Don't use it with messages you want to store on disk or in a database.** You can enable it by setting `openpgp.config.aeadProtect = true`. You can change the AEAD mode by setting one of the following options: @@ -87,59 +86,88 @@ library to convert back and forth between them. openpgp.config.aeadMode = openpgp.enums.aead.experimentalGcm // **Non-standard**, fastest ``` -* For environments that don't provide native crypto, the library falls back to [asm.js](https://caniuse.com/#feat=asmjs) implementations of AES, SHA-1, and SHA-256. We use [Rusha](https://github.com/srijs/rusha) and [asmCrypto Lite](https://github.com/openpgpjs/asmcrypto-lite) (a minimal subset of asmCrypto.js built specifically for OpenPGP.js). +* For environments that don't provide native crypto, the library falls back to [asm.js](https://caniuse.com/#feat=asmjs) implementations of AES, SHA-1, and SHA-256. ### Getting started -#### Npm +#### Node.js - npm install --save openpgp +Install OpenPGP.js using npm and save it in your dependencies: -#### Bower +```sh +npm install --save openpgp +``` - bower install --save openpgp - -Or just fetch a minified build under [dist](https://github.com/openpgpjs/openpgpjs/tree/master/dist). - - -### Examples - -Here are some examples of how to use the v5.x+ API. For more elaborate examples and working code, please check out the [public API unit tests](https://github.com/openpgpjs/openpgpjs/blob/master/test/general/openpgp.js). If you're upgrading from v4.x it might help to check out the [documentation](https://github.com/openpgpjs/openpgpjs#documentation). - -#### Set up - -##### Node.js +And import it as a CommonJS module: ```js const openpgp = require('openpgp'); ``` -##### Browser +Or as an ES6 module, from an .mjs file: -Copy `dist/openpgp.min.js` or `dist/compat/openpgp.min.js` (depending on the browser support you need, see [Platform Support](#platform-support)) to your project folder, and load it in a script tag: +```js +import * as openpgp from 'openpgp'; +``` + +#### Browser (webpack) + +Install OpenPGP.js using npm and save it in your devDependencies: + +```sh +npm install --save-dev openpgp +``` + +And import it as an ES6 module: + +```js +import * as openpgp from 'openpgp'; +``` + +You can also only import the functions you need, as follows: + +```js +import { readMessage, decrypt } from 'openpgp'; +``` + +Or, if you want to use the lightweight build (which is smaller, and lazily loads non-default curves on demand): + +```js +import * as openpgp from 'openpgp/lightweight'; +``` + +To test whether the lazy loading works, try to generate a key with a non-standard curve: + +```js +import { generateKey } from 'openpgp/lightweight'; +await generateKey({ curve: 'brainpoolP512r1', userIds: [{ name: 'Test', email: 'test@test.com' }] }); +``` + +For more examples of how to generate a key, see [Generate new key pair](#generate-new-key-pair). It is recommended to use `curve25519` instead of `brainpoolP512r1` by default. + + +#### Browser (plain files) + +Grab `openpgp.min.js` from [unpkg.com/openpgp/dist](https://unpkg.com/openpgp/dist/), and load it in a script tag: ```html ``` -To offload cryptographic operations off the main thread, you can implement a Web Worker in your application and load OpenPGP.js from there. This can be more performant if you store or fetch keys and messages directly inside the Worker, so that they don't have to be `postMessage`d there. For an example Worker implementation, see `test/worker/worker_example.js`. - -If you want to use the lightweight build (which is smaller, and lazily loads non-default curves on demand), copy `dist/lightweight/openpgp.min.mjs` and `dist/lightweight/elliptic.min.mjs`, and import the former: +Or, to load OpenPGP.js as an ES6 module, grab `openpgp.min.mjs` from [unpkg.com/openpgp/dist](https://unpkg.com/openpgp/dist/), and import it as follows: ```html ``` -To test whether the lazy loading works, try: +To offload cryptographic operations off the main thread, you can implement a Web Worker in your application and load OpenPGP.js from there. For an example Worker implementation, see `test/worker/worker_example.js`. -```js -await openpgp.generateKey({ curve: 'brainpoolP512r1', userIds: [{ name: 'Test', email: 'test@test.com' }] }); -``` +### Examples -For more examples of how to generate a key, see [Generate new key pair](#generate-new-key-pair). It is recommended to use `curve25519` instead of `brainpoolP512r1` by default. +Here are some examples of how to use OpenPGP.js v5. For more elaborate examples and working code, please check out the [public API unit tests](https://github.com/openpgpjs/openpgpjs/blob/master/test/general/openpgp.js). If you're upgrading from v4 it might help to check out the [changelog](https://github.com/openpgpjs/openpgpjs/wiki/V5-Changelog) and [documentation](https://github.com/openpgpjs/openpgpjs#documentation). #### Encrypt and decrypt *Uint8Array* data with a password @@ -357,19 +385,20 @@ its [Reader class](https://openpgpjs.org/web-stream-tools/Reader.html). #### Generate new key pair -ECC keys: +ECC keys (smaller and faster to generate): -Possible values for `curve` are: `curve25519`, `ed25519`, `p256`, `p384`, `p521`, `secp256k1`, -`brainpoolP256r1`, `brainpoolP384r1`, or `brainpoolP512r1`. +Possible values for `curve` are: `curve25519`, `ed25519`, `p256`, `p384`, `p521`, +`brainpoolP256r1`, `brainpoolP384r1`, `brainpoolP512r1`, and `secp256k1`. Note that both the `curve25519` and `ed25519` options generate a primary key for signing using Ed25519 and a subkey for encryption using Curve25519. ```js (async () => { const { privateKeyArmored, publicKeyArmored, revocationCertificate } = await openpgp.generateKey({ + type: 'ecc', // Type of the key, defaults to ECC + curve: 'curve25519', // ECC curve name, defaults to curve25519 userIds: [{ name: 'Jon Smith', email: 'jon@example.com' }], // you can pass multiple user IDs - curve: 'ed25519', // ECC curve name - passphrase: 'super long and hard to guess secret' // protects the private key + passphrase: 'super long and hard to guess secret' // protects the private key }); console.log(privateKeyArmored); // '-----BEGIN PGP PRIVATE KEY BLOCK ... ' @@ -378,14 +407,15 @@ and a subkey for encryption using Curve25519. })(); ``` -RSA keys: +RSA keys (increased compatibility): ```js (async () => { const key = await openpgp.generateKey({ + type: 'rsa', // Type of the key + rsaBits: 4096, // RSA key size (defaults to 4096 bits) userIds: [{ name: 'Jon Smith', email: 'jon@example.com' }], // you can pass multiple user IDs - rsaBits: 4096, // RSA key size - passphrase: 'super long and hard to guess secret' // protects the private key + passphrase: 'super long and hard to guess secret' // protects the private key }); })(); ``` @@ -571,9 +601,7 @@ Using the private key: ### Documentation -A jsdoc build of our code comments is available at [doc/index.html](https://openpgpjs.org/openpgpjs/doc/index.html). Public calls should generally be made through the OpenPGP object [doc/openpgp.html](https://openpgpjs.org/openpgpjs/doc/module-openpgp.html). - -For the documentation of `openpgp.stream`, see the documentation of [the web-stream-tools dependency](https://openpgpjs.org/web-stream-tools/). +The full documentation is available at [openpgpjs.org](https://openpgpjs.org/openpgpjs/). ### Security Audit @@ -602,13 +630,3 @@ You want to help, great! It's probably best to send us a message on [Gitter](htt ### License [GNU Lesser General Public License](https://www.gnu.org/licenses/lgpl-3.0.en.html) (3.0 or any later version). Please take a look at the [LICENSE](LICENSE) file for more information. - -### Resources - -Below is a collection of resources, many of these were projects that were in someway a precursor to the current OpenPGP.js project. If you'd like to add your link here, please do so in a pull request or email to the list. - -* [https://www.hanewin.net/encrypt/](https://www.hanewin.net/encrypt/) -* [https://github.com/seancolyer/gmail-crypt](https://github.com/seancolyer/gmail-crypt) -* [https://github.com/mete0r/jspg](https://github.com/mete0r/jspg) -* [https://github.com/GPGTools/Mobile/wiki/Introduction](https://github.com/GPGTools/Mobile/wiki/Introduction) -* [https://github.com/gmontalvoriv/mailock](https://github.com/gmontalvoriv/mailock) diff --git a/package-lock.json b/package-lock.json index dc640a41..fcf09406 100644 --- a/package-lock.json +++ b/package-lock.json @@ -576,6 +576,12 @@ "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==", "dev": true }, + "bluebird": { + "version": "3.7.2", + "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz", + "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==", + "dev": true + }, "bn.js": { "version": "4.11.8", "resolved": "https://registry.npmjs.org/bn.js/-/bn.js-4.11.8.tgz", @@ -1298,9 +1304,9 @@ "dev": true }, "entities": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/entities/-/entities-2.0.0.tgz", - "integrity": "sha512-D9f7V0JSRwIxlRI2mjMqufDrRDnx8p+eEOz7aUM9SuvF8gsBzra0/6tbjl1m8eQHrZlYj6PxqE00hZ1SAIKPLw==", + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/entities/-/entities-2.0.3.tgz", + "integrity": "sha512-MyoZ0jgnLvB2X3Lg5HqpFmn1kybDiIfEQmKzTb5apr51Rb+T3KdmMiqa70T+bhGnyv7bQ6WMj2QMHpGMmlrUYQ==", "dev": true }, "error-ex": { @@ -2702,8 +2708,8 @@ } }, "jsdoc": { - "version": "github:openpgpjs/jsdoc#0f1816eb4553856647b4ca9561b9307b11ec4f9e", - "from": "github:openpgpjs/jsdoc#0f1816eb4553856647b4ca9561b9307b11ec4f9e", + "version": "github:openpgpjs/jsdoc#ff7cb3929586868bf91deb78a26d7e217e051a0f", + "from": "github:openpgpjs/jsdoc#ff7cb3929586868bf91deb78a26d7e217e051a0f", "dev": true, "requires": { "@babel/parser": "^7.9.4", @@ -2722,30 +2728,12 @@ "underscore": "~1.10.2" }, "dependencies": { - "@babel/parser": { - "version": "7.9.6", - "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.9.6.tgz", - "integrity": "sha512-AoeIEJn8vt+d/6+PXDRPaksYhnlbMIiejioBZvvMQsOjW/JYK6k/0dKnvvP3EhK5GfMBWDPtrxRtegWdAcdq9Q==", - "dev": true - }, - "bluebird": { - "version": "3.7.2", - "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz", - "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==", - "dev": true - }, "escape-string-regexp": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz", "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==", "dev": true }, - "marked": { - "version": "0.8.2", - "resolved": "https://registry.npmjs.org/marked/-/marked-0.8.2.tgz", - "integrity": "sha512-EGwzEeCcLniFX51DhTpmTom+dSA/MG/OBUDjnWtHbEnjAH180VzUeAw+oE4+Zv+CoYBWyRlYOTR0N8SO9R1PVw==", - "dev": true - }, "mkdirp": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", @@ -2753,9 +2741,9 @@ "dev": true }, "strip-json-comments": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.0.tgz", - "integrity": "sha512-e6/d0eBu7gHtdCqFt0xJr642LdToM5/cN4Qb9DbHjVx1CP5RyeM+zH7pbecEmDv/lBqb0QH+6Uqq75rxFPkM0w==", + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", + "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==", "dev": true } } @@ -3282,9 +3270,15 @@ } }, "markdown-it-anchor": { - "version": "5.2.7", - "resolved": "https://registry.npmjs.org/markdown-it-anchor/-/markdown-it-anchor-5.2.7.tgz", - "integrity": "sha512-REFmIaSS6szaD1bye80DMbp7ePwsPNvLTR5HunsUcZ0SG0rWJQ+Pz24R4UlTKtjKBPhxo0v0tOBDYjZQQknW8Q==", + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/markdown-it-anchor/-/markdown-it-anchor-5.3.0.tgz", + "integrity": "sha512-/V1MnLL/rgJ3jkMWo84UR+K+jF1cxNG1a+KwqeXqTIJ+jtA8aWSHuigx8lTzauiIjBDbwF3NcWQMotd0Dm39jA==", + "dev": true + }, + "marked": { + "version": "0.8.2", + "resolved": "https://registry.npmjs.org/marked/-/marked-0.8.2.tgz", + "integrity": "sha512-EGwzEeCcLniFX51DhTpmTom+dSA/MG/OBUDjnWtHbEnjAH180VzUeAw+oE4+Zv+CoYBWyRlYOTR0N8SO9R1PVw==", "dev": true }, "mdurl": { diff --git a/package.json b/package.json index 35bf63c2..cf2bf47b 100644 --- a/package.json +++ b/package.json @@ -72,7 +72,7 @@ "esm": "^3.2.25", "hash.js": "^1.1.3", "http-server": "^0.12.3", - "jsdoc": "github:openpgpjs/jsdoc#0f1816eb4553856647b4ca9561b9307b11ec4f9e", + "jsdoc": "github:openpgpjs/jsdoc#ff7cb3929586868bf91deb78a26d7e217e051a0f", "karma": "^6.1.0", "karma-browserstack-launcher": "^1.6.0", "karma-mocha": "^2.0.1", diff --git a/src/biginteger/bn.interface.js b/src/biginteger/bn.interface.js index 84226097..b4616867 100644 --- a/src/biginteger/bn.interface.js +++ b/src/biginteger/bn.interface.js @@ -1,8 +1,15 @@ import BN from 'bn.js'; /** + * @fileoverview * BigInteger implementation of basic operations * Wrapper of bn.js library (wwww.github.com/indutny/bn.js) + * @module biginteger/bn + * @private + */ + +/** + * @private */ export default class BigInteger { /** diff --git a/src/biginteger/native.interface.js b/src/biginteger/native.interface.js index 20397b13..c593de80 100644 --- a/src/biginteger/native.interface.js +++ b/src/biginteger/native.interface.js @@ -1,10 +1,17 @@ /* eslint-disable new-cap */ /** + * @fileoverview * BigInteger implementation of basic operations * that wraps the native BigInt library. * Operations are not constant time, * but we try and limit timing leakage where we can + * @module biginteger/native + * @private + */ + +/** + * @private */ export default class BigInteger { /** @@ -189,7 +196,7 @@ export default class BigInteger { * Extended Eucleadian algorithm (http://anh.cs.luc.edu/331/notes/xgcd.pdf) * Given a = this and b, compute (x, y) such that ax + by = gdc(a, b) * @param {BigInteger} b second operand - * @returns { gcd, x, y: BigInteger } + * @returns {{ gcd, x, y: BigInteger }} */ _egcd(b) { let x = BigInt(0); diff --git a/src/cleartext.js b/src/cleartext.js index 0087ce8d..5574ea52 100644 --- a/src/cleartext.js +++ b/src/cleartext.js @@ -15,15 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires encoding/armor - * @requires enums - * @requires util - * @requires packet - * @requires signature - * @module cleartext - */ - import { armor, unarmor } from './encoding/armor'; import enums from './enums'; import util from './util'; @@ -38,8 +29,8 @@ import defaultConfig from './config'; */ export class CleartextMessage { /** - * @param {String} text The cleartext of the signed message - * @param {module:signature.Signature} signature The detached signature or an empty signature for unsigned messages + * @param {String} text The cleartext of the signed message + * @param {Signature} signature The detached signature or an empty signature for unsigned messages */ constructor(text, signature) { // normalize EOL to canonical form @@ -52,7 +43,7 @@ export class CleartextMessage { /** * Returns the key IDs of the keys that signed the cleartext message - * @returns {Array} array of keyid objects + * @returns {Array} array of keyid objects */ getSigningKeyIds() { const keyIds = []; @@ -65,13 +56,13 @@ export class CleartextMessage { /** * Sign the cleartext message - * @param {Array} privateKeys private keys with decrypted secret key data for signing + * @param {Array} privateKeys private keys with decrypted secret key data for signing * @param {Signature} signature (optional) any existing detached signature - * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] + * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] * @param {Date} date (optional) The creation time of the signature that should be created * @param {Array} userIds (optional) user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }] * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} new cleartext message with signed content + * @returns {Promise} new cleartext message with signed content * @async */ async sign(privateKeys, signature = null, signingKeyIds = [], date = new Date(), userIds = [], config = defaultConfig) { @@ -80,13 +71,13 @@ export class CleartextMessage { /** * Sign the cleartext message - * @param {Array} privateKeys private keys with decrypted secret key data for signing + * @param {Array} privateKeys private keys with decrypted secret key data for signing * @param {Signature} signature (optional) any existing detached signature - * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] + * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] * @param {Date} date (optional) The creation time of the signature that should be created * @param {Array} userIds (optional) user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }] * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} new detached signature of message content + * @returns {Promise} new detached signature of message content * @async */ async signDetached(privateKeys, signature = null, signingKeyIds = [], date = new Date(), userIds = [], config = defaultConfig) { @@ -98,10 +89,10 @@ export class CleartextMessage { /** * Verify signatures of cleartext signed message - * @param {Array} keys array of keys to verify signatures + * @param {Array} keys array of keys to verify signatures * @param {Date} date (optional) Verify the signature against the given date, i.e. check signature creation time < date < expiration time * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise>} list of signer's keyid and validity of signature + * @returns {Promise>} list of signer's keyid and validity of signature * @async */ verify(keys, date = new Date(), config = defaultConfig) { @@ -110,10 +101,10 @@ export class CleartextMessage { /** * Verify signatures of cleartext signed message - * @param {Array} keys array of keys to verify signatures + * @param {Array} keys array of keys to verify signatures * @param {Date} date (optional) Verify the signature against the given date, i.e. check signature creation time < date < expiration time * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise>} list of signer's keyid and validity of signature + * @returns {Promise>} list of signer's keyid and validity of signature * @async */ verifyDetached(signature, keys, date = new Date(), config = defaultConfig) { @@ -166,7 +157,7 @@ export class CleartextMessage { * Reads an OpenPGP cleartext signed message and returns a CleartextMessage object * @param {String | ReadableStream} cleartextMessage text to be parsed * @param {Object} config (optional) custom configuration settings to overwrite those in openpgp.config - * @returns {module:cleartext.CleartextMessage} new cleartext message object + * @returns {CleartextMessage} new cleartext message object * @async * @static */ diff --git a/src/config/config.js b/src/config/config.js index 868ba7e6..0c1c9d10 100644 --- a/src/config/config.js +++ b/src/config/config.js @@ -17,7 +17,6 @@ /** * Global configuration values. - * @requires enums */ import enums from '../enums'; diff --git a/src/crypto/aes_kw.js b/src/crypto/aes_kw.js index 14d5839c..40bdceac 100644 --- a/src/crypto/aes_kw.js +++ b/src/crypto/aes_kw.js @@ -18,9 +18,8 @@ /** * @fileoverview Implementation of RFC 3394 AES Key Wrap & Key Unwrap funcions * @see module:crypto/public_key/elliptic/ecdh - * @requires crypto/cipher - * @requires util * @module crypto/aes_kw + * @private */ import * as cipher from './cipher'; diff --git a/src/crypto/cfb.js b/src/crypto/cfb.js index c23857fd..042cfb46 100644 --- a/src/crypto/cfb.js +++ b/src/crypto/cfb.js @@ -18,10 +18,8 @@ */ /** - * @requires web-stream-tools - * @requires crypto/cipher - * @requires util * @module crypto/cfb + * @private */ import { AES_CFB } from 'asmcrypto.js/dist_es8/aes/cfb'; diff --git a/src/crypto/cipher/aes.js b/src/crypto/cipher/aes.js index ff389480..0d0661c2 100644 --- a/src/crypto/cipher/aes.js +++ b/src/crypto/cipher/aes.js @@ -1,7 +1,3 @@ -/** - * @requires asmcrypto.js - */ - import { AES_ECB } from 'asmcrypto.js/dist_es8/aes/ecb'; // TODO use webCrypto or nodeCrypto when possible. diff --git a/src/crypto/cipher/index.js b/src/crypto/cipher/index.js index daf3f222..bb97112d 100644 --- a/src/crypto/cipher/index.js +++ b/src/crypto/cipher/index.js @@ -1,11 +1,7 @@ /** * @fileoverview Symmetric cryptography functions - * @requires crypto/cipher/aes - * @requires crypto/cipher/des - * @requires crypto/cipher/cast5 - * @requires crypto/cipher/twofish - * @requires crypto/cipher/blowfish * @module crypto/cipher + * @private */ import aes from './aes'; @@ -21,7 +17,6 @@ import BF from './blowfish'; * @see {@link https://github.com/asmcrypto/asmcrypto.js|asmCrypto} * @see {@link https://csrc.nist.gov/publications/fips/fips197/fips-197.pdf|NIST FIPS-197} * @returns {Object} - * @requires asmcrypto.js */ export const aes128 = aes(128); /** @@ -31,7 +26,6 @@ export const aes128 = aes(128); * @see {@link https://github.com/asmcrypto/asmcrypto.js|asmCrypto} * @see {@link https://csrc.nist.gov/publications/fips/fips197/fips-197.pdf|NIST FIPS-197} * @returns {Object} - * @requires asmcrypto.js */ export const aes192 = aes(192); /** @@ -41,7 +35,6 @@ export const aes192 = aes(192); * @see {@link https://github.com/asmcrypto/asmcrypto.js|asmCrypto} * @see {@link https://csrc.nist.gov/publications/fips/fips197/fips-197.pdf|NIST FIPS-197} * @returns {Object} - * @requires asmcrypto.js */ export const aes256 = aes(256); // Not in OpenPGP specifications diff --git a/src/crypto/cmac.js b/src/crypto/cmac.js index 3eda17ea..ad4217a8 100644 --- a/src/crypto/cmac.js +++ b/src/crypto/cmac.js @@ -1,9 +1,8 @@ /** * @fileoverview This module implements AES-CMAC on top of * native AES-CBC using either the WebCrypto API or Node.js' crypto API. - * @requires asmcrypto.js - * @requires util * @module crypto/cmac + * @private */ import { AES_CBC } from 'asmcrypto.js/dist_es8/aes/cbc'; diff --git a/src/crypto/crypto.js b/src/crypto/crypto.js index f0da2898..9341b0bf 100644 --- a/src/crypto/crypto.js +++ b/src/crypto/crypto.js @@ -20,15 +20,8 @@ /** * @fileoverview Provides functions for asymmetric encryption and decryption as * well as key generation and parameter handling for all public-key cryptosystems. - * @requires crypto/public_key - * @requires crypto/cipher - * @requires crypto/random - * @requires type/ecdh_symkey - * @requires type/kdf_params - * @requires type/oid - * @requires enums - * @requires util * @module crypto/crypto + * @private */ import publicKey from './public_key'; diff --git a/src/crypto/eax.js b/src/crypto/eax.js index e59cf3ff..6a0d9abd 100644 --- a/src/crypto/eax.js +++ b/src/crypto/eax.js @@ -18,10 +18,8 @@ /** * @fileoverview This module implements AES-EAX en/decryption on top of * native AES-CTR using either the WebCrypto API or Node.js' crypto API. - * @requires asmcrypto.js - * @requires crypto/cmac - * @requires util * @module crypto/eax + * @private */ import { AES_CTR } from 'asmcrypto.js/dist_es8/aes/ctr'; diff --git a/src/crypto/gcm.js b/src/crypto/gcm.js index 64b75567..f5de5f4c 100644 --- a/src/crypto/gcm.js +++ b/src/crypto/gcm.js @@ -18,9 +18,8 @@ /** * @fileoverview This module wraps native AES-GCM en/decryption for both * the WebCrypto api as well as node.js' crypto api. - * @requires asmcrypto.js - * @requires util * @module crypto/gcm + * @private */ import { AES_GCM } from 'asmcrypto.js/dist_es8/aes/gcm'; diff --git a/src/crypto/hash/index.js b/src/crypto/hash/index.js index 961e0a2f..fa704408 100644 --- a/src/crypto/hash/index.js +++ b/src/crypto/hash/index.js @@ -2,12 +2,8 @@ * @fileoverview Provides an interface to hashing functions available in Node.js or external libraries. * @see {@link https://github.com/asmcrypto/asmcrypto.js|asmCrypto} * @see {@link https://github.com/indutny/hash.js|hash.js} - * @requires asmcrypto.js - * @requires hash.js - * @requires web-stream-tools - * @requires crypto/hash/md5 - * @requires util * @module crypto/hash + * @private */ import { Sha1 } from 'asmcrypto.js/dist_es8/hash/sha1/sha1'; diff --git a/src/crypto/hash/md5.js b/src/crypto/hash/md5.js index 126c8fb1..ce2b592c 100644 --- a/src/crypto/hash/md5.js +++ b/src/crypto/hash/md5.js @@ -12,10 +12,6 @@ * warranty of any kind. */ -/** - * @requires util - */ - import util from '../../util'; // MD5 Digest diff --git a/src/crypto/index.js b/src/crypto/index.js index ac08ed0f..eecab5bb 100644 --- a/src/crypto/index.js +++ b/src/crypto/index.js @@ -7,6 +7,7 @@ * @see module:crypto/random * @see module:crypto/hash * @module crypto + * @private */ import * as cipher from './cipher'; diff --git a/src/crypto/ocb.js b/src/crypto/ocb.js index 8547e27e..93f86651 100644 --- a/src/crypto/ocb.js +++ b/src/crypto/ocb.js @@ -17,9 +17,8 @@ /** * @fileoverview This module implements AES-OCB en/decryption. - * @requires crypto/cipher - * @requires util * @module crypto/ocb + * @private */ import * as ciphers from './cipher'; diff --git a/src/crypto/pkcs1.js b/src/crypto/pkcs1.js index d91f234e..c9e0e2ef 100644 --- a/src/crypto/pkcs1.js +++ b/src/crypto/pkcs1.js @@ -20,9 +20,8 @@ * @see module:crypto/public_key/rsa * @see module:crypto/public_key/elliptic/ecdh * @see PublicKeyEncryptedSessionKeyPacket - * @requires crypto/random - * @requires crypto/hash * @module crypto/pkcs1 + * @private */ import { getRandomBytes } from './random'; diff --git a/src/crypto/pkcs5.js b/src/crypto/pkcs5.js index acb1577b..183bbb29 100644 --- a/src/crypto/pkcs5.js +++ b/src/crypto/pkcs5.js @@ -21,6 +21,7 @@ import util from '../util'; * @fileoverview Functions to add and remove PKCS5 padding * @see PublicKeyEncryptedSessionKeyPacket * @module crypto/pkcs5 + * @private */ /** diff --git a/src/crypto/public_key/dsa.js b/src/crypto/public_key/dsa.js index a501eb39..f22d441b 100644 --- a/src/crypto/public_key/dsa.js +++ b/src/crypto/public_key/dsa.js @@ -17,9 +17,8 @@ /** * @fileoverview A Digital signature algorithm implementation - * @requires crypto/random - * @requires util * @module crypto/public_key/dsa + * @private */ import { getRandomBigInteger } from '../random'; import util from '../../util'; diff --git a/src/crypto/public_key/elgamal.js b/src/crypto/public_key/elgamal.js index 81fa505b..2386f0df 100644 --- a/src/crypto/public_key/elgamal.js +++ b/src/crypto/public_key/elgamal.js @@ -17,9 +17,8 @@ /** * @fileoverview ElGamal implementation - * @requires crypto/random - * @requires util * @module crypto/public_key/elgamal + * @private */ import util from '../../util'; diff --git a/src/crypto/public_key/elliptic/curves.js b/src/crypto/public_key/elliptic/curves.js index 7370f970..302cd4c8 100644 --- a/src/crypto/public_key/elliptic/curves.js +++ b/src/crypto/public_key/elliptic/curves.js @@ -17,14 +17,8 @@ /** * @fileoverview Wrapper of an instance of an Elliptic Curve - * @requires tweetnacl - * @requires crypto/public_key/elliptic/key - * @requires crypto/random - * @requires enums - * @requires util - * @requires type/oid - * @requires config * @module crypto/public_key/elliptic/curve + * @private */ import nacl from 'tweetnacl/nacl-fast-light.js'; diff --git a/src/crypto/public_key/elliptic/ecdh.js b/src/crypto/public_key/elliptic/ecdh.js index 04c97c18..1d0910ed 100644 --- a/src/crypto/public_key/elliptic/ecdh.js +++ b/src/crypto/public_key/elliptic/ecdh.js @@ -17,16 +17,8 @@ /** * @fileoverview Key encryption and decryption for RFC 6637 ECDH - * @requires tweetnacl - * @requires crypto/public_key/elliptic/curve - * @requires crypto/aes_kw - * @requires crypto/cipher - * @requires crypto/random - * @requires crypto/hash - * @requires type/kdf_params - * @requires enums - * @requires util * @module crypto/public_key/elliptic/ecdh + * @private */ import nacl from 'tweetnacl/nacl-fast-light.js'; diff --git a/src/crypto/public_key/elliptic/ecdsa.js b/src/crypto/public_key/elliptic/ecdsa.js index 6dacca49..461bd4ac 100644 --- a/src/crypto/public_key/elliptic/ecdsa.js +++ b/src/crypto/public_key/elliptic/ecdsa.js @@ -17,11 +17,8 @@ /** * @fileoverview Implementation of ECDSA following RFC6637 for Openpgpjs - * @requires web-stream-tools - * @requires enums - * @requires util - * @requires crypto/public_key/elliptic/curves * @module crypto/public_key/elliptic/ecdsa + * @private */ import enums from '../../../enums'; diff --git a/src/crypto/public_key/elliptic/eddsa.js b/src/crypto/public_key/elliptic/eddsa.js index f3845228..3c5da63c 100644 --- a/src/crypto/public_key/elliptic/eddsa.js +++ b/src/crypto/public_key/elliptic/eddsa.js @@ -17,11 +17,8 @@ /** * @fileoverview Implementation of EdDSA following RFC4880bis-03 for OpenPGP - * @requires hash.js - * @requires tweetnacl - * @requires crypto/public_key/elliptic/curve - * @requires util * @module crypto/public_key/elliptic/eddsa + * @private */ import sha512 from 'hash.js/lib/hash/sha/512'; diff --git a/src/crypto/public_key/elliptic/index.js b/src/crypto/public_key/elliptic/index.js index 4fac26fd..2f5367fe 100644 --- a/src/crypto/public_key/elliptic/index.js +++ b/src/crypto/public_key/elliptic/index.js @@ -22,6 +22,7 @@ * @see module:crypto/public_key/elliptic/ecdsa * @see module:crypto/public_key/elliptic/eddsa * @module crypto/public_key/elliptic + * @private */ import { Curve, generate, getPreferredHashAlgo } from './curves'; diff --git a/src/crypto/public_key/elliptic/indutnyKey.js b/src/crypto/public_key/elliptic/indutnyKey.js index c1022524..4df03b24 100644 --- a/src/crypto/public_key/elliptic/indutnyKey.js +++ b/src/crypto/public_key/elliptic/indutnyKey.js @@ -17,9 +17,8 @@ /** * @fileoverview Wrapper for a KeyPair of an curve from indutny/elliptic library - * @requires enums - * @requires asn1.js * @module crypto/public_key/elliptic/indutnyKey + * @private */ import config from '../../../config'; diff --git a/src/crypto/public_key/index.js b/src/crypto/public_key/index.js index e9a81025..01973352 100644 --- a/src/crypto/public_key/index.js +++ b/src/crypto/public_key/index.js @@ -1,11 +1,7 @@ /** * @fileoverview Asymmetric cryptography functions - * @requires tweetnacl - * @requires crypto/public_key/dsa - * @requires crypto/public_key/elgamal - * @requires crypto/public_key/elliptic - * @requires crypto/public_key/rsa * @module crypto/public_key + * @private */ import nacl from 'tweetnacl/nacl-fast-light.js'; diff --git a/src/crypto/public_key/prime.js b/src/crypto/public_key/prime.js index d2f39a4a..fb330565 100644 --- a/src/crypto/public_key/prime.js +++ b/src/crypto/public_key/prime.js @@ -17,8 +17,8 @@ /** * @fileoverview Algorithms for probabilistic random prime generation - * @requires crypto/random * @module crypto/public_key/prime + * @private */ import util from '../../util'; diff --git a/src/crypto/public_key/rsa.js b/src/crypto/public_key/rsa.js index e7c10caf..5a85e8b4 100644 --- a/src/crypto/public_key/rsa.js +++ b/src/crypto/public_key/rsa.js @@ -17,11 +17,8 @@ /** * @fileoverview RSA implementation - * @requires crypto/public_key/prime - * @requires crypto/random - * @requires config - * @requires util * @module crypto/public_key/rsa + * @private */ import { randomProbablePrime } from './prime'; diff --git a/src/crypto/random.js b/src/crypto/random.js index 56a12777..07412793 100644 --- a/src/crypto/random.js +++ b/src/crypto/random.js @@ -19,8 +19,8 @@ /** * @fileoverview Provides tools for retrieving secure randomness from browsers or Node.js - * @requires util * @module crypto/random + * @private */ import util from '../util'; diff --git a/src/crypto/signature.js b/src/crypto/signature.js index 39946b7b..6e3542db 100644 --- a/src/crypto/signature.js +++ b/src/crypto/signature.js @@ -1,10 +1,8 @@ /** * @fileoverview Provides functions for asymmetric signing and signature verification - * @requires crypto/public_key - * @requires enums - * @requires util * @module crypto/signature -*/ + * @private + */ import publicKey from './public_key'; import enums from '../enums'; diff --git a/src/encoding/armor.js b/src/encoding/armor.js index 60f7e0c3..16890fab 100644 --- a/src/encoding/armor.js +++ b/src/encoding/armor.js @@ -15,15 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires web-stream-tools - * @requires encoding/base64 - * @requires enums - * @requires config - * @requires util - * @module encoding/armor - */ - import stream from 'web-stream-tools'; import * as base64 from './base64.js'; import enums from '../enums.js'; @@ -32,7 +23,6 @@ import defaultConfig from '../config'; /** * Finds out which Ascii Armoring type is used. Throws error if unknown type. - * @private * @param {String} text [String] ascii armored text * @returns {Integer} 0 = MESSAGE PART n of m * 1 = MESSAGE PART n @@ -41,6 +31,7 @@ import defaultConfig from '../config'; * 4 = PUBLIC KEY BLOCK * 5 = PRIVATE KEY BLOCK * 6 = SIGNATURE + * @private */ function getType(text) { const reHeader = /^-----BEGIN PGP (MESSAGE, PART \d+\/\d+|MESSAGE, PART \d+|SIGNED MESSAGE|MESSAGE|PUBLIC KEY BLOCK|PRIVATE KEY BLOCK|SIGNATURE)-----$/m; @@ -99,6 +90,7 @@ function getType(text) { * @version 2011-12-16 * @param {String} customComment (optional) additional comment to add to the armored string * @returns {String} The header information + * @private */ function addheader(customComment, config) { let result = ""; @@ -120,6 +112,7 @@ function addheader(customComment, config) { * Calculates a checksum over the given data and returns it base64 encoded * @param {String | ReadableStream} data Data to create a CRC-24 checksum for * @returns {String | ReadableStream} Base64 encoded checksum + * @private */ function getCheckSum(data) { const crc = createcrc24(data); @@ -167,6 +160,7 @@ const isLittleEndian = (function() { * Internal function to calculate a CRC-24 checksum over a given string (data) * @param {String | ReadableStream} data Data to create a CRC-24 checksum for * @returns {Uint8Array | ReadableStream} The CRC-24 checksum + * @private */ function createcrc24(input) { let crc = 0xCE04B7; @@ -209,6 +203,7 @@ function verifyHeaders(headers) { * @param {String} text OpenPGP armored message part * @returns {Object} An object with attribute "body" containing the body * and an attribute "checksum" containing the checksum. + * @private */ function splitChecksum(text) { let body = text; diff --git a/src/encoding/base64.js b/src/encoding/base64.js index da56729a..2f1947c5 100644 --- a/src/encoding/base64.js +++ b/src/encoding/base64.js @@ -12,9 +12,8 @@ */ /** - * @requires web-stream-tools - * @requires util * @module encoding/base64 + * @private */ import stream from 'web-stream-tools'; diff --git a/src/hkp.js b/src/hkp.js index 44c2a69b..4fc4276b 100644 --- a/src/hkp.js +++ b/src/hkp.js @@ -15,14 +15,12 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @fileoverview This class implements a client for the OpenPGP HTTP Keyserver Protocol (HKP) - * in order to lookup and upload keys on standard public key servers. - * @module hkp - */ - import defaultConfig from './config'; +/** + * This class implements a client for the OpenPGP HTTP Keyserver Protocol (HKP) + * in order to lookup and upload keys on standard public key servers. + */ class HKP { /** * Initialize the HKP client and configure it with the key server url and fetch function. diff --git a/src/index.js b/src/index.js index ec42e062..083a3841 100644 --- a/src/index.js +++ b/src/index.js @@ -11,74 +11,26 @@ export { generateSessionKey, encryptSessionKey, decryptSessionKeys } from './openpgp'; -/** - * @see module:key - * @name module:openpgp.key - */ export { Key, readKey, readKeys } from './key'; -/** - * @see module:signature - * @name module:openpgp.signature - */ export { Signature, readSignature } from './signature'; -/** - * @see module:message - * @name module:openpgp.message - */ export { Message, readMessage } from './message'; -/** - * @see module:cleartext - * @name module:openpgp.cleartext - */ export { CleartextMessage, readCleartextMessage } from './cleartext'; -/** - * @see module:packet - * @name module:openpgp.packet - */ export * from './packet'; -/** - * @see streams - * @name module:openpgp.stream - */ export { default as stream } from 'web-stream-tools'; -/** - * @see module:encoding/armor - * @name module:openpgp.armor - */ export * from './encoding/armor'; -/** - * @see module:enums - * @name module:openpgp.enums - */ export { default as enums } from './enums'; -/** - * @see module:config/config - * @name module:openpgp.config - */ export { default as config } from './config/config'; -/** - * @see module:keyring - * @name module:openpgp.Keyring - */ export { default as Keyring } from './keyring'; -/** - * @see module:hkp - * @name module:openpgp.HKP - */ export { default as HKP } from './hkp'; -/** - * @see module:wkd - * @name module:openpgp.WKD - */ export { default as WKD } from './wkd'; diff --git a/src/key/factory.js b/src/key/factory.js index 37af5f6b..f6372aa3 100644 --- a/src/key/factory.js +++ b/src/key/factory.js @@ -15,18 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @fileoverview Provides factory methods for key creation - * @requires packet - * @requires key/Key - * @requires key/helper - * @requires enums - * @requires util - * @requires config - * @requires armor - * @module key/factory - */ - import { PacketList, UserIDPacket, SignaturePacket } from '../packet'; import Key from './key'; import * as helper from './helper'; @@ -48,9 +36,10 @@ import { unarmor } from '../encoding/armor'; * @param {Object} config Full configuration * @param {Array} options.subkeys (optional) options for each subkey, default to main key options. e.g. [{sign: true, passphrase: '123'}] * sign parameter defaults to false, and indicates whether the subkey should sign rather than encrypt - * @returns {Promise} + * @returns {Promise} * @async * @static + * @private */ export async function generate(options, config) { options.sign = true; // primary key is always a signing key @@ -63,7 +52,7 @@ export async function generate(options, config) { /** * Reformats and signs an OpenPGP key with a given User ID. Currently only supports RSA keys. - * @param {module:key.Key} options.privateKey The private key to reformat + * @param {Key} options.privateKey The private key to reformat * @param {Array} options.userIds User IDs as strings or objects: 'Jo Doe ' or { name:'Jo Doe', email:'info@jo.com' } * @param {String} options.passphrase Passphrase used to encrypt the resulting private key * @param {Number} options.keyExpirationTime Number of seconds from the key creation time after which the key expires @@ -71,9 +60,10 @@ export async function generate(options, config) { * @param {Array} options.subkeys (optional) options for each subkey, default to main key options. e.g. [{sign: true, passphrase: '123'}] * @param {Object} config Full configuration * - * @returns {Promise} + * @returns {Promise} * @async * @static + * @private */ export async function reformat(options, config) { options = sanitize(options); diff --git a/src/key/helper.js b/src/key/helper.js index f3e112cb..64669a9f 100644 --- a/src/key/helper.js +++ b/src/key/helper.js @@ -1,10 +1,7 @@ /** * @fileoverview Provides helpers methods for key module - * @requires packet - * @requires enums - * @requires config - * @requires crypto * @module key/helper + * @private */ import { @@ -126,7 +123,7 @@ export async function createBindingSignature(subkey, primaryKey, options, config /** * Returns the preferred signature hash algorithm of a key - * @param {module:key.Key} key (optional) the key to get preferences from + * @param {Key} key (optional) the key to get preferences from * @param {SecretKeyPacket|SecretSubkeyPacket} keyPacket key packet used for signing * @param {Date} date (optional) use the given date for verification instead of the current time * @param {Object} userId (optional) user ID @@ -164,7 +161,7 @@ export async function getPreferredHashAlgo(key, keyPacket, date = new Date(), us /** * Returns the preferred symmetric/aead algorithm for a set of keys * @param {symmetric|aead} type Type of preference to return - * @param {Array} keys Set of keys + * @param {Array} keys Set of keys * @param {Date} date (optional) use the given date for verification instead of the current time * @param {Array} userIds (optional) user IDs * @param {Object} config (optional) full configuration, defaults to openpgp.config @@ -212,7 +209,7 @@ export async function getPreferredAlgo(type, keys, date = new Date(), userIds = * @param {Object} detached (optional) whether to create a detached signature packet * @param {Boolean} streaming (optional) whether to process data as a stream * @param {Object} config full configuration - * @returns {module:packet/signature} signature packet + * @returns {Promise} signature packet */ export async function createSignaturePacket(dataToSign, privateKey, signingKeyPacket, signatureProperties, date, userId, detached = false, streaming = false, config) { if (signingKeyPacket.isDummy()) { @@ -231,7 +228,6 @@ export async function createSignaturePacket(dataToSign, privateKey, signingKeyPa /** * Merges signatures from source[attr] to dest[attr] - * @private * @param {Object} source * @param {Object} dest * @param {String} attr @@ -316,7 +312,7 @@ export function getExpirationTime(keyPacket, signature) { /** * Returns whether aead is supported by all keys in the set - * @param {Array} keys Set of keys + * @param {Array} keys Set of keys * @param {Date} date (optional) use the given date for verification instead of the current time * @param {Array} userIds (optional) user IDs * @param {Object} config full configuration diff --git a/src/key/index.js b/src/key/index.js index 7b036abd..87ddb08f 100644 --- a/src/key/index.js +++ b/src/key/index.js @@ -1,8 +1,3 @@ -/** - * @fileoverview helper, factory methods, constructors dealing with openPGP key object - * @module key - */ - import { readKey, readKeys, diff --git a/src/key/key.js b/src/key/key.js index 7a9b8f69..531d6978 100644 --- a/src/key/key.js +++ b/src/key/key.js @@ -15,16 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires encoding/armor - * @requires packet - * @requires enums - * @requires util - * @requires key/User - * @requires key/Subkey - * @module key/Key - */ - import { armor, unarmor } from '../encoding/armor'; import { PacketList, @@ -166,7 +156,7 @@ class Key { /** * Clones the key object - * @returns {Promise} shallow clone of the key + * @returns {Promise} shallow clone of the key * @async */ async clone() { @@ -177,7 +167,7 @@ class Key { * 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} + * @returns {Array} */ getSubkeys(keyId = null) { const subKeys = []; @@ -193,7 +183,7 @@ class 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} + * @returns {Array} */ getKeys(keyId = null) { const keys = []; @@ -205,7 +195,7 @@ class Key { /** * Returns key IDs of all keys - * @returns {Array} + * @returns {Array} */ getKeyIds() { return this.getKeys().map(key => key.getKeyId()); @@ -240,7 +230,7 @@ class Key { /** * Returns key as public key (shallow copy) * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {module:key.Key} new public Key + * @returns {Key} new public Key */ toPublic() { const packetlist = new PacketList(); @@ -281,11 +271,11 @@ class Key { /** * Returns last created key or key by given keyId that is available for signing and verification - * @param {module:type/keyid} keyId, optional + * @param {module:type/keyid~Keyid} keyId, optional * @param {Date} date (optional) use the given date for verification instead of the current time * @param {Object} userId, optional user ID * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} key or null if no signing key has been found + * @returns {Promise} key or null if no signing key has been found * @async */ async getSigningKey(keyId = null, date = new Date(), userId = {}, config = defaultConfig) { @@ -322,11 +312,11 @@ class Key { /** * Returns last created key or key by given keyId that is available for encryption or decryption - * @param {module:type/keyid} keyId, optional + * @param {module:type/keyid~Keyid} keyId, optional * @param {Date} date, optional * @param {String} userId, optional * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} key or null if no encryption key has been found + * @returns {Promise} key or null if no encryption key has been found * @async */ async getEncryptionKey(keyId, date = new Date(), userId = {}, config = defaultConfig) { @@ -361,11 +351,11 @@ class Key { /** * Returns all keys that are available for decryption, matching the keyId when given * This is useful to retrieve keys for session key decryption - * @param {module:type/keyid} keyId, optional + * @param {module:type/keyid~Keyid} keyId, optional * @param {Date} date, optional * @param {String} userId, optional * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise>} array of decryption keys + * @returns {Promise>} array of decryption keys * @async */ async getDecryptionKeys(keyId, date = new Date(), userId = {}, config = defaultConfig) { @@ -396,7 +386,7 @@ class Key { /** * Encrypts all secret key and subkey packets matching keyId * @param {String|Array} passphrases - if multiple passphrases, then should be in same order as packets each should encrypt - * @param {module:type/keyid} keyId + * @param {module:type/keyid~Keyid} keyId * @param {Object} config (optional) full configuration, defaults to openpgp.config * @throws {Error} if encryption failed for any key or subkey * @async @@ -422,7 +412,7 @@ class Key { /** * Decrypts all secret key and subkey packets matching keyId * @param {String|Array} passphrases - * @param {module:type/keyid} keyId + * @param {module:type/keyid~Keyid} keyId * @param {Object} config (optional) full configuration, defaults to openpgp.config * @throws {Error} if any matching key or subkey packets did not decrypt successfully * @async @@ -569,7 +559,7 @@ class Key { * Returns null if `capabilities` is passed and the key does not have the specified capabilities or is revoked or invalid. * Returns Infinity if the key doesn't expire. * @param {encrypt|sign|encrypt_sign} capabilities, optional - * @param {module:type/keyid} keyId, optional + * @param {module:type/keyid~Keyid} keyId, optional * @param {Object} userId, optional user ID * @param {Object} config (optional) full configuration, defaults to openpgp.config * @returns {Promise} @@ -607,7 +597,7 @@ class Key { * @param {Date} date (optional) use the given date for verification instead of the current time * @param {Object} userId (optional) user ID to get instead of the primary user, if it exists * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise<{user: module:key.User, + * @returns {Promise<{user: User, * selfCertification: SignaturePacket}>} The primary user and the self signature * @async */ @@ -661,7 +651,7 @@ class Key { * * 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 + * @param {Key} key Source key to merge * @param {Object} config (optional) full configuration, defaults to openpgp.config * @returns {Promise} * @async @@ -728,7 +718,7 @@ class Key { * @param {String} reasonForRevocation.string optional, string explaining the reason for revocation * @param {Date} date optional, override the creationtime of the revocation signature * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} new key with revocation signature + * @returns {Promise} new key with revocation signature * @async */ async revoke( @@ -774,7 +764,7 @@ class Key { * if it is a valid revocation signature. * @param {String} revocationCertificate armored revocation certificate * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} new revoked key + * @returns {Promise} new revoked key * @async */ async applyRevocationCertificate(revocationCertificate, config = defaultConfig) { @@ -803,11 +793,11 @@ class Key { /** * Signs primary user of key - * @param {Array} privateKeys decrypted private keys for signing + * @param {Array} privateKeys decrypted private keys for signing * @param {Date} date (optional) use the given date for verification instead of the current time * @param {Object} userId (optional) user ID to get instead of the primary user, if it exists * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} new public key with new certificate signature + * @returns {Promise} new public key with new certificate signature * @async */ async signPrimaryUser(privateKeys, date, userId, config = defaultConfig) { @@ -820,9 +810,9 @@ class Key { /** * Signs all users of key - * @param {Array} privateKeys decrypted private keys for signing + * @param {Array} privateKeys decrypted private keys for signing * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} new public key with new certificate signature + * @returns {Promise} new public key with new certificate signature * @async */ async signAllUsers(privateKeys, config = defaultConfig) { @@ -838,11 +828,11 @@ class Key { * Verifies primary user of key * - if no arguments are given, verifies the self certificates; * - otherwise, verifies all certificates signed with given keys. - * @param {Array} keys array of keys to verify certificate signatures + * @param {Array} keys array of keys to verify certificate signatures * @param {Date} date (optional) use the given date for verification instead of the current time * @param {Object} userId (optional) user ID to get instead of the primary user, if it exists * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise>} List of signer's keyid and validity of signature * @async */ @@ -858,10 +848,10 @@ class Key { * Verifies all users of key * - if no arguments are given, verifies the self certificates; * - otherwise, verifies all certificates signed with given keys. - * @param {Array} keys array of keys to verify certificate signatures + * @param {Array} keys array of keys to verify certificate signatures * @param {Object} config (optional) full configuration, defaults to openpgp.config * @returns {Promise>} list of userid, signer's keyid and validity of signature * @async */ @@ -892,7 +882,7 @@ class Key { * @param {Date} options.date (optional) Override the creation date of the key and the key signatures * @param {Boolean} options.sign (optional) Indicates whether the subkey should sign rather than encrypt. Defaults to false * @param {Object} options.config (optional) custom configuration settings to overwrite those in openpgp.config - * @returns {Promise} + * @returns {Promise} * @async */ async addSubkey(options = {}) { diff --git a/src/key/subkey.js b/src/key/subkey.js index 368429b8..fecb40a3 100644 --- a/src/key/subkey.js +++ b/src/key/subkey.js @@ -1,8 +1,6 @@ /** - * @requires enums - * @requires key/helper - * @requires packet * @module key/SubKey + * @private */ import enums from '../enums'; @@ -115,7 +113,7 @@ class SubKey { /** * Update subkey with new components from specified subkey - * @param {module:key~SubKey} subKey Source subkey to merge + * @param {SubKey} subKey Source subkey to merge * @param {SecretKeyPacket| SecretSubkeyPacket} primaryKey primary key used for validation * @param {Object} config (optional) full configuration, defaults to openpgp.config @@ -164,7 +162,7 @@ class SubKey { * @param {String} reasonForRevocation.string optional, string explaining the reason for revocation * @param {Date} date optional, override the creationtime of the revocation signature * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} new subkey with revocation signature + * @returns {Promise} new subkey with revocation signature * @async */ async revoke( diff --git a/src/key/user.js b/src/key/user.js index 0ffe2087..7e0329fd 100644 --- a/src/key/user.js +++ b/src/key/user.js @@ -1,9 +1,6 @@ /** - * @requires enums - * @requires util - * @requires packet - * @requires key/helper * @module key/User + * @private */ import enums from '../enums'; @@ -43,9 +40,9 @@ class User { * Signs user * @param {SecretKeyPacket| * PublicKeyPacket} primaryKey The primary key packet - * @param {Array} privateKeys Decrypted private keys for signing + * @param {Array} privateKeys Decrypted private keys for signing * @param {Object} config Full configuration - * @returns {Promise} New user with new certificate signatures + * @returns {Promise} New user with new certificate signatures * @async */ async sign(primaryKey, privateKeys, config) { @@ -102,7 +99,7 @@ class User { * @param {SecretKeyPacket| * PublicKeyPacket} primaryKey The primary key packet * @param {SignaturePacket} certificate A certificate of this user - * @param {Array} keys Array of keys to verify certificate signatures + * @param {Array} keys Array of keys to verify certificate signatures * @param {Date} date Use the given date instead of the current time * @param {Object} config Full configuration * @returns {Promise} status of the certificate @@ -141,10 +138,10 @@ class User { * Verifies all user certificates * @param {SecretKeyPacket| * PublicKeyPacket} primaryKey The primary key packet - * @param {Array} keys Array of keys to verify certificate signatures + * @param {Array} keys Array of keys to verify certificate signatures * @param {Date} date Use the given date instead of the current time * @param {Object} config Full configuration - * @returns {Promise>} List of signer's keyid and validity of signature * @async */ @@ -206,7 +203,7 @@ class User { /** * Update user with new components from specified user - * @param {module:key.User} user Source user to merge + * @param {User} user Source user to merge * @param {SecretKeyPacket| * SecretSubkeyPacket} primaryKey primary key used for validation * @param {Object} config Full configuration diff --git a/src/keyring/index.js b/src/keyring/index.js index 70cca7ee..a775ec18 100644 --- a/src/keyring/index.js +++ b/src/keyring/index.js @@ -1,9 +1,3 @@ -/** - * @fileoverview Functions dealing with storage of the keyring. - * @see module:keyring/keyring - * @see module:keyring/localstore - * @module keyring - */ import Keyring from './keyring.js'; import localstore from './localstore.js'; diff --git a/src/keyring/keyring.js b/src/keyring/keyring.js index 76e93b5a..5582fcb7 100644 --- a/src/keyring/keyring.js +++ b/src/keyring/keyring.js @@ -15,13 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @fileoverview Provides the Keyring class - * @requires key - * @requires keyring/localstore - * @module keyring/keyring - */ - import { readKeys } from '../key'; import defaultConfig from '../config'; import LocalStore from './localstore'; @@ -31,7 +24,7 @@ import LocalStore from './localstore'; */ class KeyArray { /** - * @param {Array} keys The keys to store in this array + * @param {Array} keys The keys to store in this array */ constructor(keys) { this.keys = keys; @@ -40,7 +33,7 @@ class KeyArray { /** * Searches all keys in the KeyArray matching the address or address part of the user ids * @param {String} email email address to search for - * @returns {Array} The public keys associated with provided email address. + * @returns {Array} The public keys associated with provided email address. */ getForAddress(email) { const results = []; @@ -57,7 +50,7 @@ class KeyArray { * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) * @param {Boolean} deep if true search also in subkeys - * @returns {module:key.Key|null} key found or null + * @returns {Key|null} key found or null */ getForId(keyId, deep) { for (let i = 0; i < this.keys.length; i++) { @@ -98,7 +91,7 @@ class KeyArray { /** * Add key to KeyArray - * @param {module:key.Key} key The key that will be added to the keyring + * @param {Key} key The key that will be added to the keyring * @returns {Number} The new length of the KeyArray */ push(key) { @@ -109,7 +102,7 @@ class KeyArray { * Removes a key with the specified keyid from the keyring * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) - * @returns {module:key.Key|null} The key object which has been removed or null + * @returns {Key|null} The key object which has been removed or null */ removeForId(keyId) { for (let i = 0; i < this.keys.length; i++) { @@ -164,7 +157,7 @@ class Keyring { * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) * @param {Boolean} deep if true search also in subkeys - * @returns {Array|null} keys found or null + * @returns {Array|null} keys found or null */ getKeysForId(keyId, deep) { let result = []; @@ -177,7 +170,7 @@ class Keyring { * Removes keys having the specified key id from the keyring * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) - * @returns {Array|null} keys found or null + * @returns {Array|null} keys found or null */ removeKeysForId(keyId) { let result = []; @@ -188,7 +181,7 @@ class Keyring { /** * Get all public and private keys - * @returns {Array} all keys + * @returns {Array} all keys */ getAllKeys() { return this.publicKeys.keys.concat(this.privateKeys.keys); @@ -199,7 +192,7 @@ class Keyring { * Checks a key to see if it matches the specified email address * @private * @param {String} email email address to search for - * @param {module:key.Key} key The key to be checked. + * @param {Key} key The key to be checked. * @returns {Boolean} True if the email address is defined in the specified key */ function emailCheck(email, key) { @@ -222,8 +215,9 @@ function emailCheck(email, key) { * @private * @param {String} keyId provided as string of lowercase hex number * withouth 0x prefix (can be 16-character key ID or fingerprint) - * @param {module:key.Key|module:key.SubKey} key The key to be checked + * @param {Key|SubKey} key The key to be checked * @returns {Boolean} True if key has the specified keyid + * @private */ function keyIdCheck(keyId, key) { if (keyId.length === 16) { diff --git a/src/keyring/localstore.js b/src/keyring/localstore.js index 20b1c93c..25c65dc5 100644 --- a/src/keyring/localstore.js +++ b/src/keyring/localstore.js @@ -16,11 +16,8 @@ // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA /** - * @fileoverview Provides the LocalStore class - * @requires web-stream-tools - * @requires config - * @requires key * @module keyring/localstore + * @private */ import stream from 'web-stream-tools'; @@ -30,6 +27,7 @@ import defaultConfig from '../config'; /** * The class that deals with storage of the keyring. * Currently the only option is to use HTML5 local storage. + * @private */ class LocalStore { /** @@ -49,7 +47,7 @@ class LocalStore { /** * Load the public keys from HTML5 local storage. - * @returns {Array} array of keys retrieved from localstore + * @returns {Array} array of keys retrieved from localstore * @async */ async loadPublic(config = defaultConfig) { @@ -59,7 +57,7 @@ class LocalStore { /** * Load the private keys from HTML5 local storage. * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Array} array of keys retrieved from localstore + * @returns {Array} array of keys retrieved from localstore * @async */ async loadPrivate(config = defaultConfig) { @@ -69,7 +67,7 @@ class LocalStore { /** * Saves the current state of the public keys to HTML5 local storage. * The key array gets stringified using JSON - * @param {Array} keys array of keys to save in localstore + * @param {Array} keys array of keys to save in localstore * @param {Object} config (optional) full configuration, defaults to openpgp.config * @async */ @@ -80,7 +78,7 @@ class LocalStore { /** * Saves the current state of the private keys to HTML5 local storage. * The key array gets stringified using JSON - * @param {Array} keys array of keys to save in localstore + * @param {Array} keys array of keys to save in localstore * @param {Object} config (optional) full configuration, defaults to openpgp.config * @async */ diff --git a/src/message.js b/src/message.js index d51b561e..dd5ff311 100644 --- a/src/message.js +++ b/src/message.js @@ -15,20 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires web-stream-tools - * @requires encoding/armor - * @requires type/keyid - * @requires config - * @requires crypto - * @requires enums - * @requires util - * @requires packet - * @requires signature - * @requires key - * @module message - */ - import stream from 'web-stream-tools'; import { armor, unarmor } from './encoding/armor'; import type_keyid from './type/keyid'; @@ -59,7 +45,7 @@ import { getPreferredHashAlgo, getPreferredAlgo, isAeadSupported, createSignatur */ export class Message { /** - * @param {module:PacketList} packetlist The packets that form this message + * @param {PacketList} packetlist The packets that form this message */ constructor(packetlist) { this.packets = packetlist || new PacketList(); @@ -67,7 +53,7 @@ export class Message { /** * Returns the key IDs of the keys to which the session key is encrypted - * @returns {Array} array of keyid objects + * @returns {Array} array of keyid objects */ getEncryptionKeyIds() { const keyIds = []; @@ -80,7 +66,7 @@ export class Message { /** * Returns the key IDs of the keys that signed the message - * @returns {Array} array of keyid objects + * @returns {Array} array of keyid objects */ getSigningKeyIds() { const keyIds = []; @@ -311,7 +297,7 @@ export class Message { * @param {Array} passwords (optional) password(s) for message encryption * @param {Object} sessionKey (optional) session key in the form: { data:Uint8Array, algorithm:String, [aeadAlgorithm:String] } * @param {Boolean} wildcard (optional) use a key ID of 0 instead of the public key IDs - * @param {Array} encryptionKeyIds (optional) array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i] + * @param {Array} encryptionKeyIds (optional) array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i] * @param {Date} date (optional) override the creation date of the literal package * @param {Array} userIds (optional) user IDs to encrypt for, e.g. [{ name:'Robert Receiver', email:'robert@openpgp.org' }] * @param {Boolean} streaming (optional) whether to process data as a stream @@ -362,7 +348,7 @@ export class Message { * @param {Array} publicKeys (optional) public key(s) for message encryption * @param {Array} passwords (optional) for message encryption * @param {Boolean} wildcard (optional) use a key ID of 0 instead of the public key IDs - * @param {Array} encryptionKeyIds (optional) array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i] + * @param {Array} encryptionKeyIds (optional) array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i] * @param {Date} date (optional) override the date * @param {Array} userIds (optional) user IDs to encrypt for, e.g. [{ name:'Robert Receiver', email:'robert@openpgp.org' }] * @param {Object} config (optional) full configuration, defaults to openpgp.config @@ -427,9 +413,9 @@ export class Message { /** * Sign the message (the literal data packet of the message) - * @param {Array} privateKeys private keys with decrypted secret key data for signing + * @param {Array} privateKeys private keys with decrypted secret key data for signing * @param {Signature} signature (optional) any existing detached signature to add to the message - * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] + * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] * @param {Date} date (optional) override the creation time of the signature * @param {Array} userIds (optional) user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }] * @param {Boolean} streaming (optional) whether to process data as a stream @@ -495,7 +481,7 @@ export class Message { /** * Compresses the message (the literal and -if signed- signature data packets of the message) * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {module:message.Message} new message with compressed content + * @returns {Message} new message with compressed content */ compress(config = defaultConfig) { if (config.compression === enums.compression.uncompressed) { @@ -513,14 +499,14 @@ export class Message { /** * Create a detached signature for the message (the literal data packet of the message) - * @param {Array} privateKeys private keys with decrypted secret key data for signing + * @param {Array} privateKeys private keys with decrypted secret key data for signing * @param {Signature} signature (optional) any existing detached signature - * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] + * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] * @param {Date} date (optional) override the creation time of the signature * @param {Array} userIds (optional) user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }] * @param {Boolean} streaming (optional) whether to process data as a stream * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} new detached signature of message content + * @returns {Promise} new detached signature of message content * @async */ async signDetached(privateKeys = [], signature = null, signingKeyIds = [], date = new Date(), userIds = [], streaming = false, config = defaultConfig) { @@ -533,11 +519,11 @@ export class Message { /** * Verify message signatures - * @param {Array} keys array of keys to verify signatures + * @param {Array} keys array of keys to verify signatures * @param {Date} date (optional) Verify the signature against the given date, i.e. check signature creation time < date < expiration time * @param {Boolean} streaming (optional) whether to process data as a stream * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise>} list of signer's keyid and validity of signature + * @returns {Promise>} list of signer's keyid and validity of signature * @async */ async verify(keys, date = new Date(), streaming, config = defaultConfig) { @@ -586,11 +572,11 @@ export class Message { /** * Verify detached message signature - * @param {Array} keys array of keys to verify signatures + * @param {Array} keys array of keys to verify signatures * @param {Signature} signature * @param {Date} date Verify the signature against the given date, i.e. check signature creation time < date < expiration time * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise>} list of signer's keyid and validity of signature + * @returns {Promise>} list of signer's keyid and validity of signature * @async */ verifyDetached(signature, keys, date = new Date(), streaming, config = defaultConfig) { @@ -605,7 +591,7 @@ export class Message { /** * Unwrap compressed message - * @returns {module:message.Message} message Content of compressed message + * @returns {Message} message Content of compressed message */ unwrapCompressed() { const compressed = this.packets.filterByTag(enums.packet.compressedData); @@ -646,7 +632,7 @@ export class Message { * @param {String} filename (optional) * @param {Date} date (optional) * @param {utf8|binary|text|mime} type (optional) data packet type - * @returns {module:message.Message} new message object + * @returns {Message} new message object * @static */ static fromText(text, filename, date = new Date(), type = 'utf8') { @@ -673,7 +659,7 @@ export class Message { * @param {String} filename (optional) * @param {Date} date (optional) * @param {utf8|binary|text|mime} type (optional) data packet type - * @returns {module:message.Message} new message object + * @returns {Message} new message object * @static */ static fromBinary(bytes, filename, date = new Date(), type = 'binary') { @@ -700,17 +686,18 @@ export class Message { /** * Create signature packets for the message - * @param {LiteralDataPacket} literalDataPacket the literal data packet to sign - * @param {Array} privateKeys private keys with decrypted secret key data for signing + * @param {LiteralDataPacket} literalDataPacket the literal data packet to sign + * @param {Array} privateKeys private keys with decrypted secret key data for signing * @param {Signature} signature (optional) any existing detached signature to append - * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] + * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] * @param {Date} date (optional) override the creationtime of the signature * @param {Array} userIds (optional) user IDs to sign with, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }] * @param {Boolean} detached (optional) whether to create detached signature packets * @param {Boolean} streaming (optional) whether to process data as a stream * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise} list of signature packets + * @returns {Promise} list of signature packets * @async + * @private */ export async function createSignaturePackets(literalDataPacket, privateKeys, signature = null, signingKeyIds = [], date = new Date(), userIds = [], detached = false, streaming = false, config = defaultConfig) { const packetlist = new PacketList(); @@ -741,14 +728,15 @@ export async function createSignaturePackets(literalDataPacket, privateKeys, sig * Create object containing signer's keyid and validity of signature * @param {SignaturePacket} signature signature packets * @param {Array} literalDataList array of literal data packets - * @param {Array} keys array of keys to verify signatures + * @param {Array} keys array of keys to verify signatures * @param {Date} date Verify the signature against the given date, * i.e. check signature creation time < date < expiration time * @param {Boolean} detached (optional) whether to verify detached signature packets * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise>} list of signer's keyid and validity of signature * @async + * @private */ async function createVerificationObject(signature, literalDataList, keys, date = new Date(), detached = false, streaming = false, config = defaultConfig) { let primaryKey = null; @@ -803,14 +791,15 @@ async function createVerificationObject(signature, literalDataList, keys, date = * Create list of objects containing signer's keyid and validity of signature * @param {Array} signatureList array of signature packets * @param {Array} literalDataList array of literal data packets - * @param {Array} keys array of keys to verify signatures + * @param {Array} keys array of keys to verify signatures * @param {Date} date Verify the signature against the given date, * i.e. check signature creation time < date < expiration time * @param {Boolean} detached (optional) whether to verify detached signature packets * @param {Object} config (optional) full configuration, defaults to openpgp.config - * @returns {Promise>} list of signer's keyid and validity of signature * @async + * @private */ export async function createVerificationObjects(signatureList, literalDataList, keys, date = new Date(), detached = false, streaming = false, config = defaultConfig) { return Promise.all(signatureList.filter(function(signature) { diff --git a/src/openpgp.js b/src/openpgp.js index da1dd25c..8fb44e76 100644 --- a/src/openpgp.js +++ b/src/openpgp.js @@ -15,29 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @fileoverview The openpgp base module should provide all of the functionality - * to consume the openpgp.js library. All additional classes are documented - * for extending and developing on top of the base library. - * @requires web-stream-tools - * @requires message - * @requires cleartext - * @requires key - * @requires config - * @requires enums - * @requires util - * @requires polyfills - * @module openpgp - */ - -// This file intentionally has two separate file overviews so that -// a reference to this module appears at the end of doc/index.html. - -/** - * @fileoverview To view the full API documentation, start from - * {@link module:openpgp} - */ - import stream from 'web-stream-tools'; import { createReadableStreamWrapper } from '@mattiasbuelens/web-streams-adapter'; import { Message } from './message'; @@ -258,8 +235,8 @@ export async function encryptKey({ privateKey, passphrase, config }) { * @param {'web'|'ponyfill'|'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) a detached signature to add to the encrypted message * @param {Boolean} wildcard (optional) use a key ID of 0 instead of the public key IDs - * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] - * @param {Array} encryptionKeyIds (optional) array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i] + * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] + * @param {Array} encryptionKeyIds (optional) array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i] * @param {Date} date (optional) override the creation date of the message signature * @param {Array} fromUserIds (optional) array of user IDs to sign with, one per key in `privateKeys`, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }] * @param {Array} toUserIds (optional) array of user IDs to encrypt for, one per key in `publicKeys`, e.g. [{ name:'Robert Receiver', email:'robert@openpgp.org' }] @@ -310,7 +287,7 @@ export function encrypt({ message, publicKeys, privateKeys, passwords, sessionKe * filename: String, * signatures: [ * { - * keyid: module:type/keyid, + * keyid: module:type/keyid~Keyid, * verified: Promise, * valid: Boolean (if streaming was false) * }, ... @@ -354,7 +331,7 @@ export function decrypt({ message, privateKeys, passwords, sessionKeys, publicKe * @param {Boolean} armor (optional) whether the return values should be ascii armored (true, the default) or binary (false) * @param {'web'|'ponyfill'|'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 {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] + * @param {Array} signingKeyIds (optional) array of key IDs to use for signing. Each signingKeyIds[i] corresponds to privateKeys[i] * @param {Date} date (optional) override the creation date of the signature * @param {Array} fromUserIds (optional) array of user IDs to sign with, one per key in `privateKeys`, e.g. [{ name:'Steve Sender', email:'steve@openpgp.org' }] * @param {Object} config (optional) custom configuration settings to overwrite those in openpgp.config @@ -407,7 +384,7 @@ export function sign({ message, privateKeys, armor = true, streaming = message & * data: Uint8Array|ReadableStream|NodeStream, (if `message` was a Message) * signatures: [ * { - * keyid: module:type/keyid, + * keyid: module:type/keyid~Keyid, * verified: Promise, * valid: Boolean (if `streaming` was false) * }, ... @@ -475,7 +452,7 @@ export function generateSessionKey({ publicKeys, date = new Date(), toUserIds = * @param {String|Array} passwords (optional) passwords for the message * @param {Boolean} armor (optional) whether the return values should be ascii armored (true, the default) or binary (false) * @param {Boolean} wildcard (optional) use a key ID of 0 instead of the public key IDs - * @param {Array} encryptionKeyIds (optional) array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i] + * @param {Array} encryptionKeyIds (optional) array of key IDs to use for encryption. Each encryptionKeyIds[i] corresponds to publicKeys[i] * @param {Date} date (optional) override the date * @param {Array} toUserIds (optional) array of user IDs to encrypt for, one per key in `publicKeys`, e.g. [{ name:'Phil Zimmermann', email:'phil@openpgp.org' }] * @param {Object} config (optional) custom configuration settings to overwrite those in openpgp.config @@ -529,6 +506,7 @@ export function decryptSessionKeys({ message, privateKeys, passwords, config }) /** * Input validation + * @private */ function checkString(data, name) { if (!util.isString(data)) { @@ -555,6 +533,7 @@ function checkCleartextOrMessage(message) { * Normalize parameter to an array if it is not undefined. * @param {Object} param the parameter to be normalized * @returns {Array|undefined} the resulting array or undefined + * @private */ function toArray(param) { if (param && !util.isArray(param)) { @@ -569,6 +548,7 @@ function toArray(param) { * @param {'web'|'ponyfill'|'node'|false} streaming (optional) whether to return a ReadableStream, and of what type * @param {'utf8'|'binary'} encoding (optional) how to return data in Node Readable streams * @returns {Object} the data in the respective format + * @private */ async function convertStream(data, streaming, encoding = 'utf8') { let streamType = util.isStream(data); @@ -596,6 +576,7 @@ async function convertStream(data, streaming, encoding = 'utf8') { * @param {Object} result the data to convert * @param {Message} message message object * @returns {Object} + * @private */ function linkStreams(result, message) { result.data = stream.transformPair(message.packets.stream, async (readable, writable) => { @@ -616,6 +597,7 @@ function linkStreams(result, message) { /** * Wait until signature objects have been verified * @param {Object} signatures list of signatures + * @private */ async function prepareSignatures(signatures) { await Promise.all(signatures.map(async signature => { @@ -635,6 +617,7 @@ async function prepareSignatures(signatures) { * Global error handler that logs the stack trace and rethrows a high lvl error message. * @param {String} message A human readable high level error Message * @param {Error} error The internal error that caused the failure + * @private */ function onError(message, error) { // log the stack trace diff --git a/src/packet/aead_encrypted_data.js b/src/packet/aead_encrypted_data.js index dd88e0ba..4045f4f6 100644 --- a/src/packet/aead_encrypted_data.js +++ b/src/packet/aead_encrypted_data.js @@ -15,15 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires web-stream-tools - * @requires config - * @requires crypto - * @requires enums - * @requires util - * @requires packet - */ - import stream from 'web-stream-tools'; import crypto from '../crypto'; import enums from '../enums'; @@ -44,7 +35,6 @@ const VERSION = 1; // A one-octet version number of the data packet. * * {@link https://tools.ietf.org/html/draft-ford-openpgp-format-00#section-2.1}: * AEAD Protected Data Packet - * @memberof module:packet */ class AEADEncryptedDataPacket { constructor() { diff --git a/src/packet/all_packets.js b/src/packet/all_packets.js index 1cfacb87..6828b809 100644 --- a/src/packet/all_packets.js +++ b/src/packet/all_packets.js @@ -1,82 +1,30 @@ /** * @fileoverview Exports all OpenPGP packet types - * @requires enums * @module packet/all_packets + * @private */ -export { - /** @see CompressedDataPacket */ - default as CompressedDataPacket -} from './compressed_data.js'; -export { - /** @see SymEncryptedIntegrityProtectedDataPacket */ - default as SymEncryptedIntegrityProtectedDataPacket -} from './sym_encrypted_integrity_protected_data.js'; -export { - /** @see AEADEncryptedDataPacket */ - default as AEADEncryptedDataPacket -} from './aead_encrypted_data.js'; -export { - /** @see PublicKeyEncryptedSessionKeyPacket */ - default as PublicKeyEncryptedSessionKeyPacket -} from './public_key_encrypted_session_key.js'; -export { - /** @see SymEncryptedSessionKeyPacket */ - default as SymEncryptedSessionKeyPacket -} from './sym_encrypted_session_key.js'; -export { - /** @see LiteralDataPacket */ - default as LiteralDataPacket -} from './literal_data.js'; -export { - /** @see PublicKeyPacket */ - default as PublicKeyPacket -} from './public_key.js'; -export { - /** @see SymmetricallyEncryptedDataPacket */ - default as SymmetricallyEncryptedDataPacket -} from './symmetrically_encrypted_data.js'; -export { - /** @see MarkerPacket */ - default as MarkerPacket -} from './marker.js'; -export { - /** @see PublicSubkeyPacket */ - default as PublicSubkeyPacket -} from './public_subkey.js'; -export { - /** @see UserAttributePacket */ - default as UserAttributePacket -} from './user_attribute.js'; -export { - /** @see OnePassSignaturePacket */ - default as OnePassSignaturePacket -} from './one_pass_signature.js'; -export { - /** @see SecretKeyPacket */ - default as SecretKeyPacket -} from './secret_key.js'; -export { - /** @see UserIDPacket */ - default as UserIDPacket -} from './userid.js'; -export { - /** @see SecretSubkeyPacket */ - default as SecretSubkeyPacket -} from './secret_subkey.js'; -export { - /** @see SignaturePacket */ - default as SignaturePacket -} from './signature.js'; -export { - /** @see TrustPacket */ - default as TrustPacket -} from './trust.js'; +export { default as CompressedDataPacket } from './compressed_data.js'; +export { default as SymEncryptedIntegrityProtectedDataPacket } from './sym_encrypted_integrity_protected_data.js'; +export { default as AEADEncryptedDataPacket } from './aead_encrypted_data.js'; +export { default as PublicKeyEncryptedSessionKeyPacket } from './public_key_encrypted_session_key.js'; +export { default as SymEncryptedSessionKeyPacket } from './sym_encrypted_session_key.js'; +export { default as LiteralDataPacket } from './literal_data.js'; +export { default as PublicKeyPacket } from './public_key.js'; +export { default as SymmetricallyEncryptedDataPacket } from './symmetrically_encrypted_data.js'; +export { default as MarkerPacket } from './marker.js'; +export { default as PublicSubkeyPacket } from './public_subkey.js'; +export { default as UserAttributePacket } from './user_attribute.js'; +export { default as OnePassSignaturePacket } from './one_pass_signature.js'; +export { default as SecretKeyPacket } from './secret_key.js'; +export { default as UserIDPacket } from './userid.js'; +export { default as SecretSubkeyPacket } from './secret_subkey.js'; +export { default as SignaturePacket } from './signature.js'; +export { default as TrustPacket } from './trust.js'; /** * Allocate a new packet * @function newPacketFromTag - * @memberof module:packet * @param {String} tag property name from {@link module:enums.packet} * @returns {Object} new packet object with type based on tag */ diff --git a/src/packet/compressed_data.js b/src/packet/compressed_data.js index 9a6f5aca..75be7665 100644 --- a/src/packet/compressed_data.js +++ b/src/packet/compressed_data.js @@ -15,16 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires web-stream-tools - * @requires pako - * @requires seek-bzip - * @requires config - * @requires enums - * @requires util - * @requires packet - */ - import { Deflate } from 'pako/lib/deflate'; import { Inflate } from 'pako/lib/inflate'; import { Z_SYNC_FLUSH, Z_FINISH } from 'pako/lib/zlib/constants'; @@ -46,7 +36,6 @@ import { * The Compressed Data packet contains compressed data. Typically, * this packet is found as the contents of an encrypted packet, or following * a Signature or One-Pass Signature packet, and contains a literal data packet. - * @memberof module:packet */ class CompressedDataPacket { /** diff --git a/src/packet/index.js b/src/packet/index.js index 499e7750..38ed5f4d 100644 --- a/src/packet/index.js +++ b/src/packet/index.js @@ -1,10 +1,2 @@ -/** - * @fileoverview OpenPGP packet types - * @see module:packet/all_packets - * @see module:packet/clone - * @see PacketList - * @module packet - */ - export * from './all_packets'; export { default as PacketList } from './packetlist'; diff --git a/src/packet/literal_data.js b/src/packet/literal_data.js index a662fd8c..ce7fdefc 100644 --- a/src/packet/literal_data.js +++ b/src/packet/literal_data.js @@ -15,12 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires web-stream-tools - * @requires enums - * @requires util - */ - import stream from 'web-stream-tools'; import enums from '../enums'; import util from '../util'; @@ -31,7 +25,6 @@ import util from '../util'; * {@link https://tools.ietf.org/html/rfc4880#section-5.9|RFC4880 5.9}: * A Literal Data packet contains the body of a message; data that is not to be * further interpreted. - * @memberof module:packet */ class LiteralDataPacket { /** diff --git a/src/packet/marker.js b/src/packet/marker.js index 4a4ac80e..7244a3f3 100644 --- a/src/packet/marker.js +++ b/src/packet/marker.js @@ -17,10 +17,6 @@ /* eslint class-methods-use-this: ["error", { "exceptMethods": ["read"] }] */ -/** - * @requires enums - */ - import enums from '../enums'; /** @@ -33,7 +29,6 @@ import enums from '../enums'; * the Marker packet. * * Such a packet MUST be ignored when received. - * @memberof module:packet */ class MarkerPacket { constructor() { diff --git a/src/packet/one_pass_signature.js b/src/packet/one_pass_signature.js index e8c0de91..c2cc11b8 100644 --- a/src/packet/one_pass_signature.js +++ b/src/packet/one_pass_signature.js @@ -15,14 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires web-stream-tools - * @requires packet/signature - * @requires type/keyid - * @requires enums - * @requires util - */ - import stream from 'web-stream-tools'; import SignaturePacket from './signature'; import type_keyid from '../type/keyid'; @@ -38,7 +30,6 @@ import util from '../util'; * hashes needed to verify the signature. It allows the Signature * packet to be placed at the end of the message, so that the signer * can compute the entire signed message in one pass. - * @memberof module:packet */ class OnePassSignaturePacket { constructor() { diff --git a/src/packet/packet.js b/src/packet/packet.js index 912df433..7010c1ae 100644 --- a/src/packet/packet.js +++ b/src/packet/packet.js @@ -19,10 +19,8 @@ /** * @fileoverview Functions for reading and writing packets - * @requires web-stream-tools - * @requires enums - * @requires util * @module packet/packet + * @private */ import stream from 'web-stream-tools'; diff --git a/src/packet/packetlist.js b/src/packet/packetlist.js index 3dc6c958..dcf7872e 100644 --- a/src/packet/packetlist.js +++ b/src/packet/packetlist.js @@ -1,12 +1,3 @@ -/** - * @requires web-stream-tools - * @requires packet/all_packets - * @requires packet/packet - * @requires config - * @requires enums - * @requires util - */ - import stream from 'web-stream-tools'; import * as packets from './all_packets'; import { @@ -22,7 +13,6 @@ import defaultConfig from '../config'; * This class represents a list of openpgp packets. * Take care when iterating over it - the packets themselves * are stored as numerical indices. - * @memberof module:packet * @extends Array */ class PacketList extends Array { @@ -159,7 +149,7 @@ class PacketList extends Array { /** * Traverses packet tree and returns first matching packet * @param {module:enums.packet} type The packet type - * @returns {module:packet/packet|undefined} + * @returns {Packet|undefined} */ findPacket(type) { return this.find(packet => packet.tag === type); diff --git a/src/packet/public_key.js b/src/packet/public_key.js index f9a0b883..5ad5170a 100644 --- a/src/packet/public_key.js +++ b/src/packet/public_key.js @@ -17,14 +17,6 @@ /* eslint class-methods-use-this: ["error", { "exceptMethods": ["isDecrypted"] }] */ -/** - * @requires type/keyid - * @requires config - * @requires crypto - * @requires enums - * @requires util - */ - import { Sha1 } from 'asmcrypto.js/dist_es8/hash/sha1/sha1'; import { Sha256 } from 'asmcrypto.js/dist_es8/hash/sha256/sha256'; import type_keyid from '../type/keyid'; @@ -43,7 +35,6 @@ import util from '../util'; * * A Public-Key packet starts a series of packets that forms an OpenPGP * key (sometimes called an OpenPGP certificate). - * @memberof module:packet */ class PublicKeyPacket { /** @@ -88,7 +79,7 @@ class PublicKeyPacket { this.fingerprint = null; /** * Keyid - * @type {module:type/keyid} + * @type {module:type/keyid~Keyid} */ this.keyid = null; } @@ -185,7 +176,7 @@ class PublicKeyPacket { /** * Calculates the key id of the key - * @returns {module:type/keyid} A 8 byte key id + * @returns {module:type/keyid~Keyid} A 8 byte key id */ getKeyId() { if (this.keyid) { diff --git a/src/packet/public_key_encrypted_session_key.js b/src/packet/public_key_encrypted_session_key.js index f414007a..3bb8357a 100644 --- a/src/packet/public_key_encrypted_session_key.js +++ b/src/packet/public_key_encrypted_session_key.js @@ -15,13 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires type/keyid - * @requires crypto - * @requires enums - * @requires util - */ - import type_keyid from '../type/keyid'; import crypto from '../crypto'; import enums from '../enums'; @@ -42,7 +35,6 @@ import util from '../util'; * The recipient of the message finds a session key that is encrypted to their * public key, decrypts the session key, and then uses the session key to * decrypt the message. - * @memberof module:packet */ class PublicKeyEncryptedSessionKeyPacket { constructor() { diff --git a/src/packet/public_subkey.js b/src/packet/public_subkey.js index cb0bc8f2..a7eae1a9 100644 --- a/src/packet/public_subkey.js +++ b/src/packet/public_subkey.js @@ -15,11 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires packet/public_key - * @requires enums - */ - import PublicKeyPacket from './public_key'; import enums from '../enums'; @@ -29,7 +24,6 @@ import enums from '../enums'; * associated with a top-level key. By convention, the top-level key * provides signature services, and the subkeys provide encryption * services. - * @memberof module:packet * @extends PublicKeyPacket */ class PublicSubkeyPacket extends PublicKeyPacket { diff --git a/src/packet/secret_key.js b/src/packet/secret_key.js index 31bebe15..3c507412 100644 --- a/src/packet/secret_key.js +++ b/src/packet/secret_key.js @@ -15,15 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires packet/public_key - * @requires type/keyid - * @requires type/s2k - * @requires crypto - * @requires enums - * @requires util - */ - import PublicKeyPacket from './public_key'; import type_s2k from '../type/s2k'; import crypto from '../crypto'; @@ -35,7 +26,6 @@ import defaultConfig from '../config'; * A Secret-Key packet contains all the information that is found in a * Public-Key packet, including the public-key material, but also * includes the secret-key material after all the public-key fields. - * @memberof module:packet * @extends PublicKeyPacket */ class SecretKeyPacket extends PublicKeyPacket { diff --git a/src/packet/secret_subkey.js b/src/packet/secret_subkey.js index 49a036c1..c524258a 100644 --- a/src/packet/secret_subkey.js +++ b/src/packet/secret_subkey.js @@ -15,11 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires packet/secret_key - * @requires enums - */ - import SecretKeyPacket from './secret_key'; import enums from '../enums'; import defaultConfig from '../config'; @@ -27,7 +22,6 @@ import defaultConfig from '../config'; /** * A Secret-Subkey packet (tag 7) is the subkey analog of the Secret * Key packet and has exactly the same format. - * @memberof module:packet * @extends SecretKeyPacket */ class SecretSubkeyPacket extends SecretKeyPacket { diff --git a/src/packet/signature.js b/src/packet/signature.js index 8aaf5765..563fb926 100644 --- a/src/packet/signature.js +++ b/src/packet/signature.js @@ -15,15 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires web-stream-tools - * @requires packet/packet - * @requires type/keyid - * @requires crypto - * @requires enums - * @requires util - */ - import stream from 'web-stream-tools'; import { readSimpleLength, writeSimpleLength } from './packet'; import type_keyid from '../type/keyid.js'; @@ -39,7 +30,6 @@ import defaultConfig from '../config'; * A Signature packet describes a binding between some public key and * some data. The most common signatures are a signature of a file or a * block of text, and a signature that is a certification of a User ID. - * @memberof module:packet */ class SignaturePacket { /** diff --git a/src/packet/sym_encrypted_integrity_protected_data.js b/src/packet/sym_encrypted_integrity_protected_data.js index 047854ba..e22ae8b3 100644 --- a/src/packet/sym_encrypted_integrity_protected_data.js +++ b/src/packet/sym_encrypted_integrity_protected_data.js @@ -15,16 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires asmcrypto.js - * @requires web-stream-tools - * @requires config - * @requires crypto - * @requires enums - * @requires util - * @requires packet - */ - import stream from 'web-stream-tools'; import crypto from '../crypto'; import enums from '../enums'; @@ -48,7 +38,6 @@ const VERSION = 1; // A one-octet version number of the data packet. * created for OpenPGP that addresses the problem of detecting a modification to * encrypted data. It is used in combination with a Modification Detection Code * packet. - * @memberof module:packet */ class SymEncryptedIntegrityProtectedDataPacket { constructor() { diff --git a/src/packet/sym_encrypted_session_key.js b/src/packet/sym_encrypted_session_key.js index 0fed869e..f172665e 100644 --- a/src/packet/sym_encrypted_session_key.js +++ b/src/packet/sym_encrypted_session_key.js @@ -15,14 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires type/s2k - * @requires config - * @requires crypto - * @requires enums - * @requires util - */ - import type_s2k from '../type/s2k'; import defaultConfig from '../config'; import crypto from '../crypto'; @@ -41,7 +33,6 @@ import util from '../util'; * The message is encrypted with a session key, and the session key is * itself encrypted and stored in the Encrypted Session Key packet or * the Symmetric-Key Encrypted Session Key packet. - * @memberof module:packet */ class SymEncryptedSessionKeyPacket { /** diff --git a/src/packet/symmetrically_encrypted_data.js b/src/packet/symmetrically_encrypted_data.js index 0edd83d1..e1c41425 100644 --- a/src/packet/symmetrically_encrypted_data.js +++ b/src/packet/symmetrically_encrypted_data.js @@ -15,15 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires web-stream-tools - * @requires config - * @requires crypto - * @requires enums - * @requires util - * @requires packet - */ - import stream from 'web-stream-tools'; import crypto from '../crypto'; import enums from '../enums'; @@ -45,7 +36,6 @@ import defaultConfig from '../config'; * packets (usually a literal data packet or compressed data packet, but in * theory other Symmetrically Encrypted Data packets or sequences of packets * that form whole OpenPGP messages). - * @memberof module:packet */ class SymmetricallyEncryptedDataPacket { constructor() { diff --git a/src/packet/trust.js b/src/packet/trust.js index 14226bd6..fe7e274b 100644 --- a/src/packet/trust.js +++ b/src/packet/trust.js @@ -1,9 +1,5 @@ /* eslint class-methods-use-this: ["error", { "exceptMethods": ["read"] }] */ -/** - * @requires enums - */ - import enums from '../enums'; /** @@ -20,7 +16,6 @@ import enums from '../enums'; * Trust packets SHOULD NOT be emitted to output streams that are * transferred to other users, and they SHOULD be ignored on any input * other than local keyring files. - * @memberof module:packet */ class TrustPacket { constructor() { diff --git a/src/packet/user_attribute.js b/src/packet/user_attribute.js index cba957d7..51db8ce2 100644 --- a/src/packet/user_attribute.js +++ b/src/packet/user_attribute.js @@ -15,12 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires packet - * @requires enums - * @requires util - */ - import { readSimpleLength, writeSimpleLength } from './packet'; import enums from '../enums'; import util from '../util'; @@ -41,7 +35,6 @@ import util from '../util'; * User Attribute packet. A simple way to do this is by treating the * User Attribute packet as a User ID packet with opaque contents, but * an implementation may use any method desired. - * @memberof module:packet */ class UserAttributePacket { constructor() { diff --git a/src/packet/userid.js b/src/packet/userid.js index cb0aad07..1325f3bb 100644 --- a/src/packet/userid.js +++ b/src/packet/userid.js @@ -15,10 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires enums - * @requires util - */ import emailAddresses from 'email-addresses'; import enums from '../enums'; @@ -33,7 +29,6 @@ import defaultConfig from '../config'; * includes an RFC 2822 [RFC2822] mail name-addr, but there are no * restrictions on its content. The packet length in the header * specifies the length of the User ID. - * @memberof module:packet */ class UserIDPacket { constructor() { @@ -52,7 +47,7 @@ class UserIDPacket { /** * Create UserIDPacket instance from object * @param {Object} userId object specifying userId name, email and comment - * @returns {module:userid.UserIDPacket} + * @returns {UserIDPacket} * @static */ static fromObject(userId) { diff --git a/src/polyfills.js b/src/polyfills.js index 1642ee31..7183e0f5 100644 --- a/src/polyfills.js +++ b/src/polyfills.js @@ -1,7 +1,3 @@ -/** - * @module polyfills - */ - if (typeof TextEncoder === 'undefined') { const nodeUtil = require('util') || {}; globalThis.TextEncoder = nodeUtil.TextEncoder; diff --git a/src/signature.js b/src/signature.js index 4f108ef5..cc489747 100644 --- a/src/signature.js +++ b/src/signature.js @@ -15,13 +15,6 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @requires encoding/armor - * @requires packet - * @requires enums - * @module signature - */ - import { armor, unarmor } from './encoding/armor'; import { PacketList, SignaturePacket } from './packet'; import enums from './enums'; diff --git a/src/type/ecdh_symkey.js b/src/type/ecdh_symkey.js index 4ad26724..ae640175 100644 --- a/src/type/ecdh_symkey.js +++ b/src/type/ecdh_symkey.js @@ -18,8 +18,8 @@ /** * Encoded symmetric key for ECDH * - * @requires util * @module type/ecdh_symkey + * @private */ import util from '../util'; diff --git a/src/type/kdf_params.js b/src/type/kdf_params.js index c46619dc..c213cff0 100644 --- a/src/type/kdf_params.js +++ b/src/type/kdf_params.js @@ -23,8 +23,8 @@ * encryption. The Concatenation Key Derivation Function (Approved * Alternative 1) [NIST-SP800-56A] with the KDF hash function that is * SHA2-256 [FIPS-180-3] or stronger is REQUIRED. - * @requires enums * @module type/kdf_params + * @private */ class KDFParams { diff --git a/src/type/keyid.js b/src/type/keyid.js index 5b2719eb..ede4b8d8 100644 --- a/src/type/keyid.js +++ b/src/type/keyid.js @@ -15,6 +15,13 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA +/** + * @module type/keyid + * @private + */ + +import util from '../util.js'; + /** * Implementation of type key id * @@ -23,12 +30,7 @@ * Implementations SHOULD NOT assume that Key IDs are unique. The * section "Enhanced Key Formats" below describes how Key IDs are * formed. - * @requires util - * @module type/keyid */ - -import util from '../util.js'; - class Keyid { constructor() { this.bytes = ''; diff --git a/src/type/oid.js b/src/type/oid.js index 7316bd86..ecf13d43 100644 --- a/src/type/oid.js +++ b/src/type/oid.js @@ -29,9 +29,8 @@ * 86 48 CE 3D 03 01 07", from which the first entry in the table above * is constructed by omitting the first two octets. Only the truncated * sequence of octets is the valid representation of a curve OID. - * @requires util - * @requires enums * @module type/oid + * @private */ import util from '../util'; diff --git a/src/type/s2k.js b/src/type/s2k.js index d087168f..363ba7dc 100644 --- a/src/type/s2k.js +++ b/src/type/s2k.js @@ -24,11 +24,8 @@ * places, currently: to encrypt the secret part of private keys in the * private keyring, and to convert passphrases to encryption keys for * symmetrically encrypted messages. - * @requires config - * @requires crypto - * @requires enums - * @requires util * @module type/s2k + * @private */ import defaultConfig from '../config'; diff --git a/src/util.js b/src/util.js index 409a3b19..8d59e753 100644 --- a/src/util.js +++ b/src/util.js @@ -19,10 +19,8 @@ /** * This object contains utility functions - * @requires email-addresses - * @requires web-stream-tools - * @requires encoding/base64 * @module util + * @private */ import stream from 'web-stream-tools'; diff --git a/src/wkd.js b/src/wkd.js index dfd096fd..b0fb35f5 100644 --- a/src/wkd.js +++ b/src/wkd.js @@ -15,17 +15,15 @@ // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -/** - * @fileoverview This class implements a client for the Web Key Directory (wkd) protocol - * in order to lookup keys on designated servers. - * See: https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ - * @module wkd - */ - import util from './util'; import crypto from './crypto'; import { readKeys } from './key'; +/** + * This class implements a client for the Web Key Directory (WKD) protocol + * in order to lookup keys on designated servers. + * @see https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ + */ class WKD { /** * Initialize the WKD client @@ -39,7 +37,7 @@ class WKD { * @param {String} options.email User's email. * @param {Boolean} options.rawBytes Returns Uint8Array instead of parsed key. * @returns {Promise, + * {keys: Array, * err: (Array|null)}>} The public key. * @async */