Refactor local-sealing and self-healing-open into sealing-recovery

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [7.0.0-dev12]
+
+[7.0.0-dev12]: https://github.com/microsoft/CCF/releases/tag/ccf-7.0.0-dev12
+
+### Changed
+
+- Refactored the user facing surface of self-healing-open and local sealing. The whole feature is now `sealing-recovery` with `self-healing-open` now referred to as the `recovery-decision-protocol`. (#7679)
+  - Local sealing is enabled by setting the `sealing-recovery` config field (for both the sealing node, and the unsealing recovery node)
+  - The local sealing identity is under `sealing-recovery.location.name`
+  - The recovery-decision-protocol is configured via `sealing-recovery.recovery_decision_protocol`
+
 ## [7.0.0-dev11]
 
 [7.0.0-dev11]: https://github.com/microsoft/CCF/releases/tag/ccf-7.0.0-dev11

CMakeLists.txt

@@ -369,7 +369,7 @@ endif()
 set(CCF_IMPL_SOURCE
     ${CCF_DIR}/src/enclave/main.cpp ${CCF_DIR}/src/enclave/thread_local.cpp
     ${CCF_DIR}/src/node/quote.cpp ${CCF_DIR}/src/node/uvm_endorsements.cpp
-    ${CCF_DIR}/src/node/self_healing_open_impl.cpp
+    ${CCF_DIR}/src/node/recovery_decision_protocol.cpp
 )
 
 add_ccf_static_library(
@@ -749,7 +749,7 @@ if(BUILD_TESTS)
       ${CMAKE_CURRENT_SOURCE_DIR}/src/node/rpc/test/frontend_test.cpp
       ${CCF_DIR}/src/node/quote.cpp
       ${CCF_DIR}/src/node/uvm_endorsements.cpp
-      ${CCF_DIR}/src/node/self_healing_open_impl.cpp
+      ${CCF_DIR}/src/node/recovery_decision_protocol.cpp
     )
     target_link_libraries(
       frontend_test
@@ -789,7 +789,7 @@ if(BUILD_TESTS)
       ${CMAKE_CURRENT_SOURCE_DIR}/src/node/rpc/test/node_frontend_test.cpp
       ${CCF_DIR}/src/node/quote.cpp
       ${CCF_DIR}/src/node/uvm_endorsements.cpp
-      ${CCF_DIR}/src/node/self_healing_open_impl.cpp
+      ${CCF_DIR}/src/node/recovery_decision_protocol.cpp
     )
     target_link_libraries(
       node_frontend_test

doc/audit/builtin_maps.rst

@@ -581,64 +581,69 @@ While the contents themselves are encrypted, the table is public so as to be acc
     :project: CCF
     :members:
 
+``sealing_recovery_names``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mapping from sealing recovery names to node IDs for nodes that support local sealing. This table is used alongside ``nodes.sealed_recovery_keys`` to fetch the sealed recovery key when a node is recovering.
+
+**Key** Sealing recovery name of the node, represented as a string.
+
+**Value** Node ID: SHA-256 digest of the node public key, represented as a hex-encoded string.
+
 ``last_recovery_type``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Value** The mechanism by which the ledger secret was recovered.
 
 .. doxygenenum:: ccf::RecoveryType
    :project: CCF
 
-``self_healing_open.nodes``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``recovery_decision_protocol.nodes``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Key** Intrinsic node ID: A string which is unique to a particular node role within a cluster.
+**Key** Location name: A string which is unique to the location of a particular node within a network.
 
 **Value** 
 
-.. doxygenstruct:: ccf::self_healing_open::NodeInfo
+.. doxygenstruct:: ccf::recovery_decision_protocol::NodeInfo
    :project: CCF
    :members:
 
-``self_healing_open.gossip``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Key** Intrinsic node ID of the source of the gossip message.
+``recovery_decision_protocol.gossip``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Value**
+**Key** Location name of the source of the gossip message.
 
-.. doxygenstruct:: ccf::self_healing_open::GossipRequest
-   :project: CCF
-   :members:
+**Value** The TxID of the last recovered signed transaction known by the source node.
 
-``self_healing_open.chosen_node``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``recovery_decision_protocol.chosen_node``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Value** The intrinsic node ID of the chosen node. This will either be the node this node voted for, or the node that is has received an `IAmOpen` message from.
+**Value** The location name of the chosen node. This will either be the node this node voted for, or the node that it has received an `IAmOpen` message from.
 
-``self_healing_open.votes``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``recovery_decision_protocol.votes``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Key** Intrinsic node ID of the node which has voted for this node to be opened.
+**Key** Location name of the node which has voted for this node to be opened.
 
-``self_healing_open.sm_state``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``recovery_decision_protocol.sm_state``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Value** State machine state of the self-healing open protocol.
+**Value** State machine state of the recovery decision protocol.
 
-.. doxygenenum:: ccf::self_healing_open::StateMachine
+.. doxygenenum:: ccf::recovery_decision_protocol::StateMachine
    :project: CCF
 
-``self_healing_open.timeout_sm_state``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``recovery_decision_protocol.timeout_sm_state``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Value** Timeout state machine state of the self-healing open protocol. Ticks based on `failover_timeout` and advances `self_healing_open.sm_state` if it falls behind.
+**Value** Timeout state machine state of the recovery decision protocol. Ticks based on `failover_timeout` and advances `recovery_decision_protocol.sm_state` if it falls behind.
 
-See :cpp:enum:`ccf::self_healing_open::StateMachine` above.
+See :cpp:enum:`ccf::recovery_decision_protocol::StateMachine` above.
 
-``self_healing_open.open_kind``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``recovery_decision_protocol.open_kind``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 **Value** The kind of recovery that was performed, either `Quorum`-based which guarantees that there is at most one recovered service using this path, or `Failover`-based which could allow multiple services to recover.
 
-.. doxygenenum:: ccf::self_healing_open::OpenKinds
-   :project: CCF
+.. doxygenenum:: ccf::recovery_decision_protocol::OpenKinds
+   :project: CCF

doc/host_config_schema/cchost_config.json

@@ -356,55 +356,6 @@
                   "previous_service_identity_file": {
                     "type": "string",
                     "description": "Path to the previous service certificate (PEM) file"
-                  },
-                  "previous_local_sealing_identity": {
-                    "type": ["string", "null"],
-                    "description": "The identity of the previous node which sealed the ledger secrets. Required if local sealing is enabled"
-                  },
-                  "self_healing_open": {
-                    "type": "object",
-                    "properties": {
-                      "identity": {
-                        "type": "object",
-                        "properties": {
-                          "intrinsic_id": {
-                            "type": "string",
-                            "description": "Intrinsic identifier of this node, used to identify it in the self-healing-open protocol"
-                          },
-                          "published_address": {
-                            "type": "string",
-                            "description": "Published address (host:port) of this node, used to identify it in the self-healing-open protocol"
-                          }
-                        }
-                      },
-                      "cluster_identities": {
-                        "type": "array",
-                        "items": {
-                          "type": "object",
-                          "properties": {
-                            "intrinsic_id": {
-                              "type": "string",
-                              "description": "Intrinsic identifier of the node, used to identify it in the self-healing-open protocol"
-                            },
-                            "published_address": {
-                              "type": "string",
-                              "description": "Published address (host:port) of the node, used for communication during the self-healing-open protocol"
-                            }
-                          }
-                        },
-                        "description": "List of identities for all nodes in the cluster"
-                      },
-                      "retry_timeout": {
-                        "type": "string",
-                        "default": "100ms",
-                        "description": "Interval (time string) at which the node re-sends self-healing-open messages. This should be significantly less than 'failover_timeout'"
-                      },
-                      "failover_timeout": {
-                        "type": "string",
-                        "default": "2000ms",
-                        "description": "Interval (time string) after which the node forcibly advances to the next phase of the self-healing-open protocol"
-                      }
-                    }
                   }
                 },
                 "required": ["previous_service_identity_file"],
@@ -710,10 +661,59 @@
       "default": "512MB",
       "description": "Historical queries cache soft limit (as size string)"
     },
-    "enable_local_sealing": {
-      "type": "boolean",
-      "default": false,
-      "description": "Enable sealing of ledger secrets using platform derived key capabilities (e.g. AMD SEV-SNP derived keys). This allows the node to unilaterally recover its ledger secrets on restart without needing to reconstruct them from recovery shares."
+    "sealing_recovery": {
+      "type": "object",
+      "description": "Optional. Controls the behaviour of sealing-based recovery. If set, enables sealing of ledger secrets using platform derived key capabilities (e.g. AMD SEV-SNP derived keys). This allows a future recovering node to unilaterally recover its ledger secrets on restart without needing to reconstruct them from recovery shares.",
+      "properties": {
+        "location": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "address": {
+              "type": "string"
+            }
+          },
+          "required": ["name", "address"],
+          "additionalProperties": false
+        },
+        "recovery_decision_protocol": {
+          "type": "object",
+          "properties": {
+            "expected_locations": {
+              "type": "array",
+              "description": "List of locations that the recovery_decision_protocol expects to be part of the previous network.",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "address": {
+                    "type": "string"
+                  }
+                },
+                "required": ["name", "address"],
+                "additionalProperties": false
+              }
+            },
+            "message_retry_timeout": {
+              "type": "string",
+              "default": "100ms"
+            },
+            "failover_timeout": {
+              "type": "string",
+              "default": "2000ms",
+              "description": "Timeout duration before failover forcibly advances the recovery_decision_protocol, allowing recovery to proceed even in the presence of unresponsive nodes. Set to 0 to disable failover."
+            }
+          },
+          "required": ["expected_locations"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["location"],
+      "additionalProperties": false
     }
   },
   "required": ["network", "command"],