In order to allow features like externally managed masterkeys (#7), we need to distinguish key derivation from vault decryption. If key derivation is a separate process that feeds into the decryption, it can be replaced by other modules that produce raw keys.
We'd need two different files:
masterkey.cryptomator
contains the KDF-related params
contains a fake vault version of 999 (to prevent older versions from opening this vault)
vault.cryptomator
specifies what key to use
contains the real vault version
may contain other configuration params such as the cipher config (see #94) or a shortening threshold
is a JWT signed with HS256 using the 512 bit raw masterkey to prevent downgrade attacks (note: HMAC-SHA256 uses 512 bit block size, so a 512 bit key is the maximum possible key without the hash function weakening it)
Migration
To migrate from vault version 7 to vault version 8, the following steps are required:
read old masterkey.cryptomator (vault format should still be 7)
derive key; concat old encKey + hmacKey to single 512 bit raw masterkey
write vault.cryptomator in JWT format
set header alg to HS256
set header kid=masterkeyfile:masterkey.cryptomator (RFC 7515 kid header field; allow other values eventually - see #7, #97)
add claim jti={RANDOM_UUID} to uniquely identify the vault
add claim format=8
add claim ciphercombo=SIV_CTRMAC (only possible config in vault format 7; eventually allow other values such as SIV_GCM - see #94)
add claim shorteningThreshold=220
sign with full 512 bit masterkey
write new masterkey.cryptomator
set version to 999 (to prevent older versions from attempting to unlock this)
keep all other params
Opening a vault with format 8
decode vault.cryptomator
read kid header and, depending on its value, retrieve the masterkey from the user/system/keystore/...
verify the JWT signature (or throw "wrong key" exception)
In order to allow features like externally managed masterkeys (#7), we need to distinguish key derivation from vault decryption. If key derivation is a separate process that feeds into the decryption, it can be replaced by other modules that produce raw keys.
We'd need two different files:
masterkey.cryptomator999(to prevent older versions from opening this vault)vault.cryptomatorMigration
To migrate from vault version 7 to vault version 8, the following steps are required:
masterkey.cryptomator(vault format should still be 7)vault.cryptomatorin JWT formatalgtoHS256kid=masterkeyfile:masterkey.cryptomator(RFC 7515kidheader field; allow other values eventually - see #7, #97)jti={RANDOM_UUID}to uniquely identify the vaultformat=8ciphercombo=SIV_CTRMAC(only possible config in vault format 7; eventually allow other values such asSIV_GCM- see #94)shorteningThreshold=220masterkey.cryptomatorOpening a vault with format 8
vault.cryptomatorkidheader and, depending on its value, retrieve the masterkey from the user/system/keystore/...formatis supportedciphercombo