UVF support by overheadhunter · Pull Request #274 · cryptomator/hub

overheadhunter · 2024-05-10T05:19:20Z

This PR adds fundamental support for UVF-based vaults. During vault creation either format is selected. There is no migration of format 8 based vaults planned. Vault access tokens either contain a format 8 Masterkey OR a UVF member key (which is an A256KW key for the vault.uvf file).

Notable changes:

split up crypto implementation into uvf.ts and vaultv8.ts, leaving common crypto in crypto.ts
make jwe.ts capable of handling compact as well as json serialization with support for ECDH-ES (legacy, decrypt only), ECDH-ES+A256KW, PBES2+A256KW and A256KW, allowing encryption for multiple recipients
add new vault fields to database and DTOs to allow storing a vault.uvf file as well as the public part of a recovery key pair
instead of serializing the masterkey, the recovery key consists of a serialized private key

TODO

bump API level

# Conflicts: # backend/src/test/java/org/cryptomator/hub/api/VaultResourceTest.java

# Conflicts: # backend/src/main/java/org/cryptomator/hub/api/VaultResource.java # backend/src/main/java/org/cryptomator/hub/entities/Vault.java # backend/src/test/java/org/cryptomator/hub/api/VaultResourceIT.java # frontend/src/components/VaultDetails.vue

[ci skip]

in access token

# Conflicts: # backend/src/main/resources/org/cryptomator/hub/flyway/ERM.png # frontend/src/common/userdata.ts # frontend/src/components/InitialSetup.vue # frontend/src/components/RegenerateSetupCodeDialog.vue # frontend/src/components/VaultDetails.vue # frontend/src/i18n/de-DE.json

# Conflicts: # backend/src/test/java/org/cryptomator/hub/api/VaultResourceIT.java

see encryption-alliance/unified-vault-format#32

[ci skip]

frontend/test/common/universalVaultFormat.spec.ts

# Conflicts: # frontend/src/common/jwe.ts

see encryption-alliance/unified-vault-format#31

# Conflicts: # frontend/src/components/CreateVault.vue # frontend/src/components/VaultDetails.vue

see https://devblogs.microsoft.com/typescript/announcing-typescript-5-7/#support-for---target-es2024-and---lib-es2024

chenkins · 2025-11-06T07:49:46Z

frontend/src/common/universalVaultFormat.ts

+      cty: 'json',
+      crit: ['uvf.spec.version'],
+      'uvf.spec.version': 1,
+      'cloud.katta.origin': `${apiURL}/vaults/${vault.id}/uvf/vault.uvf`, // single source of truth for this vault


@overheadhunter is this katta only? Does not make sense upstream?

you're right, should be org.cryptomator here...

chenkins · 2025-11-06T08:35:24Z

frontend/test/common/universalVaultFormat.spec.ts

+        name: 'test',
+        archived: false,
+        creationTime: new Date(),
+        uvfMetadataFile: '{"protected":"eyJvcmlnaW4iOiJodHRwcy4vL2V4YW1wbGUuY29tL2FwaS8vdmF1bHRzLzEyMy91dmYvdmF1bHQudXZmIiwiamt1Ijoiandrcy5qc29uIiwiZW5jIjoiQTI1NkdDTSJ9","recipients":[{"header":{"kid":"org.cryptomator.hub.memberkey","alg":"A256KW"},"encrypted_key":"vJ16vGF2Z3NcA7nXPnVrgDLzgxZ8RFtySgf0FsckcrTBfKDg4hAK0w"},{"header":{"kid":"org.cryptomator.hub.recoverykey.J7-F_hjMaygRKdqIoZrbxSqVSRFJ5aF8BXuOCoBBGjw","alg":"ECDH-ES+A256KW","epk":{"key_ops":[],"ext":true,"kty":"EC","x":"oQZ8e-e9UIOtbN50ySx5Xwik9ET3uu38Bzl6HdDR8uipOzdXIO8OUhVQMJWqEHjs","y":"cTP6OI_YfdCVPVWpGOA1SjQ6-4vUpE4a6QJx3JSw29DkOL70Rjl4GAcDc4Iw-VHY","crv":"P-384"},"apu":"","apv":""},"encrypted_key":"m_tSjpBcNQK42pgqLA9YDZYa3WQwJZ94HhGIpwOcKDoJQ8lP8IKbFw"}],"iv":"XPY9W-TE__Hu2m53","ciphertext":"uoukmSAuFTq-20gD9Ayum8iH6ERrld6cNV_ZTyfHBcWeIIZKOdp3RWWEtzNagVnRy5ix0yAafJIa14aSLnsxFv-NhzW1BirU5YypIkvFIO4cPnjI54vzd8nEtPdpp6z2JOqKUvZQYN89Y2EGoXb33FmQAwVMNJt_xDn2Bcb1dvI0q0uKLUidsvFL87NHSA8KUVWjXmmFdjibfqhWuO9YtFVoYD2Oqso9TzQIRMnDt3aIcVAouTTE7bR9O8kj5nseNID2gQ2osKlJVVcUn-4Cn0bI2w_-SeAfAvnePWLmolF8q79_aOsMkow3zMGsQHFoVU3PWCHR374Z02Lnt0Mj5_aUu_k8R5L11xNZQ0EYY7XWWGoUjRif7HmRfTZoHbJwvnHWk5q6IuEEjd_zSa4_im7PpoEofZR2EcH7Zz_Llq00wPWT05ZD82aRo3VCRNs6A2s6Jd8hspnaYA","tag":"j-xKxc2aZ2EDHDm8CzNf8Tj4QIkruZauF0LeUwrhq6c"}',


Update with all protected headers?

decided against it as the header doesn't affect the purpose or outcome of the test and didn't have much time

chenkins · 2025-11-06T08:35:49Z

frontend/test/common/universalVaultFormat.spec.ts

+    });
+
+    it('recover()', async () => {
+      const vaultUvfFileContents = '{"protected":"eyJvcmlnaW4iOiJodHRwcy4vL2V4YW1wbGUuY29tL2FwaS8vdmF1bHRzLzEyMy91dmYvdmF1bHQudXZmIiwiamt1Ijoiandrcy5qc29uIiwiZW5jIjoiQTI1NkdDTSJ9","recipients":[{"header":{"kid":"org.cryptomator.hub.memberkey","alg":"A256KW"},"encrypted_key":"J3Gd7wZzsy-ykWPboW9CqK6DzoDGwRiZCJ3d6fNYkpt0klqDRmYR0g"},{"header":{"kid":"org.cryptomator.hub.recoverykey.DGbyooUW5QlVWzTaF102-f59uRTX1kdqkQb_CMDq9gM","alg":"ECDH-ES+A256KW","epk":{"key_ops":[],"ext":true,"kty":"EC","x":"q4p-3TTjHZxAkf6Fa3rknf_oqBGRiAkXB78_UxElbv6DN0Ufc_2RSX2pYKb8gaAU","y":"czJGKQe_q12AMYROZfEUBbP6zMo0DjgjK_346_BjS9RQ531jf32Ryht4xIBP50ef","crv":"P-384"},"apu":"","apv":""},"encrypted_key":"7D-irqonnK01xQiTNGmsgSRPBzLdKdGTtq2XGS6BONkHWFgESpOYeg"}],"iv":"FNxcOvj_BgQ4vRVN","ciphertext":"qyORqJsK_3aec14d6gnIuNrLmnhFggY0MBWkjqOUXsOhSgOKcamtLbLGhk1gqWfc_dcshzWnBxx7TB2K_TwfSKnF0mumPldFMQ6u_HQM-jemBDCsStBSdOQoYqYcwbLyEfvH39XO4Oremppsj1a-8bOIbga0gnbQQmuNXraQtZLtyut82Q7P521Ab_leIUo_laKHPk610SW3DyJySoroxFH40qEb0GfsUAdcHMwCNA2dhQCCOW4zFZsmV_PxnVaNOhUV8aVz-lmwW8PnNCLxMdveQDegnbSvban6O0Qjl1MRnf1_pnBEM2meWk6CTnuJYwWaKHgbG69geGliOB_wKRTAapw8gOyQ-gPZya2hMvK2gAJLPWXAAc6mDo_MfzHa7PbLQ70J1r_tsJLKLmTrvU683Let70KG1_UyHFi6m9aFfXgA5PfmfGFKeDZ3e_bqNzFJbf-ytZJq9A","tag":"FpTkkwkTujb3OosDC-ck97W4awBStimQ95NfTe0TRxQ"}';


Update with all protected headers?

chenkins · 2025-11-06T19:03:33Z

frontend/src/common/universalVaultFormat.ts

+      'cloud.katta.origin': `${apiURL}/vaults/${vault.id}/uvf/vault.uvf`, // single source of truth for this vault
+      jku: 'jwks.json', // URL relative to cloud.katta.origin


@overheadhunter Also: the spec says:

As the current version of this specification only allows for predefined parameter values, nothing but the parameter order may change. The base64url-encoded version of the protected header for spec version 1 should therefore always be this:

echo eyJlbmMiOiJBMjU2R0NNIiwiY3R5IjoianNvbiIsImNyaXQiOlsidXZmLnNwZWMudmVyc2lvbiJdLCJ1dmYuc3BlYy52ZXJzaW9uIjoxfQ | jq -R '@base64d | fromjson' { "enc": "A256GCM", "cty": "json", "crit": [ "uvf.spec.version" ], "uvf.spec.version": 1 }

Do I misread the spec or ar origin and jku not allowed?

chenkins · 2025-11-06T19:09:03Z

frontend/src/common/universalVaultFormat.ts

+   */
+  public static async decryptWithMemberKey(uvfMetadataFile: string, memberKey: MemberKey): Promise<VaultMetadata> {
+    const json: JsonJWE = JSON.parse(uvfMetadataFile);
+    const payload: MetadataPayload = await JWE.parseJson(json).decrypt(Recipient.a256kw('org.cryptomator.hub.memberkey', memberKey.key));


@overheadhunter Check uvf.spec.version as discussed here

chenkins · 2025-11-06T19:09:10Z

frontend/src/common/universalVaultFormat.ts

+    }
+    const recoveryKeyID = `org.cryptomator.hub.recoverykey.${await getJwkThumbprintStr(recoveryKey.publicKey)}`;
+    const json: JsonJWE = JSON.parse(uvfMetadataFile);
+    const payload: MetadataPayload = await JWE.parseJson(json).decrypt(Recipient.ecdhEs(recoveryKeyID, recoveryKey.privateKey));


@overheadhunter Check uvf.spec.version as discussed here

# Conflicts: # backend/src/main/java/org/cryptomator/hub/api/VaultResource.java # frontend/src/common/crypto.ts # frontend/src/common/jwe.ts # frontend/src/common/userdata.ts # frontend/src/components/ArchiveVaultDialog.vue # frontend/src/components/CreateVault.vue # frontend/src/components/GrantPermissionDialog.vue # frontend/src/components/ReactivateVaultDialog.vue # frontend/src/components/VaultDetails.vue # frontend/test/common/crypto.spec.ts # frontend/test/common/jwe.spec.ts

# Conflicts: # backend/src/main/java/org/cryptomator/hub/entities/EffectiveVaultAccess.java # backend/src/main/java/org/cryptomator/hub/entities/User.java # backend/src/test/java/org/cryptomator/hub/api/VaultResourceIT.java # frontend/src/common/backend.ts # frontend/src/common/crypto.ts

overheadhunter and others added 30 commits March 2, 2024 12:10

add "alg": "A256KW" support for JWEs

2d080ea

uvf metadata (WiP).

d109cff

remove dead code from backend.ts for now

55633f1

disentangle v8 and uvf based vaults

fe7ff3d

move vault format 8 code to separate file

be8803c

move UVF code to separate file

b51cc59

adjust UVF payload to latest spec

a9f12d4

Merge branch 'develop' into feature/uvf

cdf5571

# Conflicts: # backend/src/test/java/org/cryptomator/hub/api/VaultResourceTest.java

new JWE API supporting compact and JSON format

3f77d16

use correct AlgorithmID for Concat KDF

3646379

added tests

f1c14fd

type cleanup

aa1690f

include recovery key in UVF metadata

e6e028a

create UVF-based vault

a85cf3c

store uvf metadata and recovery key in vault table

32f2743

adjusted to DTO model

a63ef34

Merge branch 'develop' into feature/uvf

6ce1569

grant permission to UVF vault

01c8a06

fix autocompletion mistake

36eb79c

use common interfaces for VF8 and UVF

3cf9c8e

fix linter errors

69f0360

experimental implementation of serializePrivateKey()

7bddc62

make config.ts usable during tests

ba05d8b

deduplicate "encrypt for user"

3d1db01

store recovery key among vault key in access token

6b46862

reordered fields

cb4e53a

[ci skip]

store recovery key as PKCS8 instead of words

b294f55

in access token

adjusted parameter order

a3fc184

fix mocha test explorer: document is not defined

aeafffe

overheadhunter added 10 commits February 7, 2025 09:45

Merge branch 'develop' into feature/uvf

5a38a4d

reordered migrations

fd6db88

Merge branch 'develop' into feature/uvf

cd68e29

# Conflicts: # backend/src/test/java/org/cryptomator/hub/api/VaultResourceIT.java

Merge branch 'develop' into feature/uvf

3a65446

use base64url in vault.uvf

b5a94a9

see encryption-alliance/unified-vault-format#32

fix base64url encoding and tests

7e285ea

fix test broken during merge cd68e29

6efd702

run linter

ce36aa1

[ci skip]

Merge branch 'develop' into feature/uvf

928b613

chenkins reviewed Jul 7, 2025

View reviewed changes

frontend/test/common/universalVaultFormat.spec.ts Outdated Show resolved Hide resolved

overheadhunter and others added 6 commits July 8, 2025 10:38

Merge branch 'develop' into feature/uvf

9fb01db

# Conflicts: # frontend/src/common/jwe.ts

use 512 bit keys for HMAC-SHA256 as per spec

27a944d

see encryption-alliance/unified-vault-format#31

Merge branch 'develop' into feature/uvf

b882d6b

Merge branch 'develop' into feature/uvf

6318fb6

# Conflicts: # frontend/src/components/CreateVault.vue # frontend/src/components/VaultDetails.vue

force big-endian seed IDs

85f4d30

use Uint8Array<ArrayBuffer> (TS 5.7 adjustments)

e7dceec

see https://devblogs.microsoft.com/typescript/announcing-typescript-5-7/#support-for---target-es2024-and---lib-es2024

chenkins mentioned this pull request Oct 31, 2025

katta-server aka. downstream diff to upstream shift7-ch/katta-server#52

Open

overheadhunter added 2 commits November 5, 2025 12:31

use Uint8Array<ArrayBuffer> (TS 5.7 adjustments)

703d092

see https://devblogs.microsoft.com/typescript/announcing-typescript-5-7/#support-for---target-es2024-and---lib-es2024

add missing protected header params

ce24d91

chenkins reviewed Nov 6, 2025

View reviewed changes

overheadhunter added 4 commits November 12, 2025 19:18

Merge branch 'develop' into feature/uvf

6bac061

Merge branch 'develop' into feature/uvf

008b3cd

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

UVF support#274

UVF support#274
overheadhunter wants to merge 119 commits intodevelopfrom
feature/uvf

overheadhunter commented May 10, 2024 •

edited

Loading

Uh oh!

Uh oh!

chenkins Nov 6, 2025 •

edited

Loading

Uh oh!

overheadhunter Nov 7, 2025

Uh oh!

chenkins Nov 6, 2025 •

edited

Loading

Uh oh!

overheadhunter Nov 7, 2025

Uh oh!

chenkins Nov 6, 2025

Uh oh!

chenkins Nov 6, 2025

Uh oh!

chenkins Nov 6, 2025

Uh oh!

chenkins Nov 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		'cloud.katta.origin': `${apiURL}/vaults/${vault.id}/uvf/vault.uvf`, // single source of truth for this vault
		jku: 'jwks.json', // URL relative to cloud.katta.origin

Uh oh!

Conversation

overheadhunter commented May 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

chenkins Nov 6, 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!

overheadhunter Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

chenkins Nov 6, 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!

overheadhunter Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

chenkins Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

chenkins Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

chenkins Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

chenkins Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

overheadhunter commented May 10, 2024 •

edited

Loading

chenkins Nov 6, 2025 •

edited

Loading

chenkins Nov 6, 2025 •

edited

Loading