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.

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::requireaction 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 [email protected].

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.

Important Note: All material is provided subject to this important notice and you must familiarize yourself with its terms. The notice contains important information, limitations, and restrictions relating to our software, publications, trademarks, third-party resources and forward-looking statements. By accessing any of our material, you accept and agree to the terms of the notice.