---
tags: protocol-doc-draft
---

# Berty Protocol v3 (Notes/Doc Draft)

## Account

### Secrets

#### Account ID Keypair:

- **Public** (shared with contacts through Contact Request Link or during Contact Request Handshake):
- Account Identification
- ECDH for Contact Group creation (on contact side)
- **Private**:
- ECDH for Contact Group creation

#### Alias Keypair:

*Alias Member is used Multi-Member Group in order not to reveal the real identity of an account.*
*An Account can chose to post an Alias Entry (Alias Proof, Alias Resolver) so its contacts within a group can lookup for its real identity. When an Alias Entry is posted to a group, it can't be cancelled.*

- **Public** (shared with contacts during Contact Group init):
- Generate an Alias Resolver: hmac(aliasPK, GroupID) so a contact can match an Alias Member within a Multi-Member Group without bruteforce (sym can be generated by both Account and Contact)
- Verify the Alias Proof to ensure that the associated Alias Resolver has been issued by the right account
- **Private**:
- Generate Alias Proof sigAlias(AliasResolver) for Multi-Member Groups

#### Public RDV Seed:

Randomly generated by any Account's device, can be changed anytime, synchronized among devices using Account Group.
Shared with contacts through Contact Request Link.

### First device / Account Creation

#### Generate Account Secrets:

- Account ID Keypair
- Alias Keypair
- Initial Public RDV Seed

#### Generate Group Account Secrets:

- Group ID Keypair (signs first device as group creator then discard SK cf. Group)
- Group Secret
- Group Secret Sig. (using Group ID SK)

#### Generate Device Secrets:

- Device ID Keypair

### New device linking

The new device (B) generates its own Device ID Keypair.

Already linked device (A) generates an invitation containing:

- Its PeerID
- A random int (we still need to discuss the pro/con about this)

A starts listening on the ProtocolID `bertyprotocol/link_new_device/<random-int>/1.0.0` and communicates it to B using a QRCode, an URL or whatever.

B dial A's PeerID on its random ProtocolID, B sends its Device ID PK to A, A gives a challenge to B
We could have multiple versions of this challenge on multiple ProtocolID:

1. Display a fingerprint of B's Device ID PK on B's device screen, display the fingerprint on A's device screen as well, then A will need to check if the fingerprint is matching (the fingerprint could also be displayed as a QRCode on B's device and scanned by A's device -> usefull only if A's device is a smartphone)
2. We could use a pin code of N digits for example generated by A, displayed on A's device screen that B's user will need to type (could also be embeded in a QRCode and scanned by B if B's device is a smartphone)

*Challenge 1 with QRCode only seems to be the safer option for the case: A is a smartphone - B is any type of device, in all other cases (when A's user need to manually check the fingerprint before validating), 2 seems to be safer because it forces the user to type the pin code, not only click on accept without a thorough verification.*

Then A sends to B all the Account and Group Account secrets:

- Account ID Keypair
- Alias Keypair
- Group ID PK
- Group Secret
- Group Secret Sig.

*Note: B will get the current Public RDV Seed (if exists) directly on the Account Group*

B join the Account Group, sends its message secret and member-device and get all the infos relative to Account's MM Group, Account's Contacts, etc...

## Contact

### Contact Request Reference

Each account can "listen" on its own rendezvous point for receiving Contact Request that can be enabled, disabled or reset (== changing the rendezvous point "address").

To calculate the address of the rendezvous point of any other account we want to send a contact request, we need to have its *ContactRequestReference* which may have been transmitted by message, QRCode or otherwise.

The contact request reference contains the following fields:

- Account ID PK (immutable)
- Public RDV Seed (can be changed)

### Handshake

When one Account (A) dial with one of its devices (A1) another Account (B) 's device (B1) listening on its Public Rendezvous Point, the following handshake occurs:


- a/b == ephemeral ED25519 keypairs
- A/B == Account ID ED25519 keypairs

## Group

### Common base

There are two types of peers that can be part of a group: Members (can decrypt messages, write, etc...) and Replication Device/Server (can't decrypt messages or write, can only replicate them to have high availability).

#### Group Secrets

##### Group ID Keypair:

- **Public** (shared with members and replication peers):
- Group Identification
- Pubsub RDV Point generation -> hmac(grpID, time)
- Verify Group Secret Sig
- Verify first member (creator) sig

- **Private**
- Signature of Group Secret and first member
- Private key is then discarded

#### Group Secret:

Secret used both as:

- **Symmetric Key** (shared with members):
- Encrypt/decrypt several Group payloads

- ED25519 Keypair - **Group Sig Priv** (shared with members):
- Sign all Group payloads to ensure that replication peers and members don't replicate a payload which is not issued by a member

- ED25519 Keypair - **Group Sig Pub** (shared with members and replication peers):
- Verify all Group payloads

#### Group Secret Sig:

Group Secret signed with Group ID SK. Ensure that group secret was generated during Group Creation so, for example, it can't be tampered within a Group Invitation.

#### Attachment Key:

- **Symmetric Key** (shared with members and replication peers):
- Encrypt/decrypt Attachments field containing cID of attachments, the replication peers need to decrypt this field in order to pin attachment.

#### Metadata and Message logs

There are now two logs in this version of the protocol, one containing the messages which has the particularity of being able to be served only in part (example: the last 1000 messages only) and the other containing the metadatas, which will have to be served by all the members and replication peers in its entirety (the first entries of this log being essential for a new member to join the group for example).

#### Log payloads

##### Message payload


*Note: the Attachements field (encrypted with attachment key) is missing from this picture.*

##### Metadata payloads





### Account Group

Account Group is used within an account for communication and synchronization between devices linked to it.

Secrets of Account Group are generated by first device during the Account creation.

#### Account Specific Events/Payloads

- Group joined/left
- ContactRequestIn on/off/reset
- Contact block/unblock
- ContactRequestOutEnqueued
- ContactRequestOutSent / ContactRequestInReceived
- ContactRequestIn accepted/refused

### Contact Group

Contact Group is used for communication between two accounts that have been added as contacts.

Secrets of Contact Group are generated using ECDH with Account A and B ID keypairs.

#### Contact Specific Events/Payloads

- DiscloseAliasPK
- ContactRequestRefused

### Multi-Member Group

Multi-Member Group is used for communication between more than two accounts that are not necessarily contacts with each other.

Secrets of Contact Group are generated randomly by the group creator and sent to other member through invitation.

#### Multi-Member Specific Events/Payloads

- DiscloseAliasResolver
- GroupInitMember

## Replication

There are four different types of configurations you might want on a server or a NAS.

### Bot account

Create a new account and add it as contact to your real account.

- manually or programatically added to each Multi-Member Groups (could **not** join Account and Contact Groups of real Account)
- could have a different display name / PP
- could execute chat commands
- could read and write on every Multi-Member Group it was added to

### Linked device

Link your NAS/Server to your existing account. It will operates as any other account's device:

- automatically added to all Groups the Account is member of (including Account, Contact and Multi-Member Groups)
- could **not** have a different display name / PP
- could execute chat commands
- could read and write on every Groups the Account is member of
- can link a new device to account

### Replication device

Linked to account but won't get or generate won't get any secrets other than replication secrets (Attachment Keys, Group ID PK, Group Sig PK).

- automatically added to all Groups the Account is member of (including Account, Contact and Multi-Member Groups)
- could **not** have a different display name / PP
- could **not** execute chat commands
- could **not** read or write on any Groups
- can **not** link a new device to account

A replication device will only be able to replicate data to provide high-availability. It can't be used by an attacker to link a new device, retrieve any major secret or read decrypted message/metadata. Note also that it will be resource efficient compared to a Linked Device as it will do much less cryptographic operations (which can be very usefull when used on a NAS with a small ARM CPU).

### Replication Server

Publicly available zero-knowledge server, made available by Berty or by any other NGO/community/company, needs to be added manually (via an API) to a group to replicate its data. Won't get any secrets other than replication secrets (Attachment Keys, Group ID PK, Group Sig PK).

- manually or programatically added to each Group (including Account, Contact and Multi-Member Groups)
- could **not** read or write on any Groups

## To define

- Admin Role granting
- Send Contact Request to a Multi-Member Group member