├── CMakeLists.txt ├── permissions_test.hpp ├── permissions_test.cpp └── README.md /CMakeLists.txt: -------------------------------------------------------------------------------- 1 | file(GLOB ABI_FILES "*.abi") 2 | configure_file("${ABI_FILES}" "${CMAKE_CURRENT_BINARY_DIR}" COPYONLY) 3 | 4 | add_wast_executable(TARGET permissions_test 5 | INCLUDE_FOLDERS "${STANDARD_INCLUDE_FOLDERS}" 6 | LIBRARIES libc++ libc eosiolib 7 | DESTINATION_FOLDER ${CMAKE_CURRENT_BINARY_DIR} 8 | ) 9 | -------------------------------------------------------------------------------- /permissions_test.hpp: -------------------------------------------------------------------------------- 1 | #pragma once 2 | 3 | #include 4 | 5 | namespace eosio { 6 | 7 | class permissions_test : public contract { 8 | public: 9 | using contract::contract; 10 | 11 | //@abi action 12 | void hasauth(account_name account); 13 | 14 | //@abi action 15 | void reqauth(account_name account); 16 | 17 | //@abi action 18 | void reqauth2(account_name account, permission_name permission); 19 | 20 | //@abi action 21 | void send(account_name sent, permission_name p_sent, account_name req); 22 | 23 | //@abi action 24 | void send2(account_name sent, permission_name p_sent, account_name req, permission_name p_req); 25 | }; 26 | } 27 | -------------------------------------------------------------------------------- /permissions_test.cpp: -------------------------------------------------------------------------------- 1 | #include "permissions_test.hpp" 2 | #include "eosiolib/action.hpp" 3 | 4 | namespace eosio { 5 | 6 | void permissions_test::hasauth(account_name account) { 7 | eosio::print(has_auth(account)); 8 | } 9 | 10 | void permissions_test::reqauth(account_name account) { 11 | require_auth(account); 12 | } 13 | 14 | void permissions_test::reqauth2(account_name account, permission_name permission) { 15 | require_auth2(account, permission); 16 | eosio::print(name{account}); 17 | eosio::print('@'); 18 | eosio::print(name{permission}); 19 | } 20 | 21 | void permissions_test::send(account_name sent, permission_name p_sent, account_name req) { 22 | action(permission_level{sent, p_sent}, 23 | N(test), N(reqauth), 24 | std::make_tuple(req) 25 | ).send(); 26 | } 27 | 28 | void permissions_test::send2(account_name sent, permission_name p_sent, account_name req, permission_name p_req) { 29 | action(permission_level{sent, p_sent}, 30 | N(test), N(reqauth2), 31 | std::make_tuple(req, p_req) 32 | ).send(); 33 | } 34 | } 35 | 36 | EOSIO_ABI(eosio::permissions_test, (hasauth)(reqauth)(reqauth2)(send)(send2)) 37 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # EOSIO Permissions System Test 2 | 3 | An EOSIO smart contract for testing different permissions and authorities. 4 | 5 | I used this smart contract to teach myself how the permissions system actually 6 | works. At the time, there was a lack of documentation on the subject and 7 | most people seemed confused. It was hard to find a definitive guide, so I 8 | wrote this simple contract to test and understand better the inner workings 9 | of the powerful EOSIO permissions system. 10 | 11 | Most of all I wanted to understand the workings of the `eosio.code` permission 12 | when sending inline actions to other contracts. This is a recap of what I 13 | understood, in the context of a Stack Exchange question: 14 | 15 | > More info here: https://eosio.stackexchange.com/a/1718/1834 16 | 17 | ## EOS Permission Model - Overview 18 | 19 | - An account can have various permissions (like owner and active), which are represented by an account@permission pair. 20 | - Permissions (which are like roles) can be linked to specific actions of specific contracts to allow those permissions to execute those actions (`linkauth`). By default, the `owner` and `active` permissions can do anything except `active` can't change the owner permission. 21 | - Permissions are controlled by an "authority", which is the multisig configuration of who can give that permission (in other words, who can act under that role). 22 | - Within this multisig configuration, you can have a combination of public keys and other permissions (account@permission pairs), which makes permissions an intrinsically recursive construct. 23 | 24 | ## Acting as another account 25 | 26 | Contracts in general should use `require_auth(account)` and not `require_auth2(account, permission)` unless there is a very specific reason to do so. Using `require_auth2` to require a specific permission of an account can hinder the configurability of the EOSIO permission system. This is because in general, if actions simply require the auth of an account, then that means they are implicitly requiring one of the following permissions of that account: 27 | 28 | 1. The `owner` permission. 29 | 2. The `active` permission. 30 | 3. Any other custom permission that the user decided to create for their account in order to give granular authorization to specific contract actions. 31 | 32 | Point 3 means that a user can create a permission (as I mentioned, it can be seen as a "role") called for example `ramtrader` and then use `linkauth` to authorize that permission to use the `eosio::buyram` and `eosio::sellram` system contract actions. This can work with any contract, not only the system contract. This way, when defining the `ramtrader` permission, users will need to specify an *authority* for it (a multisig configuration), and this authority could specify that the only object that can act under this permission is `accountb@active`, for example, giving access to the `accountb` account to buy and sell RAM for `account`. 33 | 34 | ## Contract code acting as another account 35 | 36 | Now that we understand how to act as another account, we can figure out how to allow a contract's code to act as another account, be it for transferring funds (`eosio.token::transfer` action) or just calling another contract's actions. 37 | 38 | When contracts call inline actions, they are supposed to send the right permissions for that action. If for instance a contract that lives in the `contract` account would try to buy RAM for `account` using the funds of `account` itself, it would need to provide the same permissions that `account` is required to provide when they buy RAM for themselves manually. If we use the `account@active` permission, then the contract would need to send that permission in the inline action, and not `contract@eosio.code` as many of us could end up thinking (the documentation on this is very scarce and confusing). In order for the code in the `contract` account to be able to provide that permission, first `account` would have to add authorization for the code of `contract` to the authority (multisig config) that rules it's `account@active` permission. 39 | 40 | This can be achieved by adding the `contract@eosio.code` permission to the authority, which is a special permission defined by the EOSIO software to specify that **only the contract code of the `contract` account** will be able to act under the permission (role) ruled by that authority. This means that the `account@active` authority would contain the public key that the owner of that account controls, as well as the `contract@eosio.code` permission. 41 | 42 | This effectively implements what you were looking for: Authorizing a contract's code to act as another account, but not letting the contract's account act as the other account. 43 | 44 | If you wanted to let a contract's account act as yourself but not the contract's code, you would have to do the same thing but instead of setting `contract@eosio.code` you would set `contract@active` or some other more specific (limited) permission. 45 | 46 | ## Setting up the permission authority 47 | 48 | To configure your account to allow `contract@eosio.code` to act on your behalf, you would need to issue a transaction to the `eosio::updateauth` action with the properly formatted authority data. One way to do it using `cleos` is what @confused00 showed in his example: 49 | 50 | cleos set account permission active '{"threshold": 1,"keys": [{"key": "","weight": 1}],"accounts": [{"permission":{"actor":"","permission":"eosio.code"},"weight":1}]}' owner -p 51 | 52 | It might be easier to save a `data.json` file and then put the payload in there and point `cleos` to it: 53 | 54 | > data.json 55 | 56 | { 57 | "threshold": 1, 58 | "keys": [ 59 | { 60 | "key": "", 61 | "weight": 1 62 | } 63 | ], 64 | "accounts": [ 65 | { 66 | "permission": { 67 | "actor": "", 68 | "permission": "eosio.code" 69 | }, 70 | "weight": 1 71 | } 72 | ] 73 | } 74 | 75 | and then: 76 | 77 | cleos set account permission active data.json owner -p 78 | --------------------------------------------------------------------------------