Self-transparent code update (#7681)

Co-authored-by: Amaury Chamayou <amaury@xargs.fr>
Co-authored-by: Eddy Ashton <ashton.eddy@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Amaury Chamayou <amchamay@microsoft.com>

Author: 4 people

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - 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
 

CMakeLists.txt

@@ -665,6 +665,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

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"],

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

@@ -1489,6 +1489,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

@@ -159,6 +159,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";
+  }
+}