If given, the signature will be generated using the preferred hash algo from the recipient keys.
Otherwise, the signing key preferences are used (this was also the existing behavior).
Note: when signing through `openpgp.encrypt`, the `encryptionKeys` are automatically used as recipient keys.
In `openpgp.sign`, the signing key preferences are considered instead,
since no "recipient keys" are available.
The hash algo selection logic has been reworked as follows:
if `config.preferredHashAlgo` appears in the prefs of all recipients, we pick it;
otherwise, we use the strongest supported algo (note: SHA256 is always implicitly supported by all keys),
as long as it is compatible with the signing key (e.g. ECC keys require minimum digest sizes).
Previously, only the preferences of the signing key were used to determine the hash algo to use,
but this is in contrast to the RFC: https://www.rfc-editor.org/rfc/rfc9580.html#section-5.2.3.16-2 .
Also, an algo stronger than `config.preferredHashAlgo` would be used, if the signing key
declared it as first preference.
With this change, `config.preferredHashAlgo` is picked even if it's weaker than the
preferences of the recipient keys.
When given a streamed `message` and a detached `signature` in input,
the function would return an empty array as `data` instead of
the input stream, meaning it was not possible to pull it, causing
the `verified` promise to hang indefinitely.
The above issue was introduced v5.0.0-2, and thus affects all v5 releases
up to v5.11.1.
This is a breaking change, as NIST curves identifiers and values in
`enums.curves` have been renamed:
- the identifiers `enums.curve.p256`, `.p384`, `.p521` are now marked as
`@deprecated`
- the new identifiers are, respectively: `enums.curve.nistP256`, `.nistP384`,
`.nistP521`.
- the corresponding values have been changed from `'p256'`,`'p384'`,`'p521'` to
`'nistP256'`, `'nistP384'`, `'nistP521'`.
Affected high-level API functions:
- in `generateKey`, the `options.curve` argument will expect the updated string
values
- `Key.getAlgorithmInfo()` will return the updated `curve` values
Breaking change: all functions taking streams as inputs will now require passing Web Streams in Node.js . If given a native `stream.Readable` input, they will throw. The browser build is unaffected by this change.
Utils to convert from and to Web Streams in Node are available from v17,
see https://nodejs.org/api/stream.html#streamreadabletowebstreamreadable-options .
Previously, we automatically converted between Node native streams and custom, Web-like Readable streams.
This led to occasional issues.
As per the spec, v6 keys must not use the legacy curve25519 format.
The new format is not used by default with v4 keys as it's not compatible with OpenPGP.js older than v5.10.0 .
However, v6 keys already break compatibility, so if the user requests them via config flag, we can safely use the new curve format as well.
Instead of calling getPreferredAlgo('symmetric') and
getPreferredAlgo('aead'), we define and call getPreferredCipherSuite()
to determine the preferred symmetric and AEAD algorithm.
Additionally, we remove isAEADSupported(), instead we return
aeadAlgorithm: undefined from getPreferredCipherSuite() if AEAD is not
supported (CFB is used instead).
And finally, we define getPreferredCompressionAlgo() to replace
getPreferredAlgo('compression').
Assign most signature subpacket types a criticality based on whether
failing to interpret their meaning would negatively impact security.
For Notation Data subpackets, let the user indicate their criticality
using the `signatureNotations[*].critical` property.
Breaking change: `openpgp.encryptKey` now throws if an empty string is given as
passphrase. The operation used to succeed, but the resulting key was left in an
inconsistent state, and e.g. serialization would not be possible.
Non-breaking changes:
- `options.passphrase` in `generateKey` and `reformatKey` now defaults to
`undefined` instead of empty string. Passing an empty string does not throw for
now, but this might change in the future to align with `encryptKey`'s
behaviour.
- In TS, add `GenerateKeyOptions` as alias of `KeyOptions`, to clarify its
scope.
Using `openpgp.reformatKey` with the default `date` option would render
messages signed with the original key unverifiable by OpenPGP.js v5 (not v4),
since the signing key would not be considered valid at the time of signing (due
to its self-certification signature being in the future, compared to the
message signature creation time).
This commit adds `config.allowInsecureVerificationWithReformattedKeys` (false
by default) to make it possible to still verify such messages with the
reformatted key provided the key is valid at the `date` specified for
verification (which defaults to the current time).
Breaking changes:
- throw error on key generation if the requested public key algorithm is
included in `config.rejectPublicKeyAlgorithms`;
- add `config.rejectCurves` to blacklist a set of ECC curves, to prevent keys
using those curves from being generated, or being used to
encrypt/decrypt/sign/verify messages.
By default, `config.rejectCurves` includes the brainpool curves
(`brainpoolP256r1`, `brainpoolP384r1`, `brainpoolP512r1`) and the Bitcoin curve
(`secp256k1`). This is because it's unclear whether these curves will be
standardised[1], and we prefer to blacklist them already, rather than introduce
a breaking change after release.
[1] https://gitlab.com/openpgp-wg/rfc4880bis/-/merge_requests/47#note_634199141
Breaking change: passing non-existing configuration options to top-level
functions now results in an error, to make users aware that the given
configuration cannot be applied.
The `format` option in `openpgp.generateKey, reformatKey, revokeKey, encrypt,
sign, encryptSessionKey` now expects the value `'armored'` instead of `'armor'`
to output armored data. The other format options (i.e. `'binary'` and
`'object'`) remain unchanged.
Breaking changes:
- a new `format` option has been added to `openpgp.encrypt`, `sign` and
`encryptSessionKey` to select the format of the output message. `format`
replaces the existing `armor` option, and accepts three values:
* if `format: 'armor'` (default), an armored signed/encrypted message is
returned (same as `armor: true`).
* if `format: 'binary'`, a binary signed/encrypted message is returned (same
as `armor: false`).
* if `format: 'object'`, a Message or Signature object is returned (this was
not supported before).
This change is to uniform the output format selection across all top-level
functions (following up to #1345).
- All top-level functions now throw if unrecognised options are passed, to make
library users aware that those options are not being applied.
This change is to make the code more consistent between the streaming and
non-streaming cases.
The validity of a signature (or the corresponding verification error) can be
determined through the existing `verified` property.
- Support passing a single Key ID directly to the `encryption/signingKeyIDs`
options of `openpgp.encrypt`, `sign`, `generateSessionKey` and
`encryptSessionKey`.
- Add type definitions for `openpgp.encryptSessionKey` and `decryptSessionKeys`.
- `openpgp.generateKey`, `reformatKey` and `revokeKey` take a new `format`
option, whose possible values are: `'armor', 'binary', 'object'` (default is
`'armor'`).
- `generateKey` and `reformatKey` now return an object of the form `{
publicKey, privateKey, revocationCertificate }`, where the type of `publicKey`
and `privateKey` depends on `options.format`:
* if `format: 'armor'` then `privateKey, publicKey` are armored strings;
* if `format: 'binary'` then `privateKey, publicKey` are `Uint8Array`;
* if `format: 'object'` then `privateKey, publicKey` are `PrivateKey` and
`PublicKey` objects respectively;
- `revokeKey` now returns `{ publicKey, privateKey }`, where:
* if a `PrivateKey` is passed as `key` input, `privateKey, publicKey` are of the
requested format;
* if a `PublicKey` is passed as `key` input, `publicKey` is of the requested format,
while `privateKey` is `null` (previously, in this case the `privateKey` field
was not defined).
Breaking changes:
- In `revokeKey`, if no `format` option is specified, the returned `publicKey,
privateKey` are armored strings (they used to be objects).
- In `generateKey` and `reformatKey`, the `key` value is no longer returned.
- For all three functions, the `publicKeyArmored` and `privateKeyArmored`
values are no longer returned.
- `openpgp.sign` throws if no signing keys are given, instead of returning a
non-signed literal packet.
- Any top-level function error will cause Promise rejection, and can thus be
handled with `.catch()`.
- Throw on signature parsing (e.g. in `openpgp.readSignature`) if the
creation time subpacket is missing
- `SignaturePacket.verify` now directly checks for signature creation
and expiration times. This makes it easier to thoroughly check the
validity of signatures. Also:
- `openpgp.revokeKey` now takes a `date` to check the provided
revocation certificate
- `openpgp.decryptSessionKeys` now takes a `date` to check the
validity of the provided private keys
- whenever a `date` is used internally, the function accepts a
`date` param to allow passing the correct date
- Add tests for all of the above
- Like `openpgp.generateKey`, `openpgp.reformatKey` now also requires
`options.userIDs`
- Simplify calling `SubKey.isRevoked/update/getExpirationTime` by
adding the `SubKey.mainKey` field to hold the reference of the
corresponding `Key`
Breaking changes in low-level functions:
- Added/removed `date` params:
- `Key.update(key, config)` -> `update(key, date, config)`
- `Key.applyRevocationCertificate(revocationCertificate, config)` ->
`applyRevocationCertificate(revocationCertificate, date, config)`
- `Key.signAllUsers(privateKeys, config)` ->
`signAllUsers(privateKeys, date, config)`
- `Key.verifyAllUsers(keys, config)` ->
`verifyAllUsers(keys, date, config)`
- `new SignaturePacket(date)` -> `new SignaturePacket()`
- `SignaturePacket.sign(key, data, detached)` ->
`sign(key, data, date, detached)`
- `Message.sign(primaryKey, privateKeys, config)` ->
`sign(primaryKey, privateKeys, date, config)`
- `Message.decrypt(privateKeys, passwords, sessionKeys, config)` ->
`decrypt(privateKeys, passwords, sessionKeys, date, config)`
- `Message.decryptSessionKeys(privateKeys, passwords, config)` ->
`decryptSessionKeys(privateKeys, passwords, date, config)`
- Removed `primaryKey` params:
- `SubKey.isRevoked(primaryKey, signature, key, date, config)` ->
`isRevoked(signature, key, date, config)`
- `SubKey.update(subKey, primaryKey, date, config)` ->
`update(subKey, date, config)`
- `SubKey.getExpirationTime(primaryKey, date, config)` ->
`getExpirationTime(date, config)`
- Add `PrivateKey` and `PublicKey` classes. A `PrivateKey` can always
be passed where a `PublicKey` key is expected, but not vice versa.
- Unexport `Key`, and export `PrivateKey` and `PublicKey`.
- Rename `Key.packetlist2structure` to `Key.packetListToStructure`.
- Change `Key.update` to return a new updated key, rather than
modifying the destination one in place.
- Add `openpgp.readPrivateKey` and `openpgp.readPrivateKeys` to avoid
having to downcast the result of `readKey(s)` in TypeScript.
- Rename `publicKeys` to `encryptionKeys` or `verificationKeys` depending on their use
- Rename `privateKeys` to `decryptionKeys` or `signingKeys` depending on their use
- Similarly, rename `toUserIDs` to `encryptionUserIDs` and `fromUserIDs` to `signingUserIDs`
- Make fingerprint and key ID computation async, and rely on Web Crypto
for hashing if available
- Always set fingerprint and keyID on key parsing / generation
- Introduce `*KeyPacket.computeFingerprint()` and
`*KeyPacket.computeFingerprintAndKeyID()`
- Change `getKeyID` and `getFingerprint*` functions to return the
pre-computed key ID and fingerprint, respectively
- Make `PublicKeyPacket.read` async
To encrypt/decrypt a key, the top-level functions `openpgp.encryptKey` and
`openpgp.decryptKey` should be used instead: these don't mutate the key;
instead, they either return a new encrypted/decrypted key object or throw an
error.
With `Key.prototype.encrypt` and `decrypt`, which mutated the key, it was
possible to end up in an inconsistent state if some (sub)keys could be
decrypted but others couldn't, they would both mutate the key and throw an
error, which is unexpected.
Note that the `keyID` parameter is not supported by `encryptKey`/`decryptKey`,
since partial key decryption is not recommended. If you still need to decrypt
a single subkey or primary key `k`, you can call `k.keyPacket.decrypt(...)`,
followed by `k.keyPacket.validate(...)`. Similarly, for encryption, call
`k.keyPacket.encrypt(...)`.
Additionally, `openpgp.generateKey` now requires `options.userIDs` again,
since otherwise the key is basically unusable. This was a regression from v4,
since we now allow parsing keys without user IDs (but still not using them).
If `expectSigned` is set:
- `openpgp.decrypt` throws immediately if public keys or signatures are
missing, or if the signatures are invalid and streaming is not used.
- `openpgp.verify` throws immediately if signatures are missing, or if the
signatures are invalid and streaming is not used.
- If the signatures are invalid and streaming is used, reading the returned
data stream will eventually throw.
- Use PascalCase for classes, with uppercase acronyms.
- Use camelCase for function and variables. First word/acronym is always
lowercase, otherwise acronyms are uppercase.
Also, make the packet classes' `tag` properties `static`.
- Rename `config.compression` to `config.preferredCompressionAlgorithm`
- Rename `config.encryptionCipher` to `config.preferredSymmetricAlgorithm`
- Rename `config.preferHashAlgorithm` to `config.preferredHashAlgorithm`
- Rename `config.aeadMode` to `config.preferredAeadAlgorithm`
- When encrypting to public keys, the compression/aead/symmetric algorithm is selected by:
- taking the preferred algorithm specified in config, if it is supported by all recipients
- otherwise, taking the "MUST implement" algorithm specified by rfc4880bis
- When encrypting to passphrases only (no public keys), the preferred algorithms from `config` are always used
- EdDSA signing with a hash algorithm weaker than sha256 is explicitly disallowed (https://tools.ietf.org/id/draft-ietf-openpgp-rfc4880bis-10.html#section-15-7.2)
