End-to-End Encryption

• Overview

• Precautions When Sending Messages

Process Overview

Registered user

Pretend that the involved operator is:

Operator	Description
server	server
userA	This user executes the registration operation

userA generates a pair of RSA key pairs (public key and private key) and sets the public_key field in the RegisterRequest to the public key. Ensure that the private key is not leaked to any other operator, including the server, and is saved locally.

create an end-to-end encrypted group chat

Operator	Description
server	server
userA	This user creates a group chat

userA creates a symmetric encryption room_key and saves it locally. Ensure that it is not leaked to other untrusted operators, including the server.

Then userA sends a request to the server to create a group chat, setting e2ee_on to true in the NewSessionRequest.

Accept a user to join the group chat

Pretend that the involved operator is:

Operator	Description
server	server
userA	Someone who is already in the group
userB	Yet to be in the group, will send an entry request to userA

1. userB sends a join_session request to the server

2. userA receives a JoinSessionApproval message, which contains the public key of userB, public_key. Encrypt room_key with public_key to get encrypted_room_key

3. userA sends a allow_user_join_session request, sets the room_key field to encrypted_room_key

4. userB receives an AllowUserJoinSessionNotification message, which contains the room_key field with the content of encrypted_room_key. Use their own RSA private key to decrypt it and obtain the original content of room_key. Similarly, it must not be leaked to other untrusted operators, including the server.

Invite a user to join the group chat

Pretend that the involved operator is:

Operator	Description
server	server
userA	Someone who is already in the group, will invite userB to join
userB	Yet to be in the group

1. userA sends a invite_user_to_session request to the server

2. userB receives an InviteUserToSession message, then uses the information to send an accept_join_session_approval request to the server

3. userA receives an AcceptSessionNotification message, which contains the public key of userB, public_key. Encrypt room_key with public_key to get encrypted_room_key

4. userA sends a send_room_key request, sets the room_key field to encrypted_room_key

5. userB receives a ReceiveRoomKeyNotification message, which contains the room_key field with the content of encrypted_room_key. Use their own RSA private key to decrypt it and obtain the original content of room_key. Similarly, it must not be leaked to other untrusted operators, including the server.

The replacement of room_key

Replacement conditions: When a certain time (can be set) has passed since the last replacement or someone leaves the group chat, the group will be marked. When someone speaks in the marked group, a key exchange operation will be performed. The user’s e2eeize_session request to the server can also trigger a replacement of the group’s room_key.

Pretend that the involved operator is:

Operator	Description
server	server
userA	The first user to speak in the group after it is marked
userB	Others in the group

1. When an update is needed, userA will receive an UpdateRoomKeyNotification message after the message is successfully sent. At this time, userA needs to update the group’s room_key, and there will be several SendRoomKeyNotification messages containing the public keys of other members. The following example uses userB.

2. userA encrypts the updated room_key with userB’s public key to obtain the encrypted encrypted_room_key

3. userA sends a send_room_key request, sets the room_key field to encrypted_room_key

4. userB receives a ReceiveRoomKeyNotification message, which contains the room_key field with the content of encrypted_room_key. Use their own RSA private key to decrypt it and obtain the original content of room_key. Similarly, it must not be leaked to other untrusted operators, including the server.

Switch the end-to-end encryption status of the group chat (on/off)

Pretend that the involved operator is:

Operator	Description
server	server
userA	The user in this group and with Owner permissions

Set the group chat to end-to-end encryption

1. userA sends a e2eeize_session request to the server

2. then it is the process of replacing room_key

Set the group chat to non-end-to-end encryption

1. userA sends a dee2eeize_session request to the server

Things to note when sending messages

In an end-to-end encrypted group chat, each user chooses whether to encrypt when sending a message. If so, they use the room_key for encryption.

A room_key is valid from the time it is created until it is replaced. Any client holding the room_key can decrypt the encrypted message.