Determine whether AEAD should be used for encryption solely based the encryption key preferences.
Previously, the config flag was also used to control the behaviour, since AEAD messages were not standardised nor widely supported.
To generate keys that declare AEAD in their preferences, use `generateKey` with `config.aeadProtect = true`.
This special cipher value can be relevant for unencrypted private keys:
https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#section-12.2.1 .
However, it is no longer used internally, and on the contrary it could cause
confusion on SKESK decryption, where "random" cipher algos are returned in case
of wrong password.
This change also fixes a flaky test on password-based decryption, caused by the
PKESK v6 changes which add support for `null` cipher algos. The code did not
distinguish between a `null` and a `0` (plaintext) algo identifier, and would
break when the latter was returned on SKESK decryption.
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').
The crypto refresh says that we MUST NOT reject messages where the
CRC24 checksum is incorrect. So, we remove the check for it.
Also, remove the checksumRequired config.
Mocha v10 requires the lib to be esm compliant.
ESM mandates the use of file extensions in imports, so to minimize the
changes (for now), we rely on the flag `experimental-specifier-resolution=node`
and on `ts-node` (needed only for Node 20).
Breaking changes:
downstream bundlers might be affected by the package.json changes depending on
how they load the library.
NB: legacy package.json entrypoints are still available.
In terms of API, this feature is backwards compatible, no breaking changes.
However, since a Wasm module is loaded for the Argon2 computation, browser apps
might need to make changes to their CSP policy in order to use the feature.
Newly introduced config fields:
- `config.s2kType` (defaulting to `enums.s2k.iterated`): s2k to use on
password-based encryption as well as private key encryption;
- `config.s2kArgon2Params` (defaulting to "uniformly safe settings" from Argon
RFC): parameters to use on encryption when `config.s2kType` is set to
`enums.s2k.argon2`;
As specified in openpgp-crypto-refresh-09.
Instead of encoding the symmetric key algorithm in the PKESK ciphertext (requiring padding),
the symmetric key algorithm is left unencrypted.
Co-authored-by: Lukas Burkhalter <lukas.burkhalter@proton.ch>
Such keys are still capable of encryption and signature verification.
This change is relevant for forward compatibility of v4 keys encrypted using e.g. argon2.
Most rules are derived from the `airbnb` template.
Some "bad" rule exceptions remain, but they require too many changes to fix, so
we leave it to a future refactoring.
The changes do not affect the public API:
`RandomBuffer` was used internally for secure randomness generation before
`crypto.getRandomValues` was made available to WebWorkers, requiring
generating randomness in the main thread.
As a result of the change, the internal `getRandomBytes()` and some functions
that use it are no longer async.
Calling `openpgp.decrypt` with a message that contains encrypted session keys
followed by a non-encrypted packet (e.g. Literal or Compressed Data packet)
used to succeed, even if a wrong passphrase/key was provided.
With this change, the operation will always fail, and the user is warned that
the data was not encrypted.
NB: a message that did not contain any encrypted session key packet would fail
to decrypt even prior to this change.
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.
Implement optional constant-time decryption flow to hinder Bleichenbacher-like
attacks against RSA- and ElGamal public-key encrypted session keys.
Changes:
- Add `config.constantTimePKCS1Decryption` to enable the constant-time
processing (defaults to `false`). The constant-time option is off by default
since it has measurable performance impact on message decryption, and it is
only helpful in specific application scenarios (more info below).
- Add `config.constantTimePKCS1DecryptionSupportedSymmetricAlgorithms`
(defaults to the AES algorithms). The set of supported ciphers is restricted by
default since the number of algorithms negatively affects performance.
Bleichenbacher-like attacks are of concern for applications where both of the
following conditions are met:
1. new/incoming messages are automatically decrypted (without user
interaction);
2. an attacker can determine how long it takes to decrypt each message (e.g.
due to decryption errors being logged remotely).
In several packet classes, we used to store string identifiers for public-key,
aead, cipher or hash algorithms. To make the code consistent and to avoid
having to convert to/from string values, we now always store integer values
instead, e.g. `enums.symmetric.aes128` is used instead of `'aes128'`.
This is not expected to be a breaking change for most library users. Note that
the type of `Key.getAlgorithmInfo()` and of the session key objects returned
and accepted by top-level functions remain unchanged.
Affected classes (type changes for some properties and method's arguments):
- `PublicKeyPacket`, `PublicSubkeyPacket`, `SecretKeyPacket`,
`SecretSubkeyPacket`
- `SymEncryptedIntegrityProtectedDataPacket`, `AEADEncryptedDataPacket`,
`SymmetricallyEncryptedDataPacket`
- `LiteralDataPacket`, `CompressedDataPacket`
- `PublicKeyEncryptedSessionKey`, `SymEncryptedSessionKeyPacket`
- `SignaturePacket`
Other potentially breaking changes:
- Removed property `AEADEncryptedDataPacket.aeadAlgo`, since it was redudant
given `.aeadAlgorithm`.
- Renamed `AEADEncryptedDataPacket.cipherAlgo` -> `.cipherAlgorithm`
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
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.
API changes:
- `Key.isPublic()` has been removed, since it was redundant and it would
introduce TypeScript issues. Call `!Key.isPrivate()` instead.
TypeScript changes:
- the `openpgp.readKey(s)` functions are now declared as returning a `Key`
instead of a `PublicKey`. This is just a readability improvement to make it
clearer that the result could also be a `PrivateKey`.
- All `Key` methods that return a key object now have the narrowest possible
return type.
- The `Key.isPrivate()` method can now be used for type inference, allowing the
compiler to distinguish between `PrivateKey` and `PublicKey`.
Calling `key.isPrivate()` is the recommended way of distinguishing between a
`PrivateKey` and `PublicKey` at runtime, over using `key instanceof ...`, since
the latter depends on the specifics of the `Key` class hierarchy.
- `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.
- Fix#1159: `Key.verifyPrimaryKey` considers expiration time subpackets in
direct-key signatures to determine whether the key is expired.
- `Key.getExpirationTime()` does not take the `capabilities` and `keyID` arguments
anymore, and simply returns the expiration date of the primary key. Also, like
for `verifyPrimaryKey`, direct-key signatures are now taken into account.
- Keys and signatures are considered expired at the time of expiry, instead of
one second later.
Breaking change:
`Key.getExpirationTime(capabilities, keyID, userID, config)` ->
`.getExpirationTime(userID, config)`
- `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`
This change allows us to only load the `ReadableStream` polyfill when
needed without behaving inconsistently in the external API.
Users of the library should use the global `ReadableStream` or Node.js
`stream.Readable` instead, or import a polyfill if needed. This patch
loosens the detection criteria such that polyfilled streams are better
detected.
- 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
