11 KiB
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
- Abstract
- Table of Contents
- Introduction
- Initial Key Generation
- Account Broadcasting
- Optional Account additions
- Trust establishment
- Security Considerations
- Changelog
Introduction
The core concept of an account in Status is a set of cryptographic keypairs. Namely, the combination of the following:
- a Whisper/Waku chat identity keypair
- 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)- following EIP1581
- 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
- Whisper/Waku Chat Key (
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.
- Status does not publish one-time keys
- 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
- Identity Key:
- 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
- matches
Private 1:1 messages
This can be done in the following ways:
- scanning a user generated QR code
- discovery through the Status app
- asynchronous X3DH key exchange
- public key via public channel listening
status-react/src/status_im/contact_code/core.cljs
- contact codes
- decentralized storage (not implemented)
- 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
, whereIK
is the hex encoded public key of the user, prefixed with0x
. 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.
- implementation: gfycat
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 TODO
- Added language to include Waku in all relevant places
- Change to keep
Mailserver
term consistent - Added clarification to Open Whisper Systems