# Core Vault

The Core Vault is a secure key custody solution, provided as part of the Webkey infrastructure. It is implemented at the system level, using the most secure environment available on the mobile device; for example, secure execution environments provided by the processor, TEE(Trusted Execution Environment) and Hardware Security Module integrated into the mobile device hardware, etc. The key design principles of the Core Vault are:

* All secrets (seeds, private keys, passwords, etc) should be handled only in privileged environments, separated from the Android OS and user applications. Nothing on the system, other than the Core Vault itself, should ever have access to these secrets.
* All secrets should be encrypted at rest, using keys only available to the Core Vault.
* All user inputs (for e.g., passwords or biometrics) that are used to secure Core Vault secrets should also be handled only within the same privileged environments in which the Core Vault runs.

This design ensures that, even if there is a compromise of a higher layer component, such as the operating system or a user app, the secrets stored within the Core Vault remain protected.



### Seeds

Seeds are secrets from which all account keys, both private and public, are derived. They are often represented as [BIP-0039](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) phrases, a sequence of 12 or 24 words from a known [wordlist](https://github.com/bitcoin/bips/blob/master/bip-0039/english.txt). These are the most sensitive piece of data that are handled by the Seed Vault; from these seeds, all user-facing accounts are derived. Accounts are derived using a hierarchical derivation algorith, for e.g. [SLIP-0010](https://github.com/satoshilabs/slips/blob/master/slip-0010.md).

The Core Vault is capable of storing at least 12 separate seeds, each secured by a user-provided password and (optionally) biometrics, such as a fingerprint. These passwords and biometrics are used as part of encrypting seeds when being written to storage, ensuring that only the user possessing these passwords and biometrics are capable of "unlocking" a seed in the Core Vault. Each seed has a separate configuration of password and biometrics, allowing for users to provided differentiated levels of security for different accounts (for e.g., a daily use account secured with biometrics, and a long-term storage account secured using a strong password).

Wallet apps must separately request authorization for each seed. Users are free to grant or deny this access on an app-by-app basis, ensuring that they remain in control of which seed(s) each app can obtain metadata and submit transaction signing requests for. This would allow, for e.g., a user to maintain entirely separate seeds for different wallets, ensuring that even the set of accounts associated with a seed are not visible to other applications.



### Private keys

Private keys are derived from seeds using a hierarchical derivation algorithm. No details of a private key are exposed to wallet apps; instead, they use the Wallet APIs to submit signing requests for a [BIP-0032](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) derivation path. Users must authorize all signing requests (using the password for the corresponding seed or their biometrics, depending on the configuration for the seed).



### Public keys

Public keys are also derived from seeds using the same hierarchical derivation algorithm as the corresponding private keys. The Core Vault does make public keys available to wallets authorized to access a seed. Wallets can enumerate the public keys for all known accounts, as well as retrieve and manage account metadata (such as name, account flags, etc).

When a seed is first authorized, the Seed Vault immediately derives public keys for a number of accounts using several different common derivation paths (such as `m'/44'/501'/X'`, `m/44'/501'/X'/0'`, etc). This ensures that the public keys for these accounts can be enumerated immediately by wallet apps, without requiring the user to input their password or biometrics to unlock the necessary seed. If a wallet desires to derive an account public key with a non-standard derivation path scheme, the user will be asked for their password or biometrics the first time that account is used. The public key for that account will be cached, ensuring that subsequent access to the account public key and metadata will not require explicit user authorization.



### Signature Algorithm

The following signature algorithms are supported in Core Vault:

* Secp256k1
* Ed25519
* Secp256r1
* RSA



### Encryption/Decryption Algorithm

The following encryption/decryption algorithms are supported in Core Vault:

* AES
* ECIES
* RSA
* FHE(Fully Homomorphic Encryption) GSW



### User interfaces

The Core Vault provides several different user interfaces in response to requests made by wallets. These user interfaces run in either an ordinary Android OS context, or in a secure execution environment UI context, depending on the sensistivity of the data they handle.

* Ordinary Android UI
  * Seed authorization detail
  * Transaction approval detail
  * Public key derivation detail
* Secure execution environment UI
  * Seed password entry



### Core Vault Workflow

<figure><img src="https://2390781907-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxnN6Cwxl5ZEBL4idTAzK%2Fuploads%2FVIY2EjTeGlvACzVlEKpn%2Fwebkey-vault.drawio.png?alt=media&#x26;token=96f3e7cb-d296-4fb9-81eb-fcc961ff4009" alt=""><figcaption><p>Core Vault Workflow</p></figcaption></figure>

