status-im
/
specs
mirror of https://github.com/status-im/specs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

addressed comments from PR #25

This commit is contained in:
Corey 2019-08-27 16:40:53 -04:00
parent 032d7adea6
commit 7d203206ee
1 changed files with 44 additions and 252 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

296
x5.md
View File

@ -13,9 +13,7 @@ updated:
- 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 |
@ -25,54 +23,19 @@ updated:
| 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.
- 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_{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 post to a public group channel, a client MUST have a valid account created (as per section [Account Creation Specification](./status-account-spec)).
- 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.
- A client MUST sign the message otherwise it will be discarded by the recipients.
- channel name specification:
- lower case alphanumeric
- no special characters excluding `-`
- TODO: other langauge characters
- matches `[a-z0-9\-]`
- is not a public key
#### 1.2 Private 1:1 messages
This can be done in a the following ways:
@ -90,19 +53,18 @@ This can be done in a the following ways:
#### 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
- a bundle is only generated when it is used
- a bundle MUST be distributed on the contact code channel (NOTE: define this where?)
#### 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.
@ -117,215 +79,45 @@ Status generates a deterministic 3-word random pseudonym from the whisper chat p
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
## General Comments
TODO: Fill out and requirement such as cryptographic primitives for key generation, possibly secure vault storage.
### Possible Connection Breakdown
## Design goals
possible connections
- client - client (not really ever, this is facilitated through all other connections)
- personal chat
- ratcheted with X3DH
- private group chat
- pairwise ratcheted with X3DH
- public chat
- client - mailserver (statusd + ???)
- a mailserver identifies itself by an [enode address](https://github.com/ethereum/wiki/wiki/enode-url-format)
- client - whisper node (statusd)
- a node identifies itself by an enode address
- client - bootnode (geth)
- a bootnode identifies itself by
- an enode address
- `NOTE: redezvous information here`
- 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 ???)
- we have a status hosted IPFS gateway for pinning but it currently isn't used much.
TODO: Something briefly on adversary model, i.e. https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BQP.md
### Notes
TODO: Elaborate on section of requirements below
Security properties
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
- `NOTE: need to find 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
- Network MitM Prevented
- Operator MitM Prevented
- Operator MitM Detected
- Operator Accountability
- Key Revocation Possible
- Privacy Preserving
- Usability
<br />
- 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
<br />
- 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/multikey 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 maintenance 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 re-derives 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 maintenance 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't amount 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 ENS registration 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.
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
- X3DH is used to define shared secrets which is then double ratcheted
- private group chat
- considered pairwise private chats
- public group chat
- the message is encrypted with a symmetric key derived from the chat name