Merge branch 'main' of https://github.com/microsoft/CCF into respond_at_commit

Author: eddyashton

CHANGELOG.md

@@ -11,12 +11,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
+- Backup nodes can now be configured to automatically fetch snapshots from the primary when snapshot evidence is detected. This is controlled by the `snapshots.backup_fetch` configuration section, with `enabled`, `max_attempts`, `retry_interval`, `max_size` and `target_rpc_interface` options. Note that the target RPC interface selected must have the `SnapshotRead` operator feature enabled.
 - Added `ccf::IdentityHistoryNotFetched` exception type to distinguish identity-history-fetching errors from other logic errors in the network identity subsystem (#7708).
 - Added `ccf::describe_cose_receipt_v1(receipt)` to obtain COSE receipts with Merkle proof in unprotected header for non-signature TXs, and empty unprotected header for signature TXs (#7700).
 - `NetworkIdentitySubsystemInterface` now exposes `get_trusted_keys()`, returning all trusted network identity keys as a `TrustedKeys` map (#7690).
+- Added support for self-transparent code update policies (#7681).
 
 ### Changed
 
+- On recovery, the UVM descriptor SVN is now set to the minimum of the previously stored value in the KV and the value found in the new node's startup endorsements. On start, the behaviour is unchanged (#7716).
 - 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`

CMakeLists.txt

@@ -44,6 +44,12 @@ include(GNUInstallDirs)
 # Use fixed name instead of absolute path for reproducible builds
 add_compile_options("-ffile-prefix-map=${CCF_DIR}=CCF")
 
+# In Debug builds, export symbols to the dynamic symbol table so that
+# backtrace_symbols can resolve function names in stacktraces, and preserve
+# frame pointers so that backtrace() can walk the full call stack.
+add_link_options($<$<CONFIG:Debug>:-rdynamic>)
+add_compile_options($<$<CONFIG:Debug>:-fno-omit-frame-pointer>)
+
 set(CMAKE_MODULE_PATH "${CCF_DIR}/cmake;${CMAKE_MODULE_PATH}")
 
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
@@ -275,7 +281,15 @@ add_ccf_static_library(
        ${CCF_DIR}/src/tasks/ordered_tasks.cpp
        ${CCF_DIR}/src/tasks/fan_in_tasks.cpp
        ${CCF_DIR}/src/tasks/thread_manager.cpp
+       ${CCF_DIR}/src/tasks/worker.cpp
 )
+target_link_libraries(ccf_tasks PRIVATE ${CMAKE_DL_LIBS})
+if(USE_LIBCXX)
+  # worker.cpp uses backtrace() which, under libc++, resolves through libunwind.
+  # On systems where libunwind is built with LZMA support (e.g. Azure Linux),
+  # this creates a transitive dependency on liblzma.
+  target_link_libraries(ccf_tasks PRIVATE lzma)
+endif()
 
 # Common test args for Python scripts starting up CCF networks
 set(WORKER_THREADS
@@ -657,6 +671,13 @@ if(BUILD_TESTS)
       js_test PRIVATE ccf_js ccf_kv ccf_endpoints ccfcrypto http_parser
     )
 
+    add_unit_test(
+      js_policy_test ${CMAKE_CURRENT_SOURCE_DIR}/src/node/test/js_policy.cpp
+    )
+    target_link_libraries(
+      js_policy_test PRIVATE ccf_js ccf_kv ccf_endpoints ccfcrypto
+    )
+
     add_unit_test(
       endorsements_test
       ${CMAKE_CURRENT_SOURCE_DIR}/src/node/test/endorsements.cpp
@@ -804,6 +825,13 @@ if(BUILD_TESTS)
               ccf_tasks
     )
 
+    add_unit_test(
+      internal_tables_access_test
+      ${CMAKE_CURRENT_SOURCE_DIR}/src/node/rpc/test/internal_tables_access_test.cpp
+      ${CCF_DIR}/src/node/uvm_endorsements.cpp
+    )
+    target_link_libraries(internal_tables_access_test PRIVATE ccfcrypto ccf_kv)
+
     add_unit_test(
       merkle_test ${CMAKE_CURRENT_SOURCE_DIR}/src/node/test/merkle_test.cpp
     )

doc/host_config_schema/cchost_config.json

@@ -325,6 +325,11 @@
                     "type": "string",
                     "default": "10GB",
                     "description": "Maximum size of snapshot this node is willing to fetch"
+                  },
+                  "host_data_transparent_statement_path": {
+                    "type": ["string", "null"],
+                    "default": null,
+                    "description": "Path to a SCITT Transparent Statement over the attested host_data of the node"
                   }
                 },
                 "required": ["target_rpc_address"],
@@ -493,6 +498,39 @@
         "read_only_directory": {
           "type": ["string", "null"],
           "description": "Path to read-only snapshots directory"
+        },
+        "backup_fetch": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "If true, backup nodes will automatically fetch snapshots from the primary when snapshot evidence is detected"
+            },
+            "max_attempts": {
+              "type": "integer",
+              "default": 3,
+              "description": "Maximum number of fetch attempts before giving up",
+              "minimum": 1
+            },
+            "retry_interval": {
+              "type": "string",
+              "default": "1000ms",
+              "description": "Delay between retry attempts"
+            },
+            "target_rpc_interface": {
+              "type": "string",
+              "default": "primary_rpc_interface",
+              "description": "Name of the RPC interface on the primary node to use for downloading snapshots. Must have the SnapshotRead feature enabled."
+            },
+            "max_size": {
+              "type": "string",
+              "default": "200MB",
+              "description": "Maximum size of snapshot this node is willing to fetch"
+            }
+          },
+          "description": "Configuration for automatic snapshot fetching by backup nodes",
+          "additionalProperties": false
         }
       },
       "description": "This section includes configuration for the snapshot directories and files",

doc/operations/code_upgrade.rst

@@ -184,3 +184,134 @@ Notes
 
 - The :http:GET:`/node/version` endpoint can be used by operators to check which version of CCF a specific node is running.
 - A code upgrade procedure provides very little service downtime compared to a disaster recovery. The service is only unavailable to process write transactions while the primary-ship changes (typically a few seconds) but can still process read-only transactions throughout the whole procedure. Note that this is true during any primary-ship change, and not just during the code upgrade procedure.
+
+Code Update Policy
+------------------
+
+Instead of explicitly trusting host data values, members can set a **code update policy** — a JavaScript function that evaluates transparent statements presented by joining nodes. A transparent statement is a COSE_Sign1 envelope carrying a signed statement about the node's code, countersigned with a CCF receipt that proves the statement was registered on a ledger.
+
+.. note::
+
+    CCF currently only supports **self-issued** transparent statements: the service itself acts as the transparency service, issuing receipts over signed statements registered on its own ledger.
+
+The policy receives an array of transparent statements and must return ``true`` to accept or a string describing the rejection reason. Any other return value is treated as an error. Structural validation (non-empty fields, receipt signature verification, claims digest binding) is performed by CCF before the policy runs; the policy only needs to compare values.
+
+Policy Input Schema
+~~~~~~~~~~~~~~~~~~~
+
+The ``apply(transparent_statements)`` function receives an array of transparent statement objects. Each element has the following shape:
+
+.. code-block:: javascript
+
+    [
+      {
+        phdr: {                           // COSE_Sign1 protected header
+          alg: <int>,                     // REQUIRED - COSE algorithm (e.g. -7 for ES256)
+          cty: <int|string|undefined>,    // OPTIONAL - content type
+          x5chain: [<string>, ...],       // REQUIRED - certificate chain (PEM)
+          cwt: {                          // CWT claims
+            iss: <string>,                // REQUIRED - issuer DID (did:x509:...)
+            sub: <string>,                // REQUIRED - subject / feed
+            iat: <int|undefined>,         // OPTIONAL - issued-at (Unix timestamp)
+            svn: <int|undefined>,         // OPTIONAL - security version number
+          },
+        },
+        receipts: [                       // at least one CCF receipt
+          {
+            alg: <int>,                   // REQUIRED - signature algorithm
+            vds: <int>,                   // REQUIRED - verifiable data structure (1 = CCF_LEDGER_SHA256)
+            kid: <string|undefined>,      // OPTIONAL - key identifier
+            cwt: {                        // receipt CWT claims
+              iss: <string>,              // REQUIRED - receipt issuer (e.g. "service.example.com")
+              sub: <string>,              // REQUIRED - receipt subject
+              iat: <int|undefined>,       // OPTIONAL - receipt issued-at
+            },
+            ccf: {                        // CCF-specific claims
+              txid: <string|undefined>,   // OPTIONAL - transaction ID (e.g. "2.42")
+            },
+            leaves: [                     // at least one Merkle tree leaf
+              {
+                claims_digest: <string>,      // hex-encoded SHA-256
+                commit_evidence: <string>,    // commit evidence string
+                write_set_digest: <string>,   // hex-encoded SHA-256
+              },
+              ...
+            ],
+          },
+          ...
+        ],
+      },
+      ...
+    ]
+
+Example Policy
+~~~~~~~~~~~~~~
+
+.. code-block:: javascript
+
+    export function apply(transparent_statements) {
+      for (const ts of transparent_statements) {
+        if (ts.phdr.alg !== -7) {
+          return "Unexpected algorithm: " + ts.phdr.alg;
+        }
+        if (ts.phdr.cwt.iss !== "did:x509:abc::eku:1.2.3") {
+          return "Invalid issuer: " + ts.phdr.cwt.iss;
+        }
+        if (ts.phdr.cwt.sub !== "my-application") {
+          return "Invalid subject: " + ts.phdr.cwt.sub;
+        }
+        if (ts.phdr.cwt.svn < 100) {
+          return "SVN too low: " + ts.phdr.cwt.svn;
+        }
+
+        for (const r of ts.receipts) {
+          if (r.alg !== -7) {
+            return "Unexpected receipt algorithm: " + r.alg;
+          }
+          if (r.vds !== 1) {
+            return "Unexpected VDS: " + r.vds;
+          }
+          if (r.cwt.iss !== "service.example.com") {
+            return "Invalid receipt issuer: " + r.cwt.iss;
+          }
+          if (r.cwt.sub !== "ledger.signature") {
+            return "Invalid receipt subject: " + r.cwt.sub;
+          }
+
+          for (const leaf of r.leaves) {
+            if (leaf.claims_digest !== "abcdef...") {
+              return "Unexpected claims_digest: " + leaf.claims_digest;
+            }
+            if (leaf.commit_evidence !== "ce:2.42:deadbeef") {
+              return "Unexpected commit_evidence: " + leaf.commit_evidence;
+            }
+            if (leaf.write_set_digest !== "012345...") {
+              return "Unexpected write_set_digest: " + leaf.write_set_digest;
+            }
+          }
+        }
+      }
+      return true;
+    }
+
+Setting the Policy
+~~~~~~~~~~~~~~~~~~
+
+Use the ``set_node_join_policy`` governance action to register the policy and ``remove_node_join_policy`` to remove it.
+
+Joining with a Transparent Statement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a node joins the network, it can present a transparent statement by setting the ``host_data_transparent_statement_path`` field in the ``join`` section of its configuration file. This must point to a COSE Sign1 file (the transparent statement) that attests to the node's host data:
+
+.. code-block:: json
+
+    {
+      "command": {
+        "join": {
+          "host_data_transparent_statement_path": "/path/to/transparent_statement.cose"
+        }
+      }
+    }
+
+If the joining node's host data is not in the trusted list (i.e. not registered via ``add_snp_host_data``), CCF falls back to evaluating the transparent statement against the code update policy. If no transparent statement is provided, or the policy rejects it, the node will not be allowed to join. If the host data is already explicitly trusted, the node joins without evaluating the policy, regardless of whether a transparent statement is provided.

doc/schemas/app_openapi.json

@@ -1569,6 +1569,38 @@
         }
       }
     },
+    "/app/log/signed_statement": {
+      "post": {
+        "operationId": "PostAppLogSignedStatement",
+        "responses": {
+          "204": {
+            "description": "Default response description"
+          },
+          "default": {
+            "$ref": "#/components/responses/default"
+          }
+        },
+        "x-ccf-forwarding": {
+          "$ref": "#/components/x-ccf-forwarding/always"
+        }
+      }
+    },
+    "/app/log/transparent_statement": {
+      "get": {
+        "operationId": "GetAppLogTransparentStatement",
+        "responses": {
+          "204": {
+            "description": "Default response description"
+          },
+          "default": {
+            "$ref": "#/components/responses/default"
+          }
+        },
+        "x-ccf-forwarding": {
+          "$ref": "#/components/x-ccf-forwarding/never"
+        }
+      }
+    },
     "/app/multi_auth": {
       "post": {
         "operationId": "PostAppMultiAuth",

include/ccf/network_identity_interface.h

@@ -4,6 +4,7 @@
 
 #include "ccf/crypto/ec_public_key.h"
 #include "ccf/node_subsystem_interface.h"
+#include "ccf/tx_id.h"
 
 #include <exception>
 #include <map>

include/ccf/node/quote.h

@@ -3,11 +3,13 @@
 #pragma once
 
 #include "ccf/ds/quote_info.h"
+#include "ccf/network_identity_interface.h"
 #include "ccf/pal/attestation_sev_snp.h"
 #include "ccf/pal/measurement.h"
 #include "ccf/service/tables/host_data.h"
 #include "ccf/tx.h"
 
+#include <memory>
 #include <optional>
 #include <vector>
 
@@ -44,7 +46,10 @@ namespace ccf
       ccf::kv::ReadOnlyTx& tx,
       const QuoteInfo& quote_info,
       const std::vector<uint8_t>& expected_node_public_key_der,
-      pal::PlatformAttestationMeasurement& measurement);
+      pal::PlatformAttestationMeasurement& measurement,
+      const std::optional<std::vector<uint8_t>>& code_transparent_statement,
+      std::shared_ptr<NetworkIdentitySubsystemInterface>
+        network_identity_subsystem = nullptr);
   };
   QuoteVerificationResult verify_tcb_version_against_store(
     ccf::kv::ReadOnlyTx& tx, const QuoteInfo& quote_info);

include/ccf/node/startup_config.h

@@ -99,6 +99,18 @@ namespace ccf
       size_t tx_count = 10'000;
       std::optional<std::string> read_only_directory = std::nullopt;
 
+      struct BackupFetch
+      {
+        bool enabled = false;
+        size_t max_attempts = 3;
+        ccf::ds::TimeString retry_interval = {"1000ms"};
+        std::string target_rpc_interface = ccf::PRIMARY_RPC_INTERFACE;
+        ccf::ds::SizeString max_size = {"200MB"};
+
+        bool operator==(const BackupFetch&) const = default;
+      };
+      BackupFetch backup_fetch = {};
+
       bool operator==(const Snapshots&) const = default;
     };
     Snapshots snapshots = {};
@@ -159,6 +171,8 @@ namespace ccf
       size_t fetch_snapshot_max_attempts{};
       ccf::ds::TimeString fetch_snapshot_retry_interval;
       ccf::ds::SizeString fetch_snapshot_max_size;
+      std::optional<std::string> host_data_transparent_statement_path =
+        std::nullopt;
     };
     Join join = {};
 

include/ccf/service/tables/node_join_policy.h

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the Apache 2.0 License.
+#pragma once
+
+#include "ccf/kv/value.h"
+
+namespace ccf
+{
+  using CodeUpdatePolicy = ccf::kv::RawCopySerialisedValue<std::string>;
+
+  namespace Tables
+  {
+    static constexpr auto NODE_JOIN_POLICY =
+      "public:ccf.gov.nodes.node_join_policy";
+  }
+}