In this next instalment of our Multisig and Permission Guide we are going to help you master
linkauth, another powerful feature that the EOSIO software allows you to utilize to add increased security to your account.
linkauth assigns a specific action from a contract to a permission you have created. This would allow you to assign a key or an account to have access to only a predefined action, limiting their ability to cause damage to your account should they become compromised.
Use Case for
Let’s take a look at a use case so that we can fully understand both the when and the why
linkauth could be used. A perfect example is Block Producers claiming rewards. Since Block Producers will need to do this daily, all of them have automated this task to be more efficient. In order to automate this, they will need to entrust access of their key to a script. Rather than using the same keys that would give access to their whole account, they can create a unique key that is capable of only claiming rewards. Should that key become compromised, the only thing that a hacker could achieve would be to claim rewards on behalf of that Block Producer, into the Block Producer’s own account.
Once you have generated a keypair that you’d like to assign to the claim rewards action, you will first use
updateauth to create the
claimer permission itself using:
eosc system updateauth [ACCOUNT_NAME] claimer active [FILENAME.yaml]
If you haven’t read it already, go through our article on using eosc to update your account’s authority structure. Now you will be able to assign that permission using this command:
eosc system linkauth [BP_ACCOUNT] eosio claimrewards claimer
With this new structure, the added
claimer permission and its associated key would only be able to call the claimrewards action and nothing else.
When doing authorization checks, the EOSIO chain always starts with the contract + action in hand, and looks up which permission is needed to satisfy it. Only one of the permissions can match for a given contract + action pair, and if no links are set, then
active is the default (with the exception of
There are five system actions which cannot be linked by the
linkauth function. These are:
canceldelay. So you will be unable to assign these actions to a specific permission level.
If you wanted to remove the ability for a permission level to perform an action, you could also designate the power to perform that action using
linkauth to a permission level that is within its own permission stream branching off of
owner, creating a sibling permission. Consider the following structure:
You may notice that the
claimer permission has
owner as a parent, and is not nested below
active (as in the previous example). The
active permission of this account will no longer be able to call the
claimrewards action and will be met with this assertion error. A parent permission will be able to perform the action, but once the permission structure branches out to include sibling streams, those actions become segregated.
There is also an implicit permission that exists on every account called
eosio.any. It exists at the child level of every permission stream. You can
linkauth actions to
eosio.any, and this will cause that action to be accessible to every permission level within your account. Be mindful with this as the weakest permission is what guards that action’s authorization, and as such it should only be utilized for low-risk actions.
Removing a Permission With
If you wanted to remove a linked action from a permission that you had created, you can use the opposite function,
eosc system unlinkauth [ACCOUNT_NAME] eosio claimrewards
You can remove a permission altogether with
deleteauth, but not while any linked actions are still attached to it. You will have to first call
unlinkauth for all links of that permission level, and only then call
eosc system deleteauth [ACCOUNT_NAME] claimer
Now you should have a solid understanding on how to use the permissions structure to create a system that will securely protect your account, with unique authorities and action-specific keys. In the next article, we will explore how to simplify the signature collection process using