Desktop,Mobile,Cli: Support accepting shares with a new key format by personalizedrefrigerator · Pull Request #12829 · laurent22/joplin

personalizedrefrigerator · 2025-07-31T19:25:09Z

Summary

This pull request:

Refactors the E2EE logic to support:
- Interacting with encrypted shares that use different key formats.
- Migrating the ppk field in info.json to a new key format (RSA-OAEP-4096). Note: This migration logic has automated tests, but is disabled.

New key formats (currently disabled)

This pull request allows sharing folders with accounts that use RSA-OAEP for public key encryption. Logic is also added to migrate existing users to this new key format, but is currently disabled (requires a migration step — see note above).

OWASP recommends using elliptical curve cryptography (ECC), where possible, over RSA for asymmetric encryption. However, Joplin’s current mobile cryptographic dependencies (e.g. react-native-quick-crypto) support RSA, but don't seem to support ECC for data encryption/decryption. OWASP also states that “if ECC is not available and RSA must be used, then ensure that the key is at least 2048 bits.”

The parameters for RSA-OAEP can be found in WebCryptoRsa.ts:

Key size: Either 4096 bits or 2048 bits
- .RsaV2: 2048
- .RsaV3: 4096
Hash: SHA-256
Public exponent: 65537 ([1, 0, 1]).

These parameters are based on the RSA DOM example and parameters suggested in the MDN web documentation, which recommend a key size of either at least 2048 or 4096 bits, a public exponent of 65537, and a hash of one of sha-256, sha-384, or sha-512.

Key size notes:

A key size of 2048 results in a plaintext size of 190 bytes¹. Joplin's master keys are 512 bytes hex-encoded strings and 256 bytes when decoded. As such, when the encryption method is .RsaV2, this pull request breaks the input data into blocks and encrypts/decrypts each block individually. This is the same as the approach taken by NodeRSA's long data handler. Unlike NodeRSA, this pull request limits the maximum number of blocks to two. See comments at the top of LongDataWrapper.ts for possible concerns with this approach.
A key size of 4096 is large enough to encrypt Joplin master keys in a single block.

This part of the pull request should be reviewed very carefully before being globally enabled (which would be done in a separate pull request).

Testing plan

Start Joplin Server
Create three Joplin Server accounts (or re-use three existing accounts): self@localhost, self2@localhost, and self3@localhost.
Connect to Joplin Server from the desktop app, enable encryption on the accounts if not done so already.
Share a notebook from self@localhost to self2@localhost.
Open self2@localhost and verify that a share invitation banner is visible, then quit Joplin.
Enable the RSAv2 migration and recompile.
Restart the desktop app.
Verify that the migration completed.
Accept the share.
Verify that the share accepts successfully.
- Note: When first following the testing plan, an error dialog was shown, since the invitation was created with the user’s old public key. As a workaround, the migration logic was updated to cache the old public key as a fallback when decrypting existing share invitations. After making this change, the share was accepted successfully.
Re-disable the PPK migration and recompile.
Switch to self3@localhost (in a different profile), sign in to Joplin Server if not done so already.
Switch back to self2@localhost, share a folder with self3@localhost and sync.
Switch to self1@localhost, share a folder with self3@localhost and sync.
Switch back to self3@localhost, accept the share from self2@localhost.
Re-enable the RSAv2 migration and recompile.
Restart the desktop app.
Accept the share from self1
Sync and verify that both shares were successfully accepted.

It has been verified that the integration tests (see ppkTestUtils.ts) pass on Android 13 and on web (in Chrome).

https://crypto.stackexchange.com/a/42100 ↩

…eb, add more tests

This removes the need for a separate "algorithm" property (which would require changes to Joplin Server).

an old one

…logic

See inline comments -- this should improve UX during migration if: 1. Some sharer shares a notebook with client A, targeting client A's PPK. 2. Client A's PPK is migrated. 3. Client A tries to accept the share.

laurent22

Thanks Henry, that looks good I think. I've left a few comments so please take a look

laurent22 · 2025-08-10T08:35:19Z

packages/lib/services/e2ee/ppk/RSA.node.ts

+	generateKeyPair: async () => {
+		const keys = new NodeRSA();
+		keys.setOptions(legacyRSAOptions);
+		const keySize = 2048;


Any reason not to choose a large key size to make it more future proof? I don't assume that would accept performance much?

Note that this is in the legacyRsa object — it should match the behavior of the old RSA logic. Previously, generateKeyPair took a keySize that was always 2048.

The old generateKeyPair looked like this:

generateKeyPair: async (keySize: number): Promise<RSAKeyPair> => { const keys = new NodeRSA(); keys.setOptions(nodeRSAOptions); keys.generateKeyPair(keySize, 65537); // Sanity check if (!keys.isPrivate()) throw new Error('No private key was generated'); if (!keys.isPublic()) throw new Error('No public key was generated'); return keys; },

The keySize was inlined into generateKeyPair to allow the new RSA logic to use a keySize of 4096 (while keeping the legacy behavior the same).

laurent22 · 2025-08-10T08:52:08Z

packages/lib/services/e2ee/ppk/WebCryptoRsa.ts

+	return text.match(/^[a-f0-9]+$/) && text.length % 2 === 0;
+};
+
+const modulusLengthBits = 4096;


Have you checked the performance of RSA 4096 on mobile? As I understand it can be very slow? And it looks like RSA 2048 is still considered ok till 2030: https://community.rsa.com/s/article/RSA-cryptography-and-NIST-guidance

But it would be good to use 4096 already, provided it doesn't massively impact mobile performance (in my case the app already freezes on startup for 3 seconds, maybe because of encryption/decryption, so I wouldn't want that to becomes 10 seconds+)

Thank you for pointing this out! That would certainly be good to check.

Regarding using a key size of 2048,

2048 results in a plaintext size smaller than Joplin's master keys. According to https://crypto.stackexchange.com/a/42100, a key size of 2048 results in a plaintext size of 190 bytes. Joplin's master keys are 512 bytes hex-encoded, 256 bytes when decoded.

Note: This was also an issue with the old RSA padding format, at least on mobile. Previously, NodeRSA handled the larger input by breaking the input into chunks (in a way that seems to match ECB mode), and encrypting each chunk individually. On mobile, we previously had support for decrypting input data provided in this format, but not encrypting. As a result, the mobile app could not encrypt Joplin master keys (and thus could not create encrypted shares).

provided it doesn't massively impact mobile performance

I've added performance logging to ppkTestUtils:

On an Android emulator, with a key size of 4096, the loadKeys/encrypt/decrypt operations seem to be reasonably fast (<30ms each).

I plan to test on a physical device later today.

Update:

On a physical device, the previously-tested operations have similar performance.

Performance markers from an Android 13 device, with Joplin in development mode:

:38:27: Performance: ppkTestUtils/loadKeys/shortData--legacy: Start at 7.7s Logger.js:261 12:38:27: Performance: ppkTestUtils/loadKeys/shortData--legacy: End at 7.7s (took 1.92ms) Logger.js:261 12:38:27: Performance: ppkTestUtils/decrypt.0/shortData--legacy: Start at 7.7s Logger.js:261 12:38:27: Performance: ppkTestUtils/decrypt.0/shortData--legacy: End at 7.77s (took 67.48ms) Logger.js:261 12:38:27: Performance: ppkTestUtils/encrypt/shortData--legacy: Start at 7.77s Logger.js:261 12:38:27: Performance: ppkTestUtils/encrypt/shortData--legacy: End at 7.79s (took 18.61ms) Logger.js:261 12:38:27: Performance: ppkTestUtils/decrypt.1/shortData--legacy: Start at 7.79s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/shortData--legacy: End at 7.82s (took 24.11ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/longData--legacy: Start at 7.82s Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/longData--legacy: End at 7.82s (took 1.1ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/longData--legacy: Start at 7.82s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/longData--legacy: End at 7.91s (took 88.55ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/longData--legacy: Start at 7.91s Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/longData--legacy: End at 7.92s (took 5.55ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/longData--legacy: Start at 7.92s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/longData--legacy: End at 7.94s (took 26.69ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/blockAlignedData--legacy: Start at 7.95s Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/blockAlignedData--legacy: End at 7.95s (took 1.04ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/blockAlignedData--legacy: Start at 7.96s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/blockAlignedData--legacy: End at 8.02s (took 65.98ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/blockAlignedData--legacy: Start at 8.02s Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/blockAlignedData--legacy: End at 8.03s (took 6.73ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/blockAlignedData--legacy: Start at 8.03s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/blockAlignedData--legacy: End at 8.06s (took 24.14ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/shortKey--legacy: Start at 8.06s Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/shortKey--legacy: End at 8.06s (took 1.05ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/shortKey--legacy: Start at 8.06s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/shortKey--legacy: End at 8.07s (took 8.21ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/shortKey--legacy: Start at 8.07s Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/shortKey--legacy: End at 8.07s (took 5.78ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/shortKey--legacy: Start at 8.08s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/shortKey--legacy: End at 8.08s (took 8.44ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/legacyData--legacy: Start at 8.09s Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/legacyData--legacy: End at 8.09s (took 1ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/legacyData--legacy: Start at 8.09s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/legacyData--legacy: End at 8.11s (took 25.31ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/legacyData--legacy: Start at 8.12s Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/legacyData--legacy: End at 8.12s (took 6.15ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/legacyData--legacy: Start at 8.12s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/legacyData--legacy: End at 8.15s (took 23.17ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/v2Data--rsa-v2: Start at 8.15s Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/v2Data--rsa-v2: End at 8.16s (took 14.11ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/v2Data--rsa-v2: Start at 8.17s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/v2Data--rsa-v2: End at 8.21s (took 47.62ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/v2Data--rsa-v2: Start at 8.21s Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/v2Data--rsa-v2: End at 8.22s (took 6.1ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/v2Data--rsa-v2: Start at 8.22s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/v2Data--rsa-v2: End at 8.25s (took 29.57ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/v2DataWebHexadecimal--rsa-v2: Start at 8.25s Logger.js:261 12:38:28: Performance: ppkTestUtils/loadKeys/v2DataWebHexadecimal--rsa-v2: End at 8.26s (took 1.67ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/v2DataWebHexadecimal--rsa-v2: Start at 8.26s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.0/v2DataWebHexadecimal--rsa-v2: End at 8.29s (took 34.74ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/v2DataWebHexadecimal--rsa-v2: Start at 8.29s Logger.js:261 12:38:28: Performance: ppkTestUtils/encrypt/v2DataWebHexadecimal--rsa-v2: End at 8.3s (took 2.26ms) Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/v2DataWebHexadecimal--rsa-v2: Start at 8.3s Logger.js:261 12:38:28: Performance: ppkTestUtils/decrypt.1/v2DataWebHexadecimal--rsa-v2: End at 8.33s (took 29.65ms) Logger.js:261 12:38:33: Performance: ppkTestUtils/loadKeys/local data--rsa-v2: Start at 13.22s Logger.js:261 12:38:33: Performance: ppkTestUtils/loadKeys/local data--rsa-v2: End at 13.22s (took 2.43ms) Logger.js:261 12:38:33: Performance: ppkTestUtils/decrypt.0/local data--rsa-v2: Start at 13.22s Logger.js:261 12:38:33: Performance: ppkTestUtils/decrypt.0/local data--rsa-v2: End at 13.25s (took 33.58ms) Logger.js:261 12:38:33: Performance: ppkTestUtils/encrypt/local data--rsa-v2: Start at 13.25s Logger.js:261 12:38:33: Performance: ppkTestUtils/encrypt/local data--rsa-v2: End at 13.26s (took 2.14ms) Logger.js:261 12:38:33: Performance: ppkTestUtils/decrypt.1/local data--rsa-v2: Start at 13.26s Logger.js:261 12:38:33: Performance: ppkTestUtils/decrypt.1/local data--rsa-v2: End at 13.29s (took 29.41ms)

However, at least in development mode, the generateKey operation (which runs during sync, when syncInfo.ppk is unset and when resetting the master key password) is very slow (trials: 12.69s, 3.46s, 8.16s, 7.11s).

Update 2:

generateKey also seems to be slow in release mode on the same Android device (trials: 3.9s, 2.66s, 4.15s, 7.26s, 4.66s, 4.45, 8.64, 9.86).

laurent22 · 2025-08-10T08:58:20Z

packages/lib/services/e2ee/ppk/WebCryptoRsa.ts

+	private textToBuffer_(textUtf8: string) {
+		// To avoid data loss when restoring (whether everything is capital or lowercase), work only
+		// with lowercase hexadecimal.
+		const isHex = isLowercaseHexadecimalString(textUtf8);


I'm not sure I understand the logic here - is that for compatibility with the previous version? Which means some data is hex and some is not?

Currently, Joplin seems to only provide non-hex-encoded data during tests (assuming that Joplin master keys are always hex-encoded).

An alternative to this might be to:

throw when provided non-hex-encoded data, both here and in the legacy RSA implementation. This would help ensure that the input data remains hexadecimal encoded in the future.

Add tests and/or runtime assertions elsewhere to help ensure that Joplin master keys remain hex-encoded in the future (even if the legacy RSA implementation is still in-use).

Without hexadecimal decoding, Joplin master keys are larger than the maximum plaintext size (see notes above).

…logic

- Rename RsaLegacy -> RsaV1 - Add note that RsaV2 can block the mobile app UI when generating keys, but might not after migrating to the New Architecture. - Disable key generation with RsaV2 in the mobile app startup tests. - Verify that key generation is tested with whatever public key algorithm is the default in the mobile app startup tests.

During pull request review, it was suggested that an RSA-OAEP-based encryption option be provided that uses a length-2048 key (due to the performance overhead of generating length-4096 keys). This commit adds such an encryption scheme as "RsaV2". The old RsaV2 has been renamed to "RsaV3". As before, migrations to both RsaV2 and RsaV3 are disabled. Possible concerns: - See comment at the top of "LongDataWrapper.ts". - MDN, referring to the key size: "Some organizations are now recommending that it should be 4096." - https://developer.mozilla.org/en-US/docs/Web/API/RsaHashedKeyGenParams#moduluslength

…rsion

…/node version" This reverts commit d0335f5.

…logic

laurent22 · 2025-09-08T10:31:28Z

I think we can go ahead and merge this, as soon as the conflicts are fixed

…logic

personalizedrefrigerator added 18 commits July 30, 2025 11:20

WIP

9e29917

Fix method name

117e8ed

Switch back to a single "ppk" field in info.json

7d6c1ab

Add logic for PPK migration

9d03d08

Revert changes to builtInMetadata.ts

cd449e5

Revert now-unnecessary changes to ShareService.ts

0a6eb1b

Rename "RsaOaep" -> "RsaV2", add mobile test case, fix linter error

b1b192b

Fix React Native key format incompatibility issue, run RSA tests on w…

5b8d426

…eb, add more tests

Remove incorrect deprecation warning for router.get...public_key

2619348

Refactoring, commenting

26ea4eb

Refactoring

30b9074

Use webcrypto in NodeJS to explicitly use the NodeJS webcrypto typings

e9c9564

Move the PPK algorithm to a prefix of the public key

e9e61a9

This removes the need for a separate "algorithm" property (which would require changes to Joplin Server).

Prevent old clients from migrating backwards from a new PPK algorithm to

85e95b3

an old one

Don't migrate to RsaV2 for now

4d45f08

The PPK algorithm name should not include spaces

2396387

Revert most changes to packages/server

f4335e7

Fix tsc error in environments with an old version of @types/node

5a6633e

personalizedrefrigerator changed the title ~~Desktop,Mobile,Cli: Sharing: Add support for accepting shares that use a new key format~~ Chore: Desktop,Mobile,Cli: Support accepting shares with a new key format Jul 31, 2025

personalizedrefrigerator added 3 commits July 31, 2025 12:30

Revert unnecessary changes to ShareService.test.ts

0afc1e1

Trying to fix NodeJS 18 compatibility

8c852d3

Trying to fix NodeJS 18 support

7d76337

personalizedrefrigerator mentioned this pull request Jul 31, 2025

Chore: Work around test failure in newer NodeJS versions #12830

Merged

personalizedrefrigerator added 4 commits August 1, 2025 09:28

Merge remote-tracking branch 'upstream/dev' into pr/all/refactor-rsa-…

069fda9

…logic

Restore change lost during merge

8e93773

Refactoring, add more tests

16c40ef

Allow accepting invitations targeting the old PPK

50c6139

See inline comments -- this should improve UX during migration if: 1. Some sharer shares a notebook with client A, targeting client A's PPK. 2. Client A's PPK is migrated. 3. Client A tries to accept the share.

personalizedrefrigerator force-pushed the pr/all/refactor-rsa-logic branch from 5f777f6 to 50c6139 Compare August 1, 2025 19:49

personalizedrefrigerator added 2 commits August 1, 2025 13:22

Trying to fix NodeJS 18 compatibility

16adeef

Document how to add migrations

f870886

laurent22 reviewed Aug 10, 2025

View reviewed changes

personalizedrefrigerator added 4 commits August 11, 2025 12:51

Merge remote-tracking branch 'upstream/dev' into pr/all/refactor-rsa-…

1cd926e

…logic

Add performance logging to ppkTestUtils

683f22f

Merge remote-tracking branch 'upstream/dev' into pr/all/refactor-rsa-…

7ea5373

…logic

Add more performance logging

ce70cbf

personalizedrefrigerator marked this pull request as ready for review August 13, 2025 14:57

personalizedrefrigerator added 4 commits August 13, 2025 08:37

WIP: Refactoring

1dba1a2

Fix legacy RSA support

d08d9f8

personalizedrefrigerator changed the title ~~Chore: Desktop,Mobile,Cli: Support accepting shares with a new key format~~ Desktop,Mobile,Cli: Support accepting shares with a new key format Aug 15, 2025

personalizedrefrigerator added 9 commits August 15, 2025 11:22

Fix tsc errors by depending on a consistent version of "@types/node"

54fde7a

Plugin documentation generator: Also depend on a newer @types/node ve…

d0335f5

…rsion

Revert "Plugin documentation generator: Also depend on a newer @types…

cdc1172

…/node version" This reverts commit d0335f5.

Trying to fix CI

2d93271

Refactoring

df3cf93

Test supportsPpkAlgorithm

421f5d4

Merge remote-tracking branch 'upstream/dev' into pr/all/refactor-rsa-…

6998011

…logic

Fix version of @types/node

c3edad3

Merge remote-tracking branch 'upstream/dev' into pr/all/refactor-rsa-…

ffa69df

…logic

laurent22 added the v3.5 label Aug 20, 2025

personalizedrefrigerator added 2 commits September 8, 2025 08:21

Merge remote-tracking branch 'upstream/dev' into pr/all/refactor-rsa-…

8d6ef21

…logic

Fix yarn.lock

d11330e

laurent22 merged commit fdde04e into laurent22:dev Sep 8, 2025
11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

Desktop,Mobile,Cli: Support accepting shares with a new key format#12829

Desktop,Mobile,Cli: Support accepting shares with a new key format#12829
laurent22 merged 46 commits intolaurent22:devfrom
personalizedrefrigerator:pr/all/refactor-rsa-logic

personalizedrefrigerator commented Jul 31, 2025 •

edited

Loading

Uh oh!

laurent22 left a comment

Uh oh!

laurent22 Aug 10, 2025

Uh oh!

personalizedrefrigerator Aug 11, 2025

Uh oh!

laurent22 Aug 10, 2025

Uh oh!

personalizedrefrigerator Aug 11, 2025

Uh oh!

personalizedrefrigerator Aug 11, 2025 •

edited

Loading

Uh oh!

laurent22 Aug 10, 2025

Uh oh!

personalizedrefrigerator Aug 11, 2025

Uh oh!

laurent22 commented Sep 8, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Comments

Conversation

personalizedrefrigerator commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New key formats (currently disabled)

Testing plan

Footnotes

Uh oh!

laurent22 left a comment

Choose a reason for hiding this comment

Uh oh!

laurent22 Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

personalizedrefrigerator Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

laurent22 Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

personalizedrefrigerator Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

personalizedrefrigerator Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

laurent22 Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

personalizedrefrigerator Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

laurent22 commented Sep 8, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

personalizedrefrigerator commented Jul 31, 2025 •

edited

Loading

personalizedrefrigerator Aug 11, 2025 •

edited

Loading