Chrome extension reference app demonstrating how users could sign transactions using various EOSIO Labs tools
A Chrome extension which demonstrates how users could sign transactions from EOSIO apps using various EOSIO labs tools.
EOSIO Labs repositories are experimental. Developers in the community are encouraged to use EOSIO Labs repositories as the basis for code and concepts to incorporate into their applications. Community members are also welcome to contribute and further develop these repositories. Since these repositories are not supported by Block.one, we may not provide responses to issue reports, pull requests, updates to functionality, or other requests from the community, and we encourage the community to take responsibility for these.
The EOSIO ecosystem is rich with existing wallets providing users the ability to sign transactions on the EOSIO blockchain. However, we have identified some limitations and possible areas for improvement to the overall user experience:
This Reference Implementation serves an example for wallet developers as possible solutions to the problems stated above from the Chrome desktop browser. The Chrome extension provides the following as reference:
^1.15.2
(latest stable).^10.15.3
LTS. NOTICE This project will not build on the current version of Node.js 12.3.1
due to an error in a sub-dependency of react-scripts
.yarn install
yarn build
build
folder.The Chrome extension follows the EOSIO Authentication Transport Protocol Specification. There is some configuration needed in the integrating app, and there are a few different ways to interact with the Chrome extension from an integrating app:
If you want to start out by test driving the EOSIO Reference Chrome Extension Authenticator App for yourself, we recommend checking out our Tropical Example web app. Tropical Example is a mock web application for renting properties and provides instructions and a script for setting up a local chain bootstrapped with all of the necessary, compliant contracts for making the experience work.
Specifically, follow the instructions under the Running Tropical Example header. (Of course, we recommend reading the rest of the README there too, which will provide more context around how the pieces work together to provide the user with a secure and positive user experience.)
hello my name is
.The data flow in the Chrome extension is unfortunately not straight-forward. Ultimately, integrating apps interact with the Chrome extension through the window messaging API. Internally, the Chrome extension uses various means of sending data between different parts of the extension. Here is an explanation of the data flow:
The Chrome extension uses the Chrome storage API for storing data. It uses both sync
and local
storage for different things. The only difference between sync
and local
storage is that sync
storage is synced across your Chrome browsers on different devices, and can store significantly less data.
sync
storage is used for storing Auths (encrypted private keys) and the user's hashed passphrase.
local
storage is used as a buffer to move data from the background script to the extension window, as described in the Data Flow section above. It also stores developer settings such as the insecure mode settings.The main extension window and the settings page are separate React apps, so changes to the state of one doesn't automatically propagate to the other. Because of this, the states of the React apps need to update when the Chrome storage changes. This is done by adding listeners to the onChanged event on Chrome storage. Here is a quick explanation:
onChanged
event on Chrome storage, which update the Redux store when changes happen to Chrome storage.The Chrome extension uses the Web Workers API for encrypting and decrypting keys. Web workers run scripts in background threads without interfering with the UI. Encryption and decryption rely on CPU intensive operations which hang up the extension UI. This performance hit is especially noticeable when users have several keys imported and they are updating the passphrase used to encrypt those keys. The keys need to all be decrypted with the old passphrase and then re-encrypted with the new passphrase, resulting in a frozen UI for several seconds. Using the web workers API allows the UI to continue functioning while encryption and decryption runs in a background thread.
The Chrome extension adheres to the Manifest Specification. All checks described in the Manifest Specification are validated in the Chrome Extension.
As part of the Manifest Specification, the Chrome extension will generate a eosio.assert::require
action with the following parameters:
chain_params_hash
: Hash of the chain information from the Application Metadata for the chain defined in the request envelope.manifest_id
: Hash of the Manifest for the chain defined in the request envelope.actions
: An array of actions whitelisted in the Manifest.abi_hashes
: An array of the hashed abis included in the request envelope.This action, with the above parameters, will be added to the transaction so that the chain can validate that these values match what is registered on chain. If any of these validations fail, the entire transaction will be rolled back and rejected.
The Chrome extension takes measures to assure users that private keys are securely stored.
hello my name is
. These requirements should be thoroughly reviewed for a production extension.sha256
hash function and stored in sync
storage. Passphrases are then validated by checking the sha256
of the provided passphrase making them NON-RECOVERABLE since they are never stored.The Chrome extension has a developer settings page that allows application developers to enable insecure mode
in order to bypass Manifest Specification security measures for development purposes only. Turning off security measures could lead to DISASTROUS results. :warning: USE THIS FEATURE WITH CAUTION. :warning:
To enable insecure mode
follow the steps below for both the Chrome extension and the application being developed.
insecure mode
open the Chrome extension and click on the settings cog icon in the upper right-hand corner.The integrating application must add the securityExclusions options to the Request Envelope as part of the EOSIO Authentication Transport Protocol Specification.
See LICENSE for copyright and license terms. Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any related applications. We make no representation, warranty, guarantee or undertaking in respect of the software or any related documentation, whether expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall we be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or documentation or the use or other dealings in the software or documentation. Any test results or performance figures are indicative and will not reflect performance under all conditions. Any reference to any third party or third-party product, service or other resource is not an endorsement or recommendation by Block.one. We are not responsible, and disclaim any and all responsibility and liability, for your use of or reliance on any of these resources. Third-party resources may be updated, changed or terminated at any time, so the information here may be out of date or inaccurate. Any person using or offering this software in connection with providing software, goods or services to third parties shall advise such third parties of these license terms, disclaimers and exclusions of liability. Block.one, EOSIO, EOSIO Labs, EOS, the heptahedron and associated logos are trademarks of Block.one.
Wallets and related components are complex software that require the highest levels of security. If incorrectly built or used, they may compromise users’ private keys and digital assets. Wallet applications and related components should undergo thorough security evaluations before being used. Only experienced developers should work with this software.