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

11 KiB
Raw Blame History

permalink parent title
/spec/2 Stable specs 2/ACCOUNT

2/ACCOUNT

Version: 0.3

Status: Stable

Authors: Corey Petty corey@status.im, Oskar Thorén oskar@status.im, Samuel Hawksby-Robinson samuel@status.im (alphabetical order)

Abstract

In this specification we explain what Status account is, and how trust is established.

Table of Contents

Introduction

The core concept of an account in Status is a set of cryptographic keypairs. Namely, the combination of the following:

  1. a Whisper/Waku chat identity keypair
  2. a set of cryptocurrency wallet keypairs

Everything else associated with the contact is either verified or derived from the above items, including:

  • Ethereum address (future verification, currently the same base keypair)
  • 3 word mnemonic name
  • identicon
  • message signatures

Initial Key Generation

Public/Private Keypairs

  • An ECDSA (secp256k1 curve) public/private keypair MUST be generated via a BIP43 derived path from a BIP39 mnemonic seed phrase.
  • The default paths are defined as such:
    • Whisper/Waku Chat Key (IK): m/43'/60'/1581'/0'/0 (post Multiaccount integration) 
    - Status Wallet paths: `m/44'/60'/0'/0/i` starting at `i=0`
  - following [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
  - NOTE: this (`i=0`) is also the current (and only) path for Whisper/Waku key before Multiaccount integration

X3DH Prekey bundle creation

  • Status follows the X3DH prekey bundle scheme that Open Whisper Systems (not to be confused with the Whisper sub-protocol) outlines in their documentation with the following exceptions:
    • Status does not publish one-time keys OPK or perform DH including them, because there are no central servers in the Status implementation.
  • A client MUST create X3DH prekey bundles, each defined by the following items:
    • Identity Key: IK
    • Signed prekey: SPK
    • Prekey signature: Sig(IK, Encode(SPK))
    • Timestamp
  • These bundles are made available in a variety of ways, as defined in section 2.1.

Account Broadcasting

  • A user is responsible for broadcasting certain information publicly so that others may contact them.

X3DH Prekey bundles

  • A client SHOULD regenerate a new X3DH prekey bundle every 24 hours. This MAY be done in a lazy way, such that a client that does not come online past this time period does not regenerate or broadcast bundles.
  • The current bundle SHOULD be broadcast on a Whisper/Waku topic specific to his Identity Key, {IK}-contact-code, intermittently. This MAY be done every 6 hours.
  • A bundle SHOULD accompany every message sent.
  • TODO: retrieval of long-time offline users bundle via {IK}-contact-code

Optional Account additions

ENS Username

  • A user MAY register a public username on the Ethereum Name System (ENS). This username is a user-chosen subdomain of the stateofus.eth ENS registration that maps to their Whisper/Waku identity key (IK).

Trust establishment

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/Waku key pubkey for chat with HD derivation path m/43'/60'/1581'/0'/0

Contact Discovery

Public channels

  • Public group channels in Status are a broadcast/subscription system. All public messages are encrypted with a symmetric key derived 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's web3.ssh.generateSymKeyFromPassword function
  • In order to post to a public group channel, a client MUST have a valid account created.
  • 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:
    • matches [a-z0-9\-]
    • is not a public key

Private 1:1 messages

This can be done in the following ways:

  1. scanning a user generated QR code
  2. discovery through the Status app
  3. asynchronous X3DH key exchange
  4. public key via public channel listening
    • status-react/src/status_im/contact_code/core.cljs
  5. contact codes
  6. decentralized storage (not implemented)
  7. Whisper/Waku

Initial Key Exchange

Contact Request

Bundles

  • An X3DH prekey bundle is defined as (code): 
    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
    • include BundleContainer
  • a new bundle SHOULD be created at least every 12 hours
  • a bundle is only generated when it is used
  • a bundle SHOULD be distributed on the contact code channel. This is the Whisper and Waku topic {IK}-contact-code, where IK is the hex encoded public key of the user, prefixed with 0x. The channel is encrypted in the same way public chats are encrypted.

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/Waku chat public key. This can then be compared out of band to ensure the receiver's public key is the one you have locally.

3 word pseudonym / Whisper/Waku key fingerprint

Status generates a deterministic 3-word random pseudonym from the Whisper/Waku chat public key. This pseudonym acts as a human readable fingerprint to the Whisper/Waku chat public key. This name also shows when viewing a contact's public profile and in the chat UI.

ENS name

Status offers the ability to register a mapping of a human readable subdomain of stateofus.eth to their Whisper/Waku chat public key. This registration is purchased (currently by staking 10 SNT) and stored on the Ethereum mainnet blockchain for public lookup.

Security Considerations

Changelog

Version 0.3

Released May 22, 2020

  • Added language to include Waku in all relevant places
  • Change to keep Mailserver term consistent
  • Added clarification to Open Whisper Systems