The article goes by explaining different components in the app that relate to the secret storage. At the end of the article, I include a very rough code path that describes how the extension to create a new wallet. Note that Wallet secrets in this article refer to the seed phrase(mnemonic) and private keys.<\/p>\n\n\n\n
\ud83e\udd8aKeyring<\/h3>\n\n\n\n
Keyring<\/strong> is the core concept of the secret storing and account management system in MetaMask. KeyringController<\/a> is the implementation of the keyring. Cited from the KeyringController README<\/a>:<\/p>\n\n\n\n Here is the visual reference of the keyring structure: <\/p>\n\n\n\n The circular ring represents the seed phrase that is used to generate public key-private key pairs. Each key hangs on the ring is an individual wallet account with its private key drives from the seed phase. The seed phrase and all accounts data get bundled together, encrypted with an encryption key generated from the user password, and stores in the extension.<\/p>\n\n\n\n The KeyringController uses the “obs-store” class to store data. “obs-store” stands for ObservableStore, which is a synchronous in-memory store for a single value. The code also references the obs-store as a “Vault<\/strong>“. Let’s take a closer look at how it’s implemented: Two Inside the KeyringController class, the encryption and decryption operation is performed by the encryptor<\/a> object. <\/p>\n\n\n\n The encryptor object is assigned in the KeyringController constructor<\/p>\n\n\n\n The extension and the mobile app uses a different encryptor. The extension uses the browser-passworder<\/a> module, its source code is available<\/a> on Github. The mobile app has its own encryptor<\/a> class. They work pretty much the same, except for the PBKDF2<\/a> iteration and AES<\/a> mode. <\/p>\n\n\n\n Similar to extension, the mobile app adopts the Keyring structure to store secrets and manage accounts. For persistent storage, the app stores encrypted data with the async-storage<\/a> module that define in the The mobile wallet provides the “remember me” and ‘unlock with touch ID\/device passcode” options. Users don’t need to enter their password every time they open the app on their mobile devices.<\/p>\n\n\n\n To achieve this, the MetaMask mobile app stores the user password in the device with the SecureKeychain<\/a> module, which builds upon the “react-native-keychain<\/a>“. The user password is used to generate the key to decrypt the encrypted wallet secret in persistent storage. <\/p>\n\n\n\n Quick note on how “react-native-keychain” stores data in mobile devices:<\/p>\n\n\n\n Comment in the code explain what the SecureKeychain does:<\/p>\n\n\n\n “abstracting metamask specific functionality and settings” refers to the “remember me” and “sign in with touch ID\/device passcode” feature. Check out the As for “adding an extra layer of encryption”, I am curious about what’s the encryption key used here to perform the encryption? Here is the relevant code path I found:<\/p>\n\n\n\n What is the I download the Metamask<\/a> APK with this tool<\/a>, de-package with jadx<\/a>, search for the string “foxCode” and found this:<\/p>\n\n\n\n Wait, so the foxCode<\/strong> equal to the string “encrypt”? What’s the point of encrypting something with a hardcoded string? \ud83e\udd14<\/p>\n\n\n\n I send an email to the Metamask security team and ask for why does the user password encrypted with the hardcoded string(the foxCode) “encrypt”, the team responded: <\/p>\n\n\n\n I pretty much agree with him. But I still wonder why such code gets put in the codebase in the first place. <\/p>\n\n\n\n This is the end of the article. I hope it explains the basics of how MetaMask wallet stores your wallet secret. If you want to know more details, you can read its source code in their GitHub repo https:\/\/github.com\/MetaMask.<\/p>\n\n\n\n ==========================\ud83e\udd8aAppendix\ud83e\udd8a==========================<\/p>\n\n\n\n A very rough code path for the new wallet creation:<\/p>\n\n\n\n As a security engineer\/pentester in the blockchain space, I have tested many crypto wallet applications during research and client engagements. After seeing different ways of handing secrets in different wallets, I was curious about how MetaMask, one of the most famous crypto wallets in the space, does it. Well, if you ask me why I […]<\/p>\n","protected":false},"author":1,"featured_media":1170,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[2],"tags":[],"_links":{"self":[{"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/posts\/770"}],"collection":[{"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/comments?post=770"}],"version-history":[{"count":402,"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/posts\/770\/revisions"}],"predecessor-version":[{"id":1200,"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/posts\/770\/revisions\/1200"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/media\/1170"}],"wp:attachment":[{"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/media?parent=770"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/categories?post=770"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.wispwisp.com\/index.php\/wp-json\/wp\/v2\/tags?post=770"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}A module for managing groups of Ethereum accounts called \"Keyrings\", defined originally for MetaMask's multiple-account-type feature.\n\nThe KeyringController has three main responsibilities:\n *Initializing & using (signing with) groups of Ethereum accounts (\"keyrings\").\n *Keeping track of local nicknames for those individual accounts.\n *Providing password-encryption persisting & restoring of secret information.<\/code><\/pre>\n\n\n\n![\"\"](\"https:\/\/www.wispwisp.com\/wp-content\/uploads\/2021\/01\/Screen-Shot-2021-01-07-at-11.20.41-AM-1-863x1024.png\")
<\/figure>\n\n\n\nObservableStore<\/code> objects are created inside the KeyringController constructor<\/a>, one named “this.store<\/code>” and another one named “this.memStore<\/code>“: <\/p>\n\n\n\n![\"\"\/](\"https:\/\/lh4.googleusercontent.com\/AVqrCzrFG56xHcERypXP9YztqJndOTYnQwMbHu3nloTPs_rt1UKsrwm8v2h-PuGyLDM-2dmCtFvF705XwKJqWBjdn2_GUxpL4qK2n-n0ybCcjCv2cgPVJPrRgaXd1c1BXWcQWK74\")
this.store<\/code> stores the encrypted<\/strong> wallet secret. Data in this.store<\/code> will be put into the chrome extension local store for persistence data storage. Users can access the data by entering the following code in the extension development console. <\/p>\n\n\n\nchrome.storage.local.get('data', result => {\n var vault = result.data.KeyringController.vault\n console.log(vault)\n})<\/code><\/pre>\n\n\n\n![\"\"\/](\"https:\/\/lh3.googleusercontent.com\/PmierCh5NN78KGyXBRdto-iMbyMFW1rdxdohlOjMy98-j-gsYDDYmQilOrqxmoTuamilwmIvH1-8Zo4Qt9w_3GBtc54gQ8F0j1Gr6RqT27u0QUs_BNlHWFlNHIsl1oWPP0pj7Luw\")
this.memStore<\/code>, on the other hand, stores the decrypted<\/strong> wallet secrets. Data in this object stays in memory and will not be put into the browser’s persistent storage. When you open the MetaMask extension and enter your password, your decrypted account private key will be stored in the this.memStore<\/code> object for any future use. Reference 1<\/a>, Reference 2<\/a><\/p>\n\n\n\n\ud83e\udd8aencryptor<\/h3>\n\n\n\n
Ex1. Encrypt keyring data:\nreturn this.encryptor.encrypt(this.password, serializedKeyrings)\n\nEx2. Decrypt the encryptedVault\nconst vault = await this.encryptor.decrypt(password, encryptedVault)<\/code><\/pre>\n\n\n\n![\"\"](\"https:\/\/www.wispwisp.com\/wp-content\/uploads\/2020\/12\/Screen-Shot-2020-12-20-at-5.06.30-PM-1024x359.png\")
<\/figure>\n\n\n\nbrowser-passworder: \nGenerate enc_key from password: PBKDF2, 10000 iteration\nAES mode: AES-GCM\n\nMobile app encryptor: \nGenerate enc_key from password: PBKDF2, 5000 iteration\nAES mode: AES-CBC<\/code><\/pre>\n\n\n\n\ud83e\udd8aMobile App<\/h3>\n\n\n\n
persistConfig<\/a><\/code>. The only official documentation<\/a> I can find that describe how “async-storage” work says:<\/p>\n\n\n\nOn iOS, AsyncStorage is backed by native code that stores small values in a serialized dictionary and larger values in separate files. \n\nOn Android, AsyncStorage will use either RocksDB or SQLite based on what is available.<\/code><\/pre>\n\n\n\n![\"\"](\"https:\/\/lh4.googleusercontent.com\/950lj8d2ir46nDbVlq4gDMePqrKF_zmARY5DOmDpLpI35Z6G3P1wpKCGghbFyLgghYCyKSTn1AbOZ4mg-3lAXNBD7VZJviC9rUtlaKYXzyeyjy6sMYhrc3pxvpkz0uoAIAGEO2iu\")
![\"\"](\"https:\/\/lh3.googleusercontent.com\/X5aJa5OykYtxd8Es7893vZ3BRdjCAyde1hwScLjgJ9uG9UZj5cvCnFkE27jsc1voKsjOU5-nWCgDAv_41AFv-0R-WtX4MV0T2cCnr__ETNR4FLOInji9drqwxY7gG9R5WXssXG7N\")
\n\n\n\n\ud83e\udd8aSecureKeychain<\/a><\/h3>\n\n\n\n
\/**\n* Class that wraps Keychain from react-native-keychain\n* abstracting metamask specific functionality and settings\n* and also adding an extra layer of encryption before writing into\n* the phone's keychain\n*\/\nclass SecureKeychain {\n...\n}<\/code><\/pre>\n\n\n\nresetGenericPassword<\/code>, getGenericPassword<\/code> and setGenericPassword<\/code> function to see how it’s implemented. <\/p>\n\n\n\ncode<\/code> in the constructor is used as the encryption key. (Source<\/a>)<\/li>init<\/code> function is called with the argument props.foxCode<\/code> (Source<\/a>)<\/li><\/ol>\n\n\n\nfoxCode<\/code>? I searched in the mobile wallet repository<\/a> and all public repositories under the MetaMask organization<\/a>, but no result. Hmm\ud83e\udd14, how about the app binary? <\/p>\n\n\n\n![\"\"](\"https:\/\/www.wispwisp.com\/wp-content\/uploads\/2020\/12\/Screen-Shot-2020-12-18-at-2.01.38-AM-1-1024x257.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/www.wispwisp.com\/wp-content\/uploads\/2020\/12\/Screen-Shot-2020-12-18-at-1.54.12-AM-1024x424.png\")
<\/figure>\n\n\n\n\ud83e\udd8aThe end<\/h3>\n\n\n\n
1. metamask-extension\/ui\/app\/pages\/first-time-flow\/first-time-flow.component.js<\/a> <-- Click Me\nconst seedPhrase = await createNewAccount(password)\n\n2. metamask-extension\/ui\/app\/pages\/first-time-flow\/first-time-flow.container.js<\/a>\ncreateNewAccount: (password) =>\ndispatch(createNewVaultAndGetSeedPhrase(password))\n\n3. metamask-extension\/ui\/app\/store\/actions.js<\/a>\nexport function createNewVaultAndGetSeedPhrase(password){\n ....\n await createNewVault(password)\n const seedWords = await verifySeedPhrase()\n ....\n}\n\n4. metamask-extension\/app\/scripts\/metamask-controller.js<\/a>\nasync createNewVaultAndKeychain(password){\n vault = await this.keyringController.createNewVaultAndKeychain(password)\n}\n\n5. KeyringController\/blob\/master\/index.js<\/a>\ncreateNewVaultAndKeychain (password) {\n return this.persistAllKeyrings(password)\n .then(this.createFirstKeyTree.bind(this))\n .then(this.persistAllKeyrings.bind(this, password))\n .then(this.setUnlocked.bind(this))\n .then(this.fullUpdate.bind(this))\n}\n\n6. MetaMask\/KeyringController\/blob\/master\/index.js<\/a> createFirstKeyTree () {\n ... \n return this.addNewKeyring('HD Key Tree', { numberOfAccounts: 1 })\n ... \n} \n\n7. MetaMask\/KeyringController\/blob\/master\/index.js<\/a> addNewKeyring (type, opts) { \n ... \n const Keyring = this.getKeyringClassForType(type)\n const keyring = new Keyring(opts)\n ... \n}\n\n8. MetaMask\/eth-hd-keyring\/blob\/master\/index.js<\/a>\naddAccounts (numberOfAccounts = 1) {\n ...\n this._initFromMnemonic(bip39.generateMnemonic())\n ...\n}\n<\/pre>\n","protected":false},"excerpt":{"rendered":"