Write and update documentation for Account Recovery and ODIS

docs/celo-codebase/protocol/identity/encrypted-cloud-backup.md

@@ -0,0 +1,62 @@
+---
+title: Encrypted Cloud Backup
+---
+
+<!-- TODO(victor): Do we want to use a more creative protocol name here -->
+
+Using built-in support for iOS and Android, mobile apps can save data backups to Apple iCloud and Google Drive respectively.
+When a user installs the wallet onto a new device, possibly after losing their old device, or reinstalls the app on the same device, it can check the user's Drive or iCloud account for account backup data.
+If available, this data can be downloaded and used to initialize the application with the recovered account information.
+
+Access to the user's cloud storage requires logging in to their Google or Apple account.
+This provides a measure of security, but is not enough to confidently store the wallet's account key.
+In order to provide additional security, the account key backup can be encrypted with a secret, namely a PIN or password, that the user has memorized or stored securely.
+This way, the users account key backup is only accessible to someone who can access their cloud storage account *and* knows their secret.
+
+Because user-chosen secrets, especially PINs, are susceptible to guessing by an attacker this secret must be [hardened](https://en.wikipedia.org/wiki/Hardening_(computing)) before it can be used as an encryption key.
+Using [ODIS](/celo-codebase/protocol/odis) for [key hardening](/celo-codebase/protocol/odis/use-cases/key-hardening), this scheme derives an encryption key for the account key backup that is resistant to guessing attacks.
+
+With these core components, we can construct a cloud backup system that allows users who remember their password or PIN, and maintain access to a cloud storage account, to quickly and reliably recover their account while providing solid security guarantees.
+
+Valora is currently working implement encrypted cloud backup, using the users access PIN for encryption.
+
+### Similar protocols
+
+- [iCloud Keychain](https://support.apple.com/guide/security/secure-icloud-keychain-recovery-secdeb202947/web) uses 6-digit PIN, hardened by an HSM app, and encrypt iCloud Keychain backups.
+- [Signal SVR](https://support.apple.com/guide/security/secure-icloud-keychain-recovery-secdeb202947/web) uses a 4-digit PIN or alphanumeric password, hardened by an Intel SGX app, to encrypt contacts and metadata.
+- [Coinbase Wallet](https://blog.coinbase.com/backup-your-private-keys-on-google-drive-and-icloud-with-coinbase-wallet-3c3f3fdc86dc) uses a password encrypted cloud backup to store user account keys. It is unclear if any hardening is used.
+- [MixIn Network TIP](https://github.com/MixinNetwork/tip) uses 6-digit PINs, hardened by a set of signers, to derive account keys
+
+## User experience
+
+Here we describe the user experience of the protocol as designed.
+Wallets may alter this flow to suite the needs of their users.
+
+### Onboarding
+
+During onboarding on a supported device, after the PIN or password is set and the account key is created, the user should be informed about cloud backup and given a chance opt-out of cloud backup for their account.
+If they opt out, the rest of the setup should be skipped as they will not be using cloud backup.
+
+On Android, when the user opts-in, they should be prompted to select a Google account that they would like to use to store the backup.
+On iOS, the user need not be prompted as there is a single Apple account on the device and the permissions architecture allows access to application-specific iCloud data without prompting the user.
+
+In the background, the chosen PIN or password and a locally generated salt value should be used to query ODIS.
+The resulting hardened key should be used to encrypt the account key mnemonic.
+The encrypted mnemonic and metadata, including the salt, should be stored in the user's cloud storage.
+
+### Recovery
+
+During recovery, the application should determine if a cloud backup is available.
+On iOS, this can be done automatically.
+On Android, the user may choose to restore from cloud backup, at which point they should be prompted to choose their Google account.
+
+If a backup is available the user may select to restore from cloud backup, at which point they should be asked for their PIN or password.
+Given the PIN or password, the application should combine it with the salt value and query ODIS to retrieve the hardened key for decrypting the account key backup.
+If successful, the user will be sent to the home screen.
+If unsuccessful, the user will be given the option to try again or enter their mnemonic phrase instead.
+
+Users should, by requirement of security, be given a limited number of attempts to enter their PIN or password.
+Attempts should be rate limited with a certain number of attempts available immediately (e.g. 3-5 attempts within the first 24 hours), and a limited number of additional attempts available after one or more waiting periods (e.g. up to 10-15 attempts over 3 days).
+Once all attempts are exhausted, the backup will become unrecoverable and the user will only be able to recover their account if they have their mnemonic phrase written down.
+
+<!-- TODO(victor): Add detailed information about the key derivation and file structure when the library is implemented and can be referenced -->

docs/celo-codebase/protocol/identity/index.md

@@ -9,9 +9,9 @@ Celo’s unique purpose is to make financial tools accessible to anyone with a m
 
 ### Adding their phone number to the mapping
 
-To allow Bob to find an address mapped to her phone number, Alice can request attestations to their phone number \(technically the hash of their phone number\) from the `Attestations` contract by transferring the attestation request fee to it. The fee per attestation request is set on the contract with [Governance](celo-codebase/protocol/governance.md). After a brief waiting time of currently `4` blocks, the `Attestations` contract will use the `Random` contract to do a random selection over the current validator set in the `Validators` contract who will become responsible for these attestation requests.
+To allow Bob to find an address mapped to her phone number, Alice can use the decentralized attestations protocol to link an account address to their phone number. They start by making a request to the `Attestations` contract; transferring a fee along with their request. After a brief waiting time of `4` blocks (20 seconds), the `Attestations` contract will use the `Random` contract to produce a random selection of validators, from the current elected set in the `Validators` contract, to issue the attestation challenges.
 
-As part of the expectation to validators, they run the attestation service whose endpoint they register in their [Metadata](/celo-codebase/protocol/identity/metadata.md). Alice can identify the validators responsible for her attestation from the smart contract, determine the validators' attestation service URLs from their [Metadata](/celo-codebase/protocol/identity/metadata.md) and request attestations from them. In turn, the attestation service produces a signed secret message that acts as an attestation by that validator that Alice owns the phone number. The validator sends that message via SMS. Read more under [attestation service](#attestation-service).
+As part of the expectation to validators, they run the attestation service whose endpoint they register in their [Metadata](/celo-codebase/protocol/identity/metadata.md). After attestation issuers have been selected for their requests, Alice determine the validators' attestation service URLs from their [Metadata](/celo-codebase/protocol/identity/metadata.md) and request an attestation message to their phone number by sending a direct HTTPS request. In turn, the attestation service produces a signed secret message attesting to the ownership of the given phone number by the requesting account. The validator sends the message to Alice's phone number via SMS. Read more under [attestation service](#attestation-service).
 
 When Alice receives the text message, she can take that signed message to the `Attestations` contract, which can verify that the attestation came from the validator indeed. Upon a successful attestation, the validator can redeem for the attestation request fee to pay them for the cost of sending the SMS. In the end, we have recorded an attestation by the validator to a mapping of Alice’s phone number to her account address.
 

docs/celo-codebase/protocol/identity/phone-number-privacy.md

@@ -1,63 +1,39 @@
 ---
 title: Phone Number Privacy
 ---
+import PageRef from '@components/PageRef'
 
-Celo's [identity protocol](..) allows users to associate their phone number with one or more addresses on the Celo blockchain. This allows users to find each other on the Celo network using phone number instead of cumbersome hexadecimal addresses. The Oblivious Decentralized Identifier Service (ODIS) was created to help preserve the privacy of phone numbers and addresses.
+Celo's [identity protocol](..) allows users to associate their phone number with one or more addresses on the Celo blockchain.
+This allows users to find each other on the Celo network using phone number instead of cumbersome hexadecimal addresses.
+The Oblivious Decentralized Identifier Service (ODIS) was created to help preserve the privacy of phone numbers and addresses.
+
+<PageRef url="/celo-codebase/protocol/odis" pageName="ODIS" />
 
 ## Understanding the problem
 
-When a user sends a payment to someone in their phone's address book, the mobile client must look up the identifier for that phone number on-chain to find the corresponding Celo blockchain address. This address is needed in order to create a payment transaction. If cleartext phone numbers were used as network identifiers directly, then anyone would be able to associate all phone numbers with blockchain accounts and balances. If instead, the identifier was the hash of the recipient's phone number, attackers would still be able to associate phone numbers with accounts and balances via a [rainbow table attack](https://en.wikipedia.org/wiki/Rainbow_table).
+When a user sends a payment to someone in their phone's address book, the mobile client must look up the identifier for that phone number on-chain to find the corresponding Celo blockchain address.
+This address is needed in order to create a payment transaction, and the user may only know the phone number of the person they want to pay.
+If cleartext phone numbers were used as identifiers directly on the Celo network, then anyone would be able to associate all phone numbers with blockchain accounts and balances (e.g. After searching for addresses with a high balance, they could look up the associated phone number to [phish](https://en.wikipedia.org/wiki/Phishing) the account owner).
+If instead, the identifier was the hash of the recipient's phone number, attackers would still be able to associate phone numbers with accounts and balances via a [rainbow table attack](https://en.wikipedia.org/wiki/Rainbow_table).
 
 ## The solution
 
-The basis of the solution is to derive a user's identifier from both their phone number and a secret pepper that is provided by the Oblivious Decentralized Identifier Service (ODIS). In order to associate a phone number with a Celo blockchain address, the mobile wallet first queries ODIS for the pepper. It then uses the pepper to compute the unique identifier that's used on-chain.
+The basis of the solution is to derive a user's identifier from both their phone number and a secret pepper that is provided by the Oblivious Decentralized Identifier Service (ODIS).
+In order to associate a phone number with a Celo blockchain address, the mobile wallet first queries ODIS for the pepper.
+It then uses the pepper to compute the unique identifier that's used on-chain.
+
+Peppers produced by ODIS are cryptographically strong, and so cannot be guessed in a brute force or rainbow table attack.
+ODIS imposes a rate limit controlling how many peppers any individual can request, and so prevents an attacker from scanning a large number of phone numbers in an attempt to compromise user privacy.
 
-### Pepper request quota
+### Pepper request rate limiting
 
-ODIS imposes a quota on requests for peppers in order to limit the feasibility of rainbow table attacks. When ODIS receives a request for a pepper, it authenticates the request and ensures the requester has not exceeded their quota. Since blockchain accounts and phone numbers are not naturally Sybil-resistant, ODIS bases request quota on the following factors:
+ODIS imposes a rate limit on requests for peppers in order to limit the feasibility of rainbow table attacks.
+When ODIS receives a request for a pepper, it authenticates the request and ensures the requester has not exceeded their quota.
+Since blockchain accounts and phone numbers are not naturally Sybil-resistant (i.e. individuals can have many accounts or phone numbers), ODIS bases request quota on the following factors:
 
 - Requester transaction history
 - Requester phone number attestation count and success rate
 - Requester account balance
 
 The requirements for these factors are configured to make it prohibitively expensive to scrape large quantities of phone numbers while still allowing typical user flows to remain unaffected.
-
-## Oblivious Decentralized Identifier Service
-
-### Distributed Key Generation
-
-For the sake of user privacy, no single party should have the ability to unilaterally compute the pepper for a given phone number. To ensure this, ODIS was designed to be decentralized across a set of reputable participants. Before the ODIS was deployed, a set of operators participated in a Distributed Key Generation (DKG) ceremony to generate parts of a shared secret. Details of the the DKG setup can be found [in the Celo Threshold BLS repository](https://github.com/celo-org/celo-threshold-bls-rs). Each ODIS node holds a share of the key which can be used to sign the response to the user. When enough of these signatures are combined, their combination can be used to derive a unique, deterministic phone number pepper. The number of key holders (_m_) and threshold of signatures required (_k_) are both configurable at the time of the DKG ceremony.
-
-### Rotating keys
-
-In the case that a key is compromised or a new ODIS operator is added, it will be necessary to perform a key rotation. Before going over the key rotation process, let's take a look at the implications of a compromised key. If the number of keys compromised at a time is less than the threshold _k_, the attacker will not be able to reach a sufficient threshold to compute the pepper for all phone numbers. Similarly, as long as _k_ other keys remain uncompromised, good users will still be able to perform the pepper lookup as part of the ODIS. Therefore, in the case that a single key is compromised, user data will remain private and the service operational; however, it's important that we can detect and perform a key rotation before the number of keys compromised exceeds _k_ or _m - k + 1_ (whichever is lower). For example, if there are ten ODIS operators and the required threshold is three, then if three of them are compromised an attacker may compute the pepper for all phone numbers. If eight are compromised then an attacker may prevent the rest of the nodes (two in this case) from generating the pepper for users. Note that "compromised" entities in these examples could also be malicious or simply unavailable.
-
-To rotate keys, a new DKG ceremony must be performed with at least _k_ of the _m_ original keys. These newly generated keys will not be compatible with the old keys; however if _k_ of the old keys are used, an attacker may still reach the necessary threshold.Therefore, it's extremely important that all of the old keys are destroyed after a successful key rotation. Note that a DKG ceremony also provides the opportunity to change the values for _k_ and _m_.
-
-### Blinding
-
-When a client, like the Celo wallet, queries ODIS to retrieve a phone number pepper, the client first blinds the phone number locally. This blinding process preserves the privacy of the mobile number such that ODIS nodes cannot determine what number they're providing a pepper for; reducing risk of targeted censorship and further increasing privacy. After the application receives the response, it unblinds it to compute the pepper.
-
-### Combiner
-
-To facilitate the multi-service communication needed for the K of M signing, ODIS includes a combiner service which performs this orchestration for the convenience of wallets and other clients building on Celo. Like ODIS signer nodes, the combiner only receives the blinded phone number and therefore cannot see what number it's handling. The combiner also validates the response from each signer to ensure a corrupt signer cannot corrupt the resulting pepper.
-
-Anyone who wishes to participate in the ODIS service may run a combiner. Currently, cLabs operates one such combiner that may be used by other projects building on Celo.
-
-## Authentication
-
-In order to measure the quota for a given requester, ODIS must check their account information on the Celo blockchain. To prove ownership over their account, the POST request contains an Authorization header with the signed message body. When ODIS nodes receive the request, it authenticates the user by recovering the message signer from the header and comparing it to the value in the message body.
-
-## Request Flow Diagram
-
-![request flow diagram](https://storage.googleapis.com/celo-website/docs/ODIS-flow-diagram.svg)
-
-## Architecture
-
-![architecture diagram](https://storage.googleapis.com/celo-website/docs/ODIS-architecture-diagram.svg)
-
-The hosted architecture is divided into two components, the Combiner and the Signers. Currently the combiner is a cloud function and the signers are independent NodeJs servers. Both services leverage the [Celo Threshold BLS library](https://github.com/celo-org/celo-threshold-bls-rs) which has been compiled to [a Web Assembly module](https://github.com/celo-org/blind-threshold-bls-wasm).
-
-The combiner and signers maintain some minimal state in a SQL database, mainly related to quota tracking.
-
-For storage of the BLS signing key, the signers currently support three cloud-based keystores: Azure Key Vault, AWS Secret Manager, and Google Secret Manager.
+In particular, it should be possible for a user to look up their contacts in order to send them payments.