How the Towns encryption and decryption protocol works.
key solicitation request
to get missing session keys. It also covers how other devices in the group can
share session keys
in a process called key fulfillment
after checking that Bob is a group member.
Before diving into the key solicitation
, key fulfillment
, and key sharing
algorithms, let’s first take a look at the core entities in the group encryption
protocol.
GroupEncryptionCrypto
: The main interface of the protocol. It
initializes the EncryptionDelegate
. This class “delegates” the
encryption and decryption operations to the
olm
library from the Matrix.org foundation.
This library implements the Double Ratchet algorithm. See notes on supported algorithm for future plans.
The Towns Encryption Protocol uses this library to create a group session, and
perform device-to-device encryption using the session keys.
The GroupEncryptionCrypto
creates a GroupEncryption
, a
GroupDecryption
, and an EncryptionDevice
to handle the group encryption
protocol:
GroupEncryption
: handles group encryption using session keys. Outgoing
messages are encrypted with outbound session keys.GroupDecryption
: handles group decryption using session keys. Incoming
messages are decrypted with inbound session keys.EncryptionDevice
: interfaces with the EncryptionDelegate
to perform
cryptographic operations. It also uses the CryptoStore
to get and save the
inbound / outbound session keys.KeySolicitation
request to the group. Any device that is “online” at that moment can share its
known session keys, and send a KeyFulfillment
response to inform others in the
group that the KeySolicitation
request has already been fulfilled.
Continuing our example, suppose Alice’s device does not have the session key
to decrypt a message from Bob. Alice’s device posts a KeySolicitation
request
to the stream. Bob’s device happens to be online at the moment. When it sees the
request, it processes the request as follows:
Thus, Alice’s device is able to get the required session keys for decryption.
The Towns Encryption Protocol is designed to support new algorithms. There is analgorithm
field in the protocol definition. The current value isr.group-encryption.v1.aes-sha2
. This means that the protocol is using theolm
Double Ratchet library for device-to-device session encryption. This field can be set to new algorithms to support future needs.