specs/x5.md

---
sip: x5
title: Initial Trust Establishment Specification
status: Draft
type: Standard
author: Corey Petty <corey@status.im>, Oskar Thorén <oskar@status.im>
created: 2019-04-18
updated:
---

# Trust Establishment Protocol Specification Draft
## Inspiration
- https://datprotocol.github.io/how-dat-works/
- 

:::info
**Trust establishment deals with users verifying they are communicating with who they think they are.**
:::

## Terms Glossary
| term | description |
| ---- | ----------- |
| privkey | ECDSA secp256k1 private key |
| pubkey | ECDSA secp256k1 public key |
| whisper key | pubkey for chat with HD derivation path m/44'/60'/0'/0/0 |


## Information Gathering Notes
:::danger
how do we identify nodes (mailservers/bootnodes/etc)
:::
possible connections
- client - client (not really ever, this is facilitated through all other connections)
    - personal chat
        - ratcheted with X3DH
    - private group chat
    - public chat
- client - mailserver (statusd + ???)
    - a mailserver identifies itself by ???
- client - whisper node (statusd)
    - a node identifies itself by ???
- client - bootnode (geth)
    - a bootnode identifies itself by ???
- client - ENS registry (ethereum blockchain -> default to infura)
- client - Ethereum RPC (custom geth RPC API -> default to infura API)
- client - IPFS (Status hosted IPFS gateway -> defaults to ???)

A user in the system is a public-private key pair using the Elliptic-Curve Cryptography secp256k1 that Ethereum uses.
- A 3-word random name is derived from the public key using the following package
    - 
    - This provides an associated human-readble fingerprint to the user's public key
- A user can optionally add additional layers on top of this keypair
    - Chosen username
    - ENS username

All messages sent are encrypted with the public key of the destination and signed by the private key of the given user using the following scheme:
- private chat
    - the message is encrypted with the public key of the intended user
- private group chat
    - the message is pairwise encrypted with each of the public keys of the members of the private group, e.g. for a group of 6 members, 5 messages will be sent. 
- public group chat
    - the message is encrypted with the topic 

## Initial Trust Establishment Specification
### 1. Contact Discovery
#### 1.1 Public channels
- Public group channels in Status are a broadcast/subscription system.  All public messages are encrypted with a symmetric key drived from the channel name, $K_{\text{pub,sym}}$, which is publicly known.
- A public group channel's symmetric key MUST creation must follow the [web3 API](https://web3js.readthedocs.io/en/1.0/web3-shh.html#generatesymkeyfrompassword)'s `web3.ssh.generateSymKeyFromPassword` function
- In order to post to a public group channel, a client MUST have a valid account created (as per section [Account Creation Specification](#Account-Creation) TODO: LINK THIS).
- In order to listen to a public group channel, a client must subscribe to the channel name.  The sender of a message is derived from the message's signature.
- Discovery of channel names is not currently part of the protocol, and is typically done out of band.  If a channel name is used that has not been used, it will be created.
- channel name specification:
    - lower case alphanumeric
    - no special characters excluding `-`
    - TODO: other langauge characters

#### 1.2 Private 1:1 messages
This can be done in a the following ways:
1. scanning a user generated QR code
1. discovery through the Status app
1. asyncronous X3DH key exchange
1. public key via public channel listening
    - `status-react/src/status_im/contact_code/core.cljs`
1. contact codes
2. decentralized storage (not implemented)
3. whisper

### 2. Initial Key Exchange

#### Contact Request

#### Bundles
- NOTE: cant seem to find bundle code on account generation
- An X3DH prekey bundle is defined as ([code(https://github.com/status-im/status-go/messaging/chat/protobuf/encryption.pb.go)]):
  ```
  Identity                // Identity key
  SignedPreKeys           // a map of installation id to array of signed prekeys by that installation id
  Signature               // Prekey signature
  Timestamp               // When the bundle was lasted created locally
  XXX_NoUnkeyedLiteral    // ???
  XXX_unrecognized        // ???
  XXX_sizecache           // ???
  ```
  - include BundleContainer???
- a new bundle SHOULD be created at least every 12 hours
#### QR code
- A generated QR code should include a X3DH bundle set along with the contact code but I can't find the code to do so.

### 4. Contact Verification
Once you have the information of a contact, the following can be used to verify that the key material is as it should be.
#### Identicon
A low-poly identicon is deterministically generated from the whisper chat public key.  This can then be compared out of band to ensure the reciever's public key is the one you have locally.
#### 3 word pseudonym / whisper key fingerprint
Status generates a deterministic 3-word random pseudonym from the whisper chat public key.  This pseudonym acts as a human readable fingerprint to the whisper chat public key.  This name also shows when viewing a contact's public profile and in the chat UI.
- implementation: [gfycat](https://github.com/status-im/status-react/tree/develop/src/status_im/utils/gfycat)
#### ENS name
Status offers the ability to register a mapping of a human readable subdomain of `stateofus.eth` to their whisper chat public key.  This registration is purchased (currently by staking 10 SNT) and stored on the Ethereum mainnet blockchain for public lookup.

## Security Implications
 
 
# Previous stuff (introduction)

## Requirement

TODO: Fill out and requirement such as cryptographic primitives for key generation, possibly secure vault storage.

## Design goals

TODO: Something briefly on adversary model, i.e. https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BQP.md

TODO: Elaborate on section of requirements below
Security properties

Network MitM Prevented
Operator MitM Prevented
Operator MitM Detected
Operator Accountability
Key Revocation Possible
Privacy Preserving
Usability

Automatic Key Initialization
Low Key Maintenance
Easy Key Discovery
Easy Key Recovery
In-Band
No Shared Secrets
Alert-less Key Renewal
Immediate Enrollment
Inattentive User Resistant
Adoptability

Multiple Key Support
No Service Provider
No Auditing Required
No Name Squatting
Asynchronous
Scalable

NOTE: Several of these we don't do, and e.g. ENS/mutlikey stuff can be noted as future enhancement

## Trust establishment

Trust establishment deals with users verifying they are communicating with who they think they are. In this document we specify how trust is established in Status, and what guarantees we make and don't make.

*NOTE: Also see https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BQP.md for inspiration of example in terms of document layout and granularity.*

## Raw SoK evaluation import

Importing document done by Corey and Oskar.

**TODO: Phrase these in terms of what guarantees we provide more clearly, in active voice**

## Trust Establishment
Trust establishment deals with users verifying they are communicating with who they think they are.

### --- Security and Privacy Features
#### Network MitM Prevention (PARTIAL)
> Prevents Man-in-the-Middle (MitM) attacks by local and global network adversaries.

- We use Trust On First Use (TOFU). This is a form of opportunistic encryption. A user doesn't verify another one before talking, in the normal case. However, since a user is tied to a public key, subsequent communication will rely on that key. Unlike, say, a naive username.
- For the initial connection, there's no way of verifying that the public key actually belongs to that user.
- This also touches on impersonation for end UX, since a user can easily pretend to be someone else by setting any display name they want.
- We also have ENS naming system that links a username registered under \*.stateofus.eth to a public-key.  This means that you have to trust whomever owns that subdomain (staked in SNT) to be the owner of the public-key it resolves to. This can act as a form of key directory.
- Ways of improving this:
    - Briar requires users to be in close proximity and use QR codes
    - Additionally, a introducing client a la web of trust can be used; A knows B, B knows C, so B can introduce A and C.
- all messages are encrypted with public key of recipient and signed by sender
- https://blog.securegroup.com/the-socialist-millionaire-protocol-how-secure-chat-prevents-mitm-attacks

#### Operator MitM Prevention (PARTIAL)
> Prevents MitM attacks executed by infrastructure operators.

- See above. There's no specific additional infrastructure.

#### Operator MitM Detection (PARTIAL)
> Allows the detection of MitM attacks performed by operators after they have occurred.

- See above. For multiple devices that are paired, you *should* get notified when a new device is added and synced. However, this requires additional analysis to ensure this invariant holds.
- Each message is signed and *should* be verified.
- TODOS:
    - Verify that you always get notified when device is added.
    - Verify that signatures are verified at each message receival.

#### Operator Accountability (PARTIAL)
> It is possible to verify that operators behaved correctly during trust establishment.
 
- See above. 
- For ENS names, we can assume that the smart contract is working as intended for resolving to public keys.  The are two ways in which this can be compromised:
    - ENS subdomain owner is compromised and redirects the name to a different public-key
    - ENS system is hacked.

#### Key Revocation Possible (NO)
> Users can revoke and renew keys (e.g., to recover from key loss or compromise).

- changing public-key is changing identity
- you cannot currently revoke keys once establishment has been made

If you add a pairing device you can't unpair it (ghost membership vulnerability)

In the future:
- Functionality like universal logins will handle multiple keys under a single identity

Another interesting idea would be to have revocation contract, where people can blacklist their own keypair as a form of revocation. E.g. by default in public chats it'd show up as "compromised account". Sparse merkle trees can be used for this.

#### Privacy Preserving (PARTIAL)
> The approach leaks no conversation metadata to other participants or even service operators.

- By default, yes.
- ENS names are not privacy preserving, but that is an optional feature and it doesn't cover linking of identities.
- Your exposure in public chats could expose your identity as your public key is available.
- Out-of-band is privacy preserving. I.e. if you only have a public key and add someone with a QR code.

comments:
- In web of trust, like Keybase, the links between individuals are public. We currently don't have this mechanism, but this is also relevant when it comes to things like Shamir's key sharing for account recovery.

### --- Usability Properties

#### Automatic Key Initialization (YES)
>No additional user effort is required to create a long-term key pair.

- All key-pairs are HD generated and maintained by the software (or keycard if available)

#### Low Key Maintenance (YES)
>  Key maintenance encompasses recurring effort users have to invest into maintaining keys. Some systems require that users sign other keys or renew expired keys. Usable systems require no key maintenance tasks
  
- no key maintenance is required, only safekeeping of the backup seed phrase.
- In the future, functionality like universal logins would be useful to extend the options of user-facing key maintanence and device risk/revocation.

#### Easy Key Discovery (YES)
> When new contacts are added, no additional effort is needed to retrieve key material.

- contacts are at a base-layer a public-key
- additionally, by using ENS a kind of display name can be used for human-readable links. E.g. foo.barclub.stateofus.eth

#### Easy Key Recovery (YES)
> When users lose long-term key material, it is easy to revoke old keys and initialize new keys (e.g., simply reinstalling the app or regenerating keys is sufficient).

- Key recovery is re-initializing your account with your backed up recovery phrase, which rederives all needed keys

#### In-band (YES)
> No out-of-band channels are needed that require users to invest additional effort to establish.

- currently yes, but this might not be desirable in the future for stronger security guarantees.

#### No Shared Secrets (YES)
> Shared secrets require existing social relationships. This limits the usability of a system, as not all communication partners are able to devise shared secrets.

- A user is a public-key so it doesn't require coordination

#### Alert-less Key Renewal (NO)
> If other participants renew their long-term keys, a user can proceed without errors or warnings.
 
- There is no key renewal for base trust establishment, a user is a public-key
- In the future, Universal logins will help with this maintanence and functionality

#### Immediate Enrollment (YES)
> When keys are (re-)initialized, other participants are able to verify and use them immediately

comments:
- HD public keys have been setup to extend the functionality of having multiple identities under a single public key.  We currently only derive a single public key for conversation, but have the option to do more for identity management. 

#### Inattentive User Resistant (YES)
> Users do not need to carefully inspect information (e.g., key fingerprints) to achieve security.

- Currently and in general, yes.
- It is worth mentioning that we also use three random names as a shorthand mapping for public keys. This is useful to casually establish provenance in a public chat. Additionally we have display names that are user set (and visible to someone who is added as a contact), which could lead to impersonation attacks.
- Note that the possible amount of 3-word pseudonyms is drastically smaller than the possible amount of public keys, so there is potential for collisions, and therefor impersonation attacks here as well.

### --- Adoption Properties

#### Multiple Key Support (NO)
> Users should not have to invest additional effort if they or their conversation partners use multiple public keys, making the use of multiple devices with separate keys transparent. While it is always possible to share one key on all devices and synchronize the key between them, this can lead to usability problems.

- In the future, Universal logins will help with this, as it manages multiple keys and their associated device and risk, and also enables multi-factor authentication for various features. 
- Furthermore, HD wallets could add some multi-key functionality (e.g. different keypairs on each device), but it would probably be best to stick with universal logins.

comments: 
- potential for self-signed attestations to universal blacklist for compromised keys. (sparse merkle tree for lookup)

#### No Service Provider Required (YES)
> Trust establishment does not require additional infrastructure (e.g., key servers).
 
- Not required for trust establishment

#### No Auditing Required (YES)
> The approach does not require auditors to verify correct behavior of infrastructure operators.

- Not required for trust establishment

#### No Name Squatting (PARTIAL)
> Users can choose their names and can be prevented from reserving a large number of popular names

- In general, yes.
- Public keys have a big space. For three-random words it is possible to generate arbitrary combinations with decent computational resources, but this doesn' amonut to "reserving" it.
- For ENS, no. But for each name, a stake of 10 SNT is required, as well as the creation of a new identity (unless they interact directly with the ENSregistration contract directly and not through the app)

#### Asynchronous (YES)
> Trust establishment can occur asynchronously without all conversation participants online.

Yes.

#### Scalable (YES)
> Trust establishment is efficient, with resource requirements growing logarithmically (or smaller) with the the total number of participants in the system

Yes.