Test and document set_user_data (#1450)

Author: eddyashton

doc/members/open_network.rst

@@ -26,7 +26,7 @@ Then, the certificates of trusted users should be registered in CCF via the memb
         "state": "OPEN"
     }
 
-Other members are then allowed to vote for the proposal, using the proposal id returned to the proposer member (here ``5``). They may submit an unconditional approval, or their vote may query the current state and the proposed calls. These votes `must` be signed.
+Other members are then allowed to vote for the proposal, using the proposal id returned to the proposer member (here ``5``). They may submit an unconditional approval, or their vote may query the current state and the proposed actions. These votes `must` be signed.
 
 .. code-block:: bash
 
@@ -69,7 +69,53 @@ The user can then make user RPCs, for example ``user_id`` to retrieve the unique
         "caller_id": 4
     }
 
-For each user CCF also stores arbitrary user-data in a JSON object, which can only be written to by members, subject to the standard proposal-vote governance mechanism. This lets members define initial metadata for certain users; for example to grant specific privileges, associate a human-readable name, or categorise the users. This user-data can then be read (but not written) by user-facing apps.
+User Data
+---------
+
+For each user, CCF also stores arbitrary user-data in a JSON object. This can only be written to by members, subject to the standard proposal-vote governance mechanism, via the ``set_user_data`` action. This lets members define initial metadata for certain users; for example to grant specific privileges, associate a human-readable name, or categorise the users. This user-data can then be read (but not written) by user-facing endpoints.
+
+For example, the ``/log/private/admin_only`` endpoint in the C++ logging sample app uses user-data to restrict who is permitted to call it:
+
+.. literalinclude:: ../../src/apps/logging/logging.cpp
+    :language: cpp
+    :start-after: SNIPPET_START: user_data_check
+    :end-before: SNIPPET_END: user_data_check
+    :dedent: 12
+
+Members configure this permission with ``set_user_data`` proposals:
+
+.. code-block:: bash
+
+    $ cat set_user_data_proposal.json 
+    {
+        "script": {
+            "text": "tables, args = ...; return Calls:call(\"set_user_data\", args)"
+        },
+        "parameter": {
+            "user_id": 0,
+            "user_data": {
+                "isAdmin": true
+            }
+        }
+    }
+
+Once this proposal is accepted, user 0 is able to use this endpoint:
+
+.. code-block:: bash
+
+    $ curl https://<ccf-node-address>/app/log/private/admin_only --key user0_privk.pem --cert user0_cert.pem --cacert networkcert.pem -X POST --data-binary '{"id": 42, "msg": "hello world"}' -H "Content-type: application/json" -i
+    HTTP/1.1 200 OK
+
+    true
+
+All other users have empty or non-matching user-data, so will receive a HTTP error if they attempt to access it:
+
+.. code-block:: bash
+
+    $ curl https://<ccf-node-address>/app/log/private/admin_only --key user1_privk.pem --cert user1_cert.pem --cacert networkcert.pem -X POST --data-binary '{"id": 42, "msg": "hello world"}' -H "Content-type: application/json" -i
+    HTTP/1.1 403 Forbidden
+
+    Only admins may access this endpoint
 
 Registering the Lua Application
 -------------------------------

doc/members/proposals.rst

@@ -3,7 +3,7 @@ Proposing and Voting for a Proposal
 
 This page explains how members can submit and vote for proposals.
 
-Proposals and vote ballots are submitted as Lua scripts. These scripts are executed transactionally, able to read from the current KV state but not write directly to it. Proposals return a list of proposed actions which can make writes, but are only applied when the proposal is accepted. Each vote script is given this list of proposed calls, and also able to read from the KV, and returns a boolean indicating whether it supports or rejects the proposed actions.
+Proposals and vote ballots are submitted as Lua scripts. These scripts are executed transactionally, able to read from the current KV state but not write directly to it. Proposals return a list of proposed actions which can make writes, but are only applied when the proposal is accepted. Each vote script is given this list of proposed actions, and also able to read from the KV, and returns a boolean indicating whether it supports or rejects the proposed actions.
 
 Any member can submit a new proposal. All members can then vote on this proposal using its unique proposal id. Each member may alter their vote (by submitting a new vote) any number of times while the proposal is open. The member who originally submitted the proposal (the `proposer`) votes for the proposal by default, but has the option to include a negative or conditional vote like any other member. Additionally, the proposer has the ability to `withdraw` a proposal while it is open.
 

doc/schemas/log/private/admin_only_POST_params.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "properties": {
+    "id": {
+      "maximum": 18446744073709551615,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "msg": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "msg"
+  ],
+  "title": "log/private/admin_only/params",
+  "type": "object"
+}

doc/schemas/log/private/admin_only_POST_result.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "log/private/admin_only/result",
+  "type": "boolean"
+}

src/apps/logging/logging.cpp

@@ -395,6 +395,49 @@ namespace loggingapp
           get_historical, context.get_historical_state(), is_tx_committed))
         .install();
 
+      auto record_admin_only =
+        [this, &nwt](ccf::EndpointContext& ctx, nlohmann::json&& params) {
+          {
+            // SNIPPET_START: user_data_check
+            // Check caller's user-data for required permissions
+            auto users_view = ctx.tx.get_view(nwt.users);
+            const auto user_opt = users_view->get(ctx.caller_id);
+            const nlohmann::json user_data = user_opt.has_value() ?
+              user_opt->user_data :
+              nlohmann::json(nullptr);
+            const auto is_admin_it = user_data.find("isAdmin");
+
+            // Exit if this user has no user data, or the user data is not an
+            // object with isAdmin field, or the value of this field is not true
+            if (
+              !user_data.is_object() || is_admin_it == user_data.end() ||
+              !is_admin_it.value().get<bool>())
+            {
+              return ccf::make_error(
+                HTTP_STATUS_FORBIDDEN, "Only admins may access this endpoint");
+            }
+            // SNIPPET_END: user_data_check
+          }
+
+          const auto in = params.get<LoggingRecord::In>();
+
+          if (in.msg.empty())
+          {
+            return ccf::make_error(
+              HTTP_STATUS_BAD_REQUEST, "Cannot record an empty log message");
+          }
+
+          auto view = ctx.tx.get_view(records);
+          view->put(in.id, in.msg);
+          return ccf::make_success(true);
+        };
+      make_endpoint(
+        "log/private/admin_only",
+        HTTP_POST,
+        ccf::json_adapter(record_admin_only))
+        .set_auto_schema<LoggingRecord::In, bool>()
+        .install();
+
       auto& notifier = context.get_notifier();
       nwt.signatures.set_global_hook(
         [&notifier](kv::Version version, const ccf::Signatures::Write& w) {

tests/e2e_logging.py

@@ -388,8 +388,50 @@ def test_update_lua(network, args):
     return network
 
 
+@reqs.description("Test user-data used for access permissions")
+@reqs.supports_methods("log/private/admin_only")
+def test_user_data_ACL(network, args):
+    if args.package == "liblogging":
+        primary, _ = network.find_primary()
+
+        proposing_member = network.consortium.get_any_active_member()
+        user_id = 0
+
+        # Give isAdmin permissions to a single user
+        proposal_body, careful_vote = ccf.proposal_generator.set_user_data(
+            user_id, {"isAdmin": True},
+        )
+        proposal = proposing_member.propose(primary, proposal_body)
+        proposal.vote_for = careful_vote
+        network.consortium.vote_using_majority(primary, proposal)
+
+        # Confirm that user can now use this endpoint
+        with primary.client(f"user{user_id}") as c:
+            r = c.post("/app/log/private/admin_only", {"id": 42, "msg": "hello world"})
+            assert r.status_code == http.HTTPStatus.OK.value, r.status_code
+
+        # Remove permission
+        proposal_body, careful_vote = ccf.proposal_generator.set_user_data(
+            user_id, {"isAdmin": False},
+        )
+        proposal = proposing_member.propose(primary, proposal_body)
+        proposal.vote_for = careful_vote
+        network.consortium.vote_using_majority(primary, proposal)
+
+        # Confirm that user is now forbidden on this endpoint
+        with primary.client(f"user{user_id}") as c:
+            r = c.post("/app/log/private/admin_only", {"id": 42, "msg": "hello world"})
+            assert r.status_code == http.HTTPStatus.FORBIDDEN.value, r.status_code
+
+    else:
+        LOG.warning(
+            f"Skipping {inspect.currentframe().f_code.co_name} as application is not C++"
+        )
+
+    return network
+
+
 @reqs.description("Check for commit of every prior transaction")
-@reqs.supports_methods("/node/commit")
 def test_view_history(network, args):
     if args.consensus == "pbft":
         # This appears to work in PBFT, but it is unacceptably slow:
@@ -586,6 +628,7 @@ def run(args):
             network = test_remove(network, args)
             network = test_forwarding_frontends(network, args)
             network = test_update_lua(network, args)
+            network = test_user_data_ACL(network, args)
             network = test_cert_prefix(network, args)
             network = test_anonymous_caller(network, args)
             network = test_raw_text(network, args)

tests/suite/test_suite.py

@@ -62,6 +62,7 @@
     e2e_logging.test_raw_text,
     e2e_logging.test_forwarding_frontends,
     e2e_logging.test_update_lua,
+    e2e_logging.test_user_data_ACL,
     e2e_logging.test_view_history,
     e2e_logging.test_tx_statuses,
     # memberclient:

tests/ws_scaffold.py

@@ -12,7 +12,7 @@
 
 
 @reqs.description("Running transactions against logging app")
-@reqs.supports_methods("/app/log/private")
+@reqs.supports_methods("log/private")
 @reqs.at_least_n_nodes(2)
 def test(network, args, notifications_queue=None):
     primary, other = network.find_primary_and_any_backup()