Adding notion of a recovery owner for network recovery

doc/host_config_schema/cchost_config.json

@@ -325,6 +325,11 @@
                         "data_json_file": {
                           "type": ["string", "null"],
                           "description": "Path to member data file (JSON)"
+                        },
+                        "recovery_role": {
+                          "type": "string",
+                          "enum": ["NonParticipant", "Participant", "Owner"],
+                          "description": "Whether the member acts as a recovery participant and gets assigned a single share or as an owner and gets assigned the full recovery key"
                         }
                       },
                       "required": ["certificate_file"],

doc/schemas/gov_openapi.json

@@ -344,6 +344,9 @@
           "member_data": {
             "$ref": "#/components/schemas/json"
           },
+          "recovery_role": {
+            "$ref": "#/components/schemas/MemberRecoveryRole"
+          },
           "status": {
             "$ref": "#/components/schemas/MemberStatus"
           }
@@ -412,6 +415,14 @@
         },
         "type": "object"
       },
+      "MemberRecoveryRole": {
+        "enum": [
+          "NonParticipant",
+          "Participant",
+          "Owner"
+        ],
+        "type": "string"
+      },
       "MemberStatus": {
         "enum": [
           "Accepted",
@@ -1331,7 +1342,7 @@
   "info": {
     "description": "This API is used to submit and query proposals which affect CCF's public governance tables.",
     "title": "CCF Governance API",
-    "version": "4.5.0"
+    "version": "4.6.0"
   },
   "openapi": "3.0.0",
   "paths": {

include/ccf/service/tables/members.h

@@ -21,6 +21,22 @@ namespace ccf
   DECLARE_JSON_ENUM(
     MemberStatus,
     {{MemberStatus::ACCEPTED, "Accepted"}, {MemberStatus::ACTIVE, "Active"}});
+
+  enum class MemberRecoveryRole
+  {
+    NonParticipant = 0,
+    Participant,
+
+    /** If set then the member is to receive the full wrapper key
+       allowing it to single-handedly recover the network without
+       requiring any other recovery member to submit their shares. */
+    Owner
+  };
+  DECLARE_JSON_ENUM(
+    MemberRecoveryRole,
+    {{MemberRecoveryRole::NonParticipant, "NonParticipant"},
+     {MemberRecoveryRole::Participant, "Participant"},
+     {MemberRecoveryRole::Owner, "Owner"}});
 }
 
 namespace ccf
@@ -33,26 +49,31 @@ namespace ccf
     std::optional<ccf::crypto::Pem> encryption_pub_key = std::nullopt;
     nlohmann::json member_data = nullptr;
 
+    std::optional<MemberRecoveryRole> recovery_role = std::nullopt;
+
     NewMember() {}
 
     NewMember(
       const ccf::crypto::Pem& cert_,
       const std::optional<ccf::crypto::Pem>& encryption_pub_key_ = std::nullopt,
-      const nlohmann::json& member_data_ = nullptr) :
+      const nlohmann::json& member_data_ = nullptr,
+      const std::optional<MemberRecoveryRole>& recovery_role_ = std::nullopt) :
       cert(cert_),
       encryption_pub_key(encryption_pub_key_),
-      member_data(member_data_)
+      member_data(member_data_),
+      recovery_role(recovery_role_)
     {}
 
     bool operator==(const NewMember& rhs) const
     {
       return cert == rhs.cert && encryption_pub_key == rhs.encryption_pub_key &&
-        member_data == rhs.member_data;
+        member_data == rhs.member_data && recovery_role == rhs.recovery_role;
     }
   };
   DECLARE_JSON_TYPE_WITH_OPTIONAL_FIELDS(NewMember)
   DECLARE_JSON_REQUIRED_FIELDS(NewMember, cert)
-  DECLARE_JSON_OPTIONAL_FIELDS(NewMember, encryption_pub_key, member_data)
+  DECLARE_JSON_OPTIONAL_FIELDS(
+    NewMember, encryption_pub_key, member_data, recovery_role)
 
   struct MemberDetails
   {
@@ -62,14 +83,17 @@ namespace ccf
         members for example. */
     nlohmann::json member_data = nullptr;
 
+    std::optional<MemberRecoveryRole> recovery_role = std::nullopt;
+
     bool operator==(const MemberDetails& rhs) const
     {
-      return status == rhs.status && member_data == rhs.member_data;
+      return status == rhs.status && member_data == rhs.member_data &&
+        recovery_role == rhs.recovery_role;
     }
   };
   DECLARE_JSON_TYPE_WITH_OPTIONAL_FIELDS(MemberDetails)
   DECLARE_JSON_REQUIRED_FIELDS(MemberDetails, status)
-  DECLARE_JSON_OPTIONAL_FIELDS(MemberDetails, member_data)
+  DECLARE_JSON_OPTIONAL_FIELDS(MemberDetails, member_data, recovery_role)
 
   using MemberInfo = ServiceMap<MemberId, MemberDetails>;
 

samples/constitutions/default/actions.js

@@ -372,6 +372,18 @@ const actions = new Map([
       function (args) {
         checkX509CertBundle(args.cert, "cert");
         checkType(args.member_data, "object?", "member_data");
+        checkType(args.recovery_role, "string?", "recovery_role");
+
+        if (
+          args.encryption_pub_key == null &&
+          args.encryption_pub_key == undefined &&
+          args.recovery_role !== null &&
+          args.recovery_role !== undefined
+        ) {
+          throw new Error(
+            "Cannot specify a recovery_role value when encryption_pub_key is not specified",
+          );
+        }
         // Also check that public encryption key is well formed, if it exists
 
         // Check if member exists
@@ -401,6 +413,7 @@ const actions = new Map([
 
         let member_info = {};
         member_info.member_data = args.member_data;
+        member_info.recovery_role = args.recovery_role;
         member_info.status = "Accepted";
         ccf.kv["public:ccf.gov.members.info"].set(
           rawMemberId,

src/host/configuration.h

@@ -48,14 +48,18 @@ namespace host
     std::string certificate_file;
     std::optional<std::string> encryption_public_key_file = std::nullopt;
     std::optional<std::string> data_json_file = std::nullopt;
+    std::optional<ccf::MemberRecoveryRole> recovery_role = std::nullopt;
 
     bool operator==(const ParsedMemberInfo& other) const = default;
   };
 
   DECLARE_JSON_TYPE_WITH_OPTIONAL_FIELDS(ParsedMemberInfo);
   DECLARE_JSON_REQUIRED_FIELDS(ParsedMemberInfo, certificate_file);
   DECLARE_JSON_OPTIONAL_FIELDS(
-    ParsedMemberInfo, encryption_public_key_file, data_json_file);
+    ParsedMemberInfo,
+    encryption_public_key_file,
+    data_json_file,
+    recovery_role);
 
   struct CCHostConfig : public ccf::CCFConfig
   {

src/host/main.cpp

@@ -216,15 +216,21 @@ int main(int argc, char** argv)
           "On start, ledger directory should not exist ({})",
           config.ledger.directory));
       }
-      // Count members with public encryption key as only these members will be
-      // handed a recovery share.
-      // Note that it is acceptable to start a network without any member having
-      // a recovery share. The service will check that at least one recovery
-      // member is added before the service can be opened.
+
+      // Count members with public encryption key who are not recovery
+      // owners as only these members will be handed a recovery share
+      // that accrues towards the recovery threshold.
+      // Note that it is acceptable to start a network without any member
+      // having a recovery share. The service will check that at least one
+      // recovery member (who is not a recovery owner) is added before the
+      // service can be opened.
       size_t members_with_pubk_count = 0;
       for (auto const& m : config.command.start.members)
       {
-        if (m.encryption_public_key_file.has_value())
+        if (
+          m.encryption_public_key_file.has_value() &&
+          m.recovery_role.value_or(ccf::MemberRecoveryRole::Participant) !=
+            ccf::MemberRecoveryRole::Owner)
         {
           members_with_pubk_count++;
         }
@@ -602,12 +608,17 @@ int main(int argc, char** argv)
       for (auto const& m : config.command.start.members)
       {
         std::optional<ccf::crypto::Pem> public_encryption_key = std::nullopt;
+        std::optional<ccf::MemberRecoveryRole> recovery_role = std::nullopt;
         if (
           m.encryption_public_key_file.has_value() &&
           !m.encryption_public_key_file.value().empty())
         {
           public_encryption_key = ccf::crypto::Pem(
             files::slurp(m.encryption_public_key_file.value()));
+          if (m.recovery_role.has_value())
+          {
+            recovery_role = m.recovery_role.value();
+          }
         }
 
         nlohmann::json md = nullptr;
@@ -619,7 +630,8 @@ int main(int argc, char** argv)
         startup_config.start.members.emplace_back(
           ccf::crypto::Pem(files::slurp(m.certificate_file)),
           public_encryption_key,
-          md);
+          md,
+          recovery_role);
       }
       startup_config.start.constitution = "";
       for (const auto& constitution_path :

src/node/gov/handlers/acks.h

@@ -266,11 +266,12 @@ namespace ccf::gov::endpoints
               return;
             }
 
-            // If this is a newly-active recovery member in an open service,
-            // allocate them a recovery share immediately
+            // If this is a newly-active recovery participant/owner in an open
+            // service, allocate them a recovery share immediately
             if (
               newly_active &&
-              InternalTablesAccess::is_recovery_member(ctx.tx, member_id))
+              InternalTablesAccess::is_recovery_participant_or_owner(
+                ctx.tx, member_id))
             {
               auto service_status =
                 InternalTablesAccess::get_service_status(ctx.tx);

src/node/gov/handlers/recovery.h

@@ -130,11 +130,14 @@ namespace ccf::gov::endpoints
             params["share"].template get<std::string>());
 
           size_t submitted_shares_count = 0;
+          bool full_key_submitted = false;
           try
           {
             submitted_shares_count = share_manager.submit_recovery_share(
               ctx.tx, member_id, raw_recovery_share);
 
+            full_key_submitted = ShareManager::is_full_key(raw_recovery_share);
+
             OPENSSL_cleanse(
               raw_recovery_share.data(), raw_recovery_share.size());
           }
@@ -164,8 +167,13 @@ namespace ccf::gov::endpoints
             submitted_shares_count,
             threshold);
 
-          if (submitted_shares_count >= threshold)
+          if (submitted_shares_count >= threshold || full_key_submitted)
           {
+            if (full_key_submitted)
+            {
+              message += "\nFull recovery key successfully submitted";
+            }
+
             message += "\nEnd of recovery procedure initiated";
             GOV_INFO_FMT("{} - initiating recovery", message);
 
@@ -196,6 +204,7 @@ namespace ccf::gov::endpoints
           response_body["message"] = message;
           response_body["submittedCount"] = submitted_shares_count;
           response_body["recoveryThreshold"] = threshold;
+          response_body["fullKeySubmitted"] = full_key_submitted;
 
           ctx.rpc_ctx->set_response_json(response_body, HTTP_STATUS_OK);
           return;

src/node/gov/handlers/service_state.h

@@ -35,6 +35,19 @@ namespace ccf::gov::endpoints
       member["publicEncryptionKey"] = enc_key.value().str();
     }
 
+    ccf::MemberRecoveryRole recovery_role =
+      ccf::MemberRecoveryRole::NonParticipant;
+    if (member_details.recovery_role.has_value())
+    {
+      recovery_role = member_details.recovery_role.value();
+    }
+    else if (enc_key.has_value())
+    {
+      recovery_role = ccf::MemberRecoveryRole::Participant;
+    }
+
+    member["recoveryRole"] = recovery_role;
+
     return member;
   }
 

src/node/rpc/member_frontend.h

@@ -600,7 +600,7 @@ namespace ccf
       openapi_info.description =
         "This API is used to submit and query proposals which affect CCF's "
         "public governance tables.";
-      openapi_info.document_version = "4.5.0";
+      openapi_info.document_version = "4.6.0";
     }
 
     static std::optional<MemberId> get_caller_member_id(
@@ -760,10 +760,12 @@ namespace ccf
         auto member_info = members->get(member_id.value());
         if (
           service_status.value() == ServiceStatus::OPEN &&
-          InternalTablesAccess::is_recovery_member(ctx.tx, member_id.value()))
+          InternalTablesAccess::is_recovery_participant_or_owner(
+            ctx.tx, member_id.value()))
         {
           // When the service is OPEN and the new active member is a recovery
-          // member, all recovery members are allocated new recovery shares
+          // member/owner, all recovery members are allocated new recovery
+          // shares
           try
           {
             share_manager.shuffle_recovery_shares(ctx.tx);