This is the first part of a series of PRs, which simplify access management.
Introduction of User Key Pairs
We formerly only had Device Key Pairs. Vault keys have been shared with devices directly. This meant that the Vault Owner who is in possession of the vault keys had to re-run the key distribution (via the "Update Permissions") button, every time a new device required access to the vault.
Now, we added User Key Pairs. Vault keys are now shared with the user. Each user will self-manage his or her devices. The device key pair does still exist and is required to decrypt the user's private key.
Updated Entity Model
Unlock Procedure
Due to the introduction of an intermediary key, an unlock operation requires to
first load the encrypted vault key (which can be decrypted using the user's private key) from /api/vaults/{vaultId}/access-token (response body is a ECDH-ES JWE)
then load the encrypted private key of the user (which can be decrypted using the device's private key) from /api/devices/{deviceId} (response body contains a JSON. attribute userPrivateKey contains ECDH-ES JWE)
We still keep the legacy API endpoint (/api/vaults/{vaultId}/keys/{deviceId}) for compatibility reasons for a while. However it will only work for existing data. Any newly registered device can only be unlocked using the new workflow.
Device Management
On the profile page, users can see their own devices. In order to add a new device, a Setup Code (here called "Personal Hub Secret", tbd) is required. This code is a secret required to unwrap the user's private key in order to re-wrap it using the device's public key. Once the device is set up, its private key will allow to access the user's private key.
The Setup Code can be access and changed any time by any fully set up device.
This fixes #189
First Device
The browser used to log in to Hub is now also considered a device and a Device Key Pair is generated and stored by the browser as well. The user will be prompted to name the browser accordingly (for identifying the browser, if they decide to revoke access from it later).
The first device from which a login succeeds will also be responsible for generating the User Key Pair together with the Setup Code.
The user's private key is then encrypted in JWE format with a) the device's public key (using an ECDH-ES) and b) using the setup code (using PBES2). The setup code in return is encrypted as an JWE using the user's private key (ECDH-ES again). This ensures that any authenticated device has access to the user's key pair and can thus decrypt the setup code again. Also, the setup code can be used to decrypt the user's key pair when setting up a new device.
Vault Ownership
We used to use the Vault Admin Password to protect a vault from being edited by anyone. Instead we will now use role-based permissions. The creator of a vault is the initial owner. Further owners can be added at a later time. Any owner has full administrative access to a vault (e.g. for adding members).
The Vault Admin Password will be removed in a follow-up PR (as this one is already bursting).
Other
Device.publicKey is now base64-encoded (used to be base64url for some reason)
Device.user_privateKey is now non-null, i.e. if a device exists, we can be sure it is able to access the user's key pair
Open Questions
[ ] Currently, we generate v4 UUID (i.e. 122 bit randomness) as a Setup Code, which is less than the key it protects. In my opinion this is sufficient, this setup code is then fed into PBKDF2 (currently defaulting to 1 mio iterations) to derive the key used to wrap the user's private key.
Next Steps
[x] ~Remove Vault Admin Password~ see #209
[x] ~Add Claim Vault Ownership button (for migrating old data that still uses the vault admin password)~ see #210
[x] ~WoT for user keys ("verify users")~ see #190
[x] ~Warning in "grant access" dialog, if granting access to unverified users~ see #191
[x] ~Add Reset User Account feature (re-roll user key pair, keep devices, losing key signatures and vault access)~ see #208
[x] Remove Legacy Devices during re-registration as a Device using the updated API
This is the first part of a series of PRs, which simplify access management.
Introduction of User Key Pairs
We formerly only had Device Key Pairs. Vault keys have been shared with devices directly. This meant that the Vault Owner who is in possession of the vault keys had to re-run the key distribution (via the "Update Permissions") button, every time a new device required access to the vault.
Now, we added User Key Pairs. Vault keys are now shared with the user. Each user will self-manage his or her devices. The device key pair does still exist and is required to decrypt the user's private key.
Updated Entity Model
Unlock Procedure
Due to the introduction of an intermediary key, an unlock operation requires to
/api/vaults/{vaultId}/access-token(response body is a ECDH-ES JWE)/api/devices/{deviceId}(response body contains a JSON. attributeuserPrivateKeycontains ECDH-ES JWE)We still keep the legacy API endpoint (
/api/vaults/{vaultId}/keys/{deviceId}) for compatibility reasons for a while. However it will only work for existing data. Any newly registered device can only be unlocked using the new workflow.Device Management
On the profile page, users can see their own devices. In order to add a new device, a Setup Code (here called "Personal Hub Secret", tbd) is required. This code is a secret required to unwrap the user's private key in order to re-wrap it using the device's public key. Once the device is set up, its private key will allow to access the user's private key.
The Setup Code can be access and changed any time by any fully set up device.
This fixes #189
First Device
The browser used to log in to Hub is now also considered a device and a Device Key Pair is generated and stored by the browser as well. The user will be prompted to name the browser accordingly (for identifying the browser, if they decide to revoke access from it later).
The first device from which a login succeeds will also be responsible for generating the User Key Pair together with the Setup Code.
The user's private key is then encrypted in JWE format with a) the device's public key (using an ECDH-ES) and b) using the setup code (using PBES2). The setup code in return is encrypted as an JWE using the user's private key (ECDH-ES again). This ensures that any authenticated device has access to the user's key pair and can thus decrypt the setup code again. Also, the setup code can be used to decrypt the user's key pair when setting up a new device.
Vault Ownership
We used to use the Vault Admin Password to protect a vault from being edited by anyone. Instead we will now use role-based permissions. The creator of a vault is the initial owner. Further owners can be added at a later time. Any owner has full administrative access to a vault (e.g. for adding members).
The Vault Admin Password will be removed in a follow-up PR (as this one is already bursting).
Other
Device.publicKeyis now base64-encoded (used to be base64url for some reason)Device.user_privateKeyis now non-null, i.e. if a device exists, we can be sure it is able to access the user's key pairOpen Questions
Next Steps