Loop/Architecture/Context: Difference between revisions

When a Loop client logs into the FxA server, it will obtain a user-specific symmetric key, '''kB''', and an OAuth application identifier. The key '''kB''' is wrapped with the user's account login password. Upon obtaining the key, the user unwraps '''kB''', combines it with the application identifier, and applies HKDF to obtain a new key, '''kBr'''.

When a client creates a new room, it first generates a new symmetric room key, '''kR'''. It then derives a room metadata-specific key, '''kRm''', via HKDF and the application name "metadata". The room context information is serialized as a JSON object, and encrypted using '''kRm'''. The client also wraps '''kR''' with '''kB'''. The encrypted context information and the wrapped room key '''kR''' are sent to the Loop server as part of the room creation request; these are stored as part of the room's information.

Upon receipt of the resulting room URL from the server, the client appends the room metadata key '''kRm''' to the URL as a URL fragment before storing it locally.

Because all desktop clients can constitute their '''kBr''' upon logging in to FxA, any room context retrieved from the Loop server can be decoded by unwrapping the '''kR''' received as part of the room information, deriving the room metadata key '''kRm''' from it, and using it to decrypt the context.

Standalone clients receive the room metadata key '''kRm''' in the fragment portion of the URL that was provided to them as the means of joining the room. Upon retrieving the encrypted room context information from the server, they use this '''kRm''' to decode the room context information and display it to the user.

Encryption consists of selecting a random 12-byte IV value. This IV, the plaintext JSON representation of the room context fields, and '''kRm''' are used as input to the AES-GCM encryption algorithm, which is configured to generate a 128-bit validation tag. The IV is then concatenated with the ciphertext and the validation tag. The resulting bytestring is Base64 encoded, and included as the "context.value" field in the appropriate Loop Server API call, alongside the wrapped room key '''kR''' and the algorithm name ("AES-GCM").

Decryption consists of Base64 decoding the "context" field, splitting off the first 12 bytes for use as an IV, and splitting off the final 16 bytes as the validation tag. These are then used as input to the AES-GCM decryption algorithm (along with '''kRm'''), the output of which is a JSON object containing fields that correspond to the various room context information fields.

The "key" field is encrypted, formatted, and decrypted similarly, but using '''kBr''' rather than '''kRm''' as the encryption key, and using '''kR''' as the cleartext.