Architecture :: Secrets

The general idea behind the derivation-based secrets hierarchy is to limit responsibilities of individual secrets and to reduce the damage caused if one does end up compromised. For example, if a DeviceFileSecret for file A is compromised, other files, metadata or user passwords should remain unaffected. Of course, if a parent secret is compromised then all secrets derived from it could also be compromised.

There may also be limits on how much data can be encrypted with the same crypto material, depending on the encryption used. For more info, check the encryption based on AES in the client.

As an additional measure to limit exposure of user and device secrets, the main DeviceSecret is unique per device, and is generated when that device is first initialized. It is encrypted with a secret based on the UserPassword but it is not related to it.

Secrets and Secret Derivation

• UserPassword

  • UserAuthenticationPassword - if hashing is enabled (the default), avoids sending the original user password outside the local device
  • UserHashedEncryptionPassword - avoids using the original user password to encrypt the device secret directly
    • UserEncryptionSecret

• DeviceSecret

  • DeviceFileSecret - avoids re-using the same secret for each file, part of file or metadata
  • DeviceMetadataSecret - avoids re-using the same secret for each file, part of file or metadata

• API Token - avoids HTTP API accepting unauthorized requests

Usage

• UserPassword - original user password; used for deriving UserHashedAuthenticationPassword and UserHashedEncryptionPassword
• UserAuthenticationPassword.Hashed - used for authenticating with an identity service, instead of sending the original user password
• UserAuthenticationPassword.Unhashed - used for authenticating with an identity service, the original user password is sent to the service (some security is sacrificed for better compatibility with 3rd party identity services)
• UserHashedEncryptionPassword - used for generating UserEncryptionSecret crypto material
• UserEncryptionSecret - used for encrypting/decrypting the device secret in local storage
• DeviceSecret - used for generating DeviceFileSecret and DeviceMetadataSecret crypto material
• DeviceFileSecret - used for encrypting each file/file part
• DeviceMetadataSecret - used for encrypting each metadata entry
• API Token - used for securing access to the client's API

Drawbacks

• UserAuthenticationPassword.Hashed - the user will not be able to log in directly with the identity service, unless it supports this custom hashing scheme; the service would expect the hashed password, but the user will be providing the original one