COSE-only ledgers (#7772)

Co-authored-by: Amaury Chamayou <amchamay@microsoft.com>
Co-authored-by: Amaury Chamayou <amaury@xargs.fr>

Author: maxtropets

CHANGELOG.md

@@ -26,6 +26,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
+- Added support for COSE-only ledger signatures. Networks can start in COSE-only mode or transition from dual signing (#7772).
+- Added `/receipt/cose` endpoint returning a COSE Sign1 receipt with Merkle proof for a given transaction. Returns 404 if no COSE receipt is available (e.g. for signature transactions) (#7772).
 - Added support for inline transaction receipt construction at commit time. Endpoint authors can use `build_receipt_for_committed_tx()` to construct a full `TxReceiptImpl` from the `CommittedTxInfo` passed to their `ConsensusCommittedEndpointFunction` callback. See the logging sample app (`/log/blocking/private/receipt`) for example usage (#7785).
 
 ### Changed

CMakeLists.txt

@@ -985,7 +985,10 @@ if(BUILD_TESTS)
   add_e2e_test(
     NAME recovery_test
     PYTHON_SCRIPT ${CMAKE_SOURCE_DIR}/tests/recovery.py
-    ADDITIONAL_ARGS ${ADDITIONAL_RECOVERY_ARGS}
+    ADDITIONAL_ARGS
+      ${ADDITIONAL_RECOVERY_ARGS}
+      --constitution
+      ${CMAKE_SOURCE_DIR}/samples/constitutions/virtual/virtual_attestation_actions.js
   )
 
   add_e2e_test(
@@ -1227,6 +1230,8 @@ if(BUILD_TESTS)
     NAME schema_test
     PYTHON_SCRIPT ${CMAKE_SOURCE_DIR}/tests/schema.py
     ADDITIONAL_ARGS
+      --constitution
+      ${CMAKE_SOURCE_DIR}/samples/constitutions/virtual/virtual_attestation_actions.js
       --schema-dir
       ${CMAKE_SOURCE_DIR}/doc/schemas
       --ledger-tutorial

doc/operations/configuration.rst

@@ -40,3 +40,22 @@ Since these operations may require disk IO and produce large responses, these fe
     - Size strings are expressed as the value suffixed with the size in bytes (``B``, ``KB``, ``MB``, ``GB``, ``TB``, as factors of 1024), e.g. ``"20MB"``, ``"100KB"`` or ``"2048"`` (bytes).
 
     - Time strings are expressed as the value suffixed with the duration (``us``, ``ms``, ``s``, ``min``, ``h``), e.g. ``"1000ms"``, ``"10s"`` or ``"30min"``.
+
+
+Upgrading to COSE-Only Ledger Signatures
+-----------------------------------------
+
+By default, CCF nodes emit **dual** ledger signatures: a traditional node signature and a COSE Sign1 signature. Applications control this via the ``ccf::get_ledger_sign_mode()`` weak-symbol callback declared in ``ccf/node/ledger_sign_mode.h``, which returns one of three modes:
+
+- ``Dual`` (default) — emit both signature types, accept all joiners.
+- ``CoseAllowDualJoin`` — emit only COSE signatures, but still accept join requests from ``Dual``-mode nodes. Use during rolling upgrades.
+- ``CoseOnly`` — emit only COSE signatures, reject ``Dual``-mode joiners. Final state after upgrade.
+
+The mode is set at link time by providing a strong definition in the application binary. Joining nodes advertise their signing mode in the join request.
+
+A rolling upgrade from ``Dual`` to ``CoseOnly`` is a two-step process:
+
+1. **CoseAllowDualJoin.** Deploy a binary that returns ``CoseAllowDualJoin``. Replace nodes one at a time. During this phase, new nodes running the old ``Dual`` binary can still join as replacements.
+
+2. **CoseOnly.** Once all nodes are upgraded, deploy a binary that returns ``CoseOnly``. Replace nodes again. After this, ``Dual`` joiners are rejected.
+

doc/schemas/app_openapi.json

@@ -31,6 +31,10 @@
         },
         "type": "object"
       },
+      "Cose": {
+        "format": "binary",
+        "type": "string"
+      },
       "GetCommit__Out": {
         "properties": {
           "transaction_id": {
@@ -1743,6 +1747,41 @@
         }
       }
     },
+    "/app/receipt/cose": {
+      "get": {
+        "description": "A COSE Sign1 envelope containing a signed statement from the service over a transaction entry in the ledger, with a Merkle proof in the unprotected header. See https://datatracker.ietf.org/doc/draft-ietf-scitt-receipts-ccf-profile/ for a complete description.",
+        "operationId": "GetAppReceiptCose",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "transaction_id",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/TransactionId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/cose": {
+                "schema": {
+                  "$ref": "#/components/schemas/Cose"
+                }
+              }
+            },
+            "description": "Default response description"
+          },
+          "default": {
+            "$ref": "#/components/responses/default"
+          }
+        },
+        "summary": "COSE receipt for a transaction",
+        "x-ccf-forwarding": {
+          "$ref": "#/components/x-ccf-forwarding/sometimes"
+        }
+      }
+    },
     "/app/tx": {
       "get": {
         "description": "Possible statuses returned are Unknown, Pending, Committed or Invalid.",

doc/schemas/node_openapi.json

@@ -198,6 +198,10 @@
         ],
         "type": "string"
       },
+      "Cose": {
+        "format": "binary",
+        "type": "string"
+      },
       "Endorsement": {
         "properties": {
           "authority": {
@@ -1641,6 +1645,41 @@
         }
       }
     },
+    "/node/receipt/cose": {
+      "get": {
+        "description": "A COSE Sign1 envelope containing a signed statement from the service over a transaction entry in the ledger, with a Merkle proof in the unprotected header. See https://datatracker.ietf.org/doc/draft-ietf-scitt-receipts-ccf-profile/ for a complete description.",
+        "operationId": "GetNodeReceiptCose",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "transaction_id",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/TransactionId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/cose": {
+                "schema": {
+                  "$ref": "#/components/schemas/Cose"
+                }
+              }
+            },
+            "description": "Default response description"
+          },
+          "default": {
+            "$ref": "#/components/responses/default"
+          }
+        },
+        "summary": "COSE receipt for a transaction",
+        "x-ccf-forwarding": {
+          "$ref": "#/components/x-ccf-forwarding/sometimes"
+        }
+      }
+    },
     "/node/self_signed_certificate": {
       "get": {
         "operationId": "GetNodeSelfSignedCertificate",

include/ccf/ds/openapi.h

@@ -20,6 +20,25 @@
  * fill every _required_ field, and the resulting object can be further
  * modified by hand as required.
  */
+namespace ccf::ds::openapi
+{
+  /** Tag type representing a binary COSE body (application/cose). */
+  struct Cose
+  {};
+
+  inline void fill_json_schema(
+    nlohmann::json& schema, [[maybe_unused]] const Cose* cose)
+  {
+    schema["type"] = "string";
+    schema["format"] = "binary";
+  }
+
+  inline std::string schema_name([[maybe_unused]] const Cose* cose)
+  {
+    return "Cose";
+  }
+}
+
 namespace ccf::ds::openapi
 {
   namespace access
@@ -393,6 +412,10 @@ namespace ccf::ds::openapi
     {
       return http::headervalues::contenttype::TEXT;
     }
+    else if constexpr (std::is_same_v<T, Cose>)
+    {
+      return http::headervalues::contenttype::COSE;
+    }
     else
     {
       return http::headervalues::contenttype::JSON;

include/ccf/node/ledger_sign_mode.h

@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the Apache 2.0 License.
+#pragma once
+
+#include "ccf/ds/json.h"
+
+#include <cstdint>
+
+namespace ccf
+{
+  enum class LedgerSignMode : uint8_t
+  {
+    // Emit both traditional node signatures and COSE Sign1 signatures.
+    // Accept join requests from nodes in any signing mode.
+    Dual = 0,
+
+    // Emit only COSE Sign1 signatures, but accept join requests from
+    // nodes still running in Dual mode. Use during rolling upgrades.
+    CoseAllowDualJoin = 1,
+
+    // Emit only COSE Sign1 signatures and reject join requests from
+    // nodes running in Dual mode. Final state after a completed upgrade.
+    CoseOnly = 2
+  };
+
+  DECLARE_JSON_ENUM(
+    LedgerSignMode,
+    {{LedgerSignMode::Dual, "Dual"},
+     {LedgerSignMode::CoseAllowDualJoin, "CoseAllowDualJoin"},
+     {LedgerSignMode::CoseOnly, "CoseOnly"}});
+
+  /** Can be optionally implemented by the application to set the ledger
+   * signing mode.
+   *
+   * The default (weak) implementation returns LedgerSignMode::Dual.
+   *
+   * @return the desired ledger signing mode
+   */
+  LedgerSignMode get_ledger_sign_mode();
+}

python/src/ccf/cose.py

@@ -195,6 +195,7 @@ def verify_receipt(
     """
     Verify a COSE Sign1 receipt as defined in https://datatracker.ietf.org/doc/draft-ietf-cose-merkle-tree-proofs/,
     using the CCF tree algorithm defined in https://datatracker.ietf.org/doc/draft-birkholz-cose-receipts-ccf-profile/
+
     """
     key_pem = key.public_bytes(Encoding.PEM, PublicFormat.SubjectPublicKeyInfo).decode(
         "ascii"

python/src/ccf/ledger.py

@@ -724,10 +724,14 @@ def add_transaction(self, transaction):
                 else:
                     self.node_certificates[node_id] = endorsed_node_cert
 
-        # This is a merkle root/signature tx if the table exists
-        if SIGNATURE_TX_TABLE_NAME in tables:
+        # This is a merkle root/signature tx if either signature table exists
+        is_signature_tx = (
+            SIGNATURE_TX_TABLE_NAME in tables or COSE_SIGNATURE_TX_TABLE_NAME in tables
+        )
+        if is_signature_tx:
             self.signature_count += 1
 
+        if SIGNATURE_TX_TABLE_NAME in tables:
             if self.verification_level >= VerificationLevel.MERKLE:
                 signature_table = tables[SIGNATURE_TX_TABLE_NAME]
 

samples/apps/logging/CMakeLists.txt

@@ -12,3 +12,21 @@ if(NOT TARGET "ccf")
 endif()
 
 add_ccf_app(logging SRCS logging.cpp create_tx_claims_digest.cpp ../main.cpp)
+
+add_ccf_app(
+  logging_cose_only
+  SRCS
+    logging.cpp
+    create_tx_claims_digest.cpp
+    get_ledger_sign_mode_cose.cpp
+    ../main.cpp
+)
+
+add_ccf_app(
+  logging_cose_only_allow_join_dual
+  SRCS
+    logging.cpp
+    create_tx_claims_digest.cpp
+    get_ledger_sign_mode_cose_allow_join_dual.cpp
+    ../main.cpp
+)