EOSIO Labs™ Release: The Assert Manifest Security Model

Last month, we announced EOSIO Labs™, an initiative through which we have begun innovating in the open with regards to the future of blockchain technologies built on EOSIO. Our first release under this initiative explored the future of private key management and its implications on security and key management — the Universal Authenticator Library (UAL).

This post continues the EOSIO Labs series, expanding on the ideas of EOSIO Manifests, Assert Contracts, and the Security Model behind them to increase user confidence when signing transactions on blockchain applications.

A Layered Security Model

Public, permissionless blockchains by definition enable any application to access any contract on the blockchain on behalf of a valid user of the blockchain. This open architecture enables numerous providers to build applications that meet users’ needs. However, inherent in this openness is a set of issues:

• Applications can misrepresent who they are to the user during signing (e.g., falsely claim to be the official app for example.com)
• Applications can misrepresent what the user is signing (e.g., request signatures for actions the user did not authorize)

Here we present a layered security model that abstracts the who and what concerns as an application concern that is separate from the way actual transaction signatures are achieved in trusted authenticators (transaction signer).

First we introduce the concept of Application Manifests that help validate the source of the application, answering the “who do you legitimately represent?” question. Second, we introduce the Assert Contract installed on the destination chain that provides assurance that

the transactions being posted by the application are legitimate by validating transaction contents against the on-chain contents of the Application Manifest. For simplification, we present Application Manifests and the Assert Contract as having the two clearly defined purposes outlined above. In reality, they share responsibility with a series of related tools like Ricardian renderers, authorization transport protocols, and others, to help deliver a secure and trusted experience to blockchain users.

The Security Model

The Application Manifest and the Assert Contract work together with conforming authenticators that have the ability to display the Ricardian contracts to solve the who and what problems outlined above. It is important to note that under this model authenticators do not communicate directly with the blockchain on behalf of the application. Authenticators securely sign transactions on behalf of the user and return the transaction to the application, which then broadcasts it to the respective chain. For reference, Figure 1 is a summary of the flow we detail below.

Fig 1: Assert, Manifest Spec, and Ricardians supported Security Model Schematic

Application Manifest

The Application Manifest publicly declares metadata about the decentralized application and the list of actions the application is permitted to broadcast to a particular smart contract. This declaration is made both on-chain, and at a well-known location on the application’s web domain. Taken together, these two declarations working in concert with the Assert Contract will enable the trusted authenticator to provide assurances that:

• The application requesting a transaction signature is an authorized application for that domain. When an application requests a transaction signature, the authenticator can enforce the same-origin policy and verify that the application provided manifest and the copy of manifest that lives at the web domain of the application are hash verifiable. This allows users to trust that they are dealing with a legitimate application for that domain as only legitimate users in control of their domain can host the manifest at that location. In addition, this also allows for application resources like icons to be hash verified as necessary.
• The action being requested by the application is legitimate by comparing it against the list of permitted actions in the manifest, preventing an application from maliciously requesting a transfer of tokens if that action is not listed in the whitelist for a blockchain game or ride sharing application, for example.

Under this model, we also provide tools and renderers to enable trusted authenticators, which can display rich Ricardian contract content to the end users and enable them to verify the exact contents of the transaction they are authorizing. The Manifest Specification provides additional details of the above flow. The Ricardian Spec and Ricardian Template Toolkit provide tools for authenticators to render Ricardian contracts. In addition to reviewing the repositories on GitHub, you can read more about Ricardians in our recent release post on Medium.

Assert Contract

The Assert Contract installed on the destination chain works in concert with the Application Manifest to ensure transactions being posted by the application are legitimate by validating transaction contents against the on-chain contents of the Application Manifest. Trusted authenticators under this model will add an assert::require action to all transactions forcing validation of key details of the Application Manifest on chain. This action is intended to ensure that if any of the details provided by the application don’t match the on-chain details, then the entire transaction fails, protecting the end user.

In particular, the Assert Contract:

1. Allows blockchain networks to register the official chain name and chain icon.
2. Allows decentralized application developers to register one or more manifests describing their application and to remove previously registered manifests.
3. Allows users (via a trusted authenticator) to include an assert::require action in a transaction that will ensure that the entire transaction is rejected if the required pre-conditions are not valid.

Trusted authenticators can now run transaction pre-flight security assertions with the Assert Contract comparing the contents of a transaction request with the list of permitted actions the applications have declared. These assertions include comparing the hash of the Application Manifest, the hash of the app-provided chain info, the hashes of ABIs provided by the app (including the Ricardians presented to the user) against the hash of the matching ABIs on chain to validate that the contract presented to the user for the given action was not tampered with.

Keen observers of this model will note how the security model is geared to maintaining the logical separation of a trusted authenticator from decentralized applications. Authenticators that conform to this model simply add a well-known assert action to all transactions for a given chain to secure end users.

We invite the community to explore if, in the future, application contract developers can also choose to examine incoming transactions to verify that it contains the same well-known assert action before processing the transaction further. This check could provide another on-chain transaction verification mechanism. The Assert Contract provides additional technical details.

The Benefits

This layered application architecture enables trusted authenticators to be excellent custodians of users’ private keys and remain clearly delineated from application-specific actions while still enforcing a security model that provides additional assurances to the end user. This way, blockchain users do not have to review all the source code associated with every decentralized application before using them since the components of the security model in themselves provide significant assurances for the end-user to confidently interact with the blockchain.

Some of the benefits of this approach are:

• Transactions that do not conform to the Application Manifest are rejected outright by the trusted authenticator and never get broadcast to the blockchain
• Transactions that make it to the chain from trusted authenticators are still verified against the Application Manifest contents on chain
• Application search engines can listen to manifest registrations and build a comprehensive listing of known decentralized applications for end users to choose from
• The model also provides a way for application developers to defend themselves against incorrect accusations made by end-users when malicious third parties commit fraud by impersonating their application

However, this model in itself does not solve all the issues associated with imposters. If the user does not pay attention to the displayed Ricardians in a secure authenticator prior to signing the transactions proposed by applications from bloçkçhainapplication.com instead of those from blockchainapplication.com — this model fails to protect users from such imposters. We invite ideas from the community on how the framework can be extended to handle such attack vectors. We consider the model laid out here as a starting point for initiating the discussion with the community and we look forward to hearing from you.

Stay Connected

If you are interested in providing feedback and working more closely with our team to improve the EOSIO Labs repositories for developers, you can post issues and pull requests on GitHub or send our developer relations team an email at developers@block.one.

You can also stay informed of future updates by subscribing to our mailing list on the EOSIO Developer Portal. We are excited to be continually improving the usability of the software for EOSIO developers as we continue laying a foundation for the mass adoption of blockchain technology.

The Future is Open for EOSIO Labs

Through EOSIO Labs, Block.one will continue releasing our thoughts and research on projects like this for EOSIO. This is just the first of many areas of research we hope to tackle as part of the community. We welcome and encourage your feedback on areas of interest to explore and look forward to continually growing one of the most vibrant and innovative technology communities in the world.

Disclaimer: 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 releases described here, the related GitHub release, the EOSIO software or any related documentation, whether expressed or implied, including but not limited to the warranties or 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, resource or service 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. Other trademarks referenced herein are the property of their respective owners. Please note that the statements herein are an expression of Block.one’s vision, not a guarantee of anything, and all aspects of it are subject to change in all respects at Block.one’s sole discretion. We call these “forward looking statements”, which includes statements in this document, other than statements of historical facts, such as statements regarding EOSIO’s development, expected performance, and future features, or our business strategy, plans, prospects, developments and objectives. These statements are only predictions and reflect Block.one’s current beliefs and expectations with respect to future events; they are based on assumptions and are subject to risk, uncertainties and change at any time. We operate in a rapidly changing environment. New risks emerge from time to time. Given these risks and uncertainties, you are cautioned not to rely on these forward-looking statements. Actual results, performance or events may differ materially from what is predicted in the forward-looking statements. Some of the factors that could cause actual results, performance or events to differ materially from the forward-looking statements include, without limitation: market volatility; continued availability of capital, financing and personnel; product acceptance; the commercial success of any new products or technologies; competition; government regulation and laws; and general economic, market or business conditions. All statements are valid only as of the date of first posting and Block.one is under no obligation to, and expressly disclaims any obligation to, update or alter any statements, whether as a result of new information, subsequent events or otherwise. Nothing herein constitutes technological, financial, investment, legal or other advice, either in general or with regard to any particular situation or implementation. Please consult with experts in appropriate areas before implementing or utilizing anything contained in this document.