Implement separate Produce and Consume SetupPayload validation modes

In Consume mode, unknown rendevouz flags are allowed.

Author: ksperling-apple

src/setup_payload/SetupPayload.cpp

@@ -36,7 +36,7 @@ namespace chip {
 // Check the Setup Payload for validity
 //
 // `vendor_id` and `product_id` are allowed all of uint16_t
-bool PayloadContents::isValidQRCodePayload() const
+bool PayloadContents::isValidQRCodePayload(ValidationMode mode) const
 {
     // 3-bit value specifying the QR code payload version.
     if (version >= 1 << kVersionFieldLengthInBits)
@@ -50,6 +50,7 @@ bool PayloadContents::isValidQRCodePayload() const
     }
 
     // Device Commissioning Flow
+    // Even in ValidatoinMode::kConsume we can only handle modes that we understand.
     // 0: Standard commissioning flow: such a device, when uncommissioned, always enters commissioning mode upon power-up, subject
     // to the rules in [ref_Announcement_Commencement]. 1: User-intent commissioning flow: user action required to enter
     // commissioning mode. 2: Custom commissioning flow: interaction with a vendor-specified means is needed before commissioning.
@@ -60,13 +61,6 @@ bool PayloadContents::isValidQRCodePayload() const
         return false;
     }
 
-    chip::RendezvousInformationFlags allvalid(RendezvousInformationFlag::kBLE, RendezvousInformationFlag::kOnNetwork,
-                                              RendezvousInformationFlag::kSoftAP);
-    if (!rendezvousInformation.HasValue() || !rendezvousInformation.Value().HasOnly(allvalid))
-    {
-        return false;
-    }
-
     // General discriminator validity is enforced by the SetupDiscriminator class, but it can't be short for QR a code.
     if (discriminator.IsShortDiscriminator())
     {
@@ -78,13 +72,21 @@ bool PayloadContents::isValidQRCodePayload() const
         return false;
     }
 
+    // RendevouzInformation must be present for a QR code.
+    VerifyOrReturnValue(rendezvousInformation.HasValue(), false);
+    if (mode == ValidationMode::kProduce)
+    {
+        chip::RendezvousInformationFlags valid(RendezvousInformationFlag::kBLE, RendezvousInformationFlag::kOnNetwork,
+                                               RendezvousInformationFlag::kSoftAP);
+        VerifyOrReturnValue(rendezvousInformation.Value().HasOnly(valid), false);
+    }
+
     return CheckPayloadCommonConstraints();
 }
 
-bool PayloadContents::isValidManualCode() const
+bool PayloadContents::isValidManualCode(ValidationMode mode) const
 {
     // Discriminator validity is enforced by the SetupDiscriminator class.
-
     if (setUpPINCode >= 1 << kSetupPINCodeFieldLengthInBits)
     {
         return false;
@@ -109,7 +111,9 @@ bool PayloadContents::IsValidSetupPIN(uint32_t setupPIN)
 
 bool PayloadContents::CheckPayloadCommonConstraints() const
 {
-    // A version not equal to 0 would be invalid for v1 and would indicate new format (e.g. version 2)
+    // Validation rules in this method apply to all validation modes.
+
+    // Even in ValidationMode::kConsume we don't understand how to handle any payload version other than 0.
     if (version != 0)
     {
         return false;

src/setup_payload/SetupPayload.h

@@ -128,8 +128,20 @@ struct PayloadContents
     SetupDiscriminator discriminator;
     uint32_t setUpPINCode = 0;
 
-    bool isValidQRCodePayload() const;
-    bool isValidManualCode() const;
+    enum class ValidationMode : uint8_t
+    {
+        kProduce, ///< Only flags or values allowed by the current spec version are allowed.
+                  ///  Producers of a Setup Payload should use this mode to ensure the
+                  //   payload is valid according to the current spec version.
+        kConsume, ///< Flags or values that are reserved for future use, or were allowed in
+                  ///  a previous spec version may be present. Consumers of a Setup Payload
+                  ///  should use this mode to ensure they are forward and backwards
+                  ///  compatible with payloads from older or newer Matter devices.
+    };
+
+    bool isValidQRCodePayload(ValidationMode mode = ValidationMode::kProduce) const;
+    bool isValidManualCode(ValidationMode mode = ValidationMode::kProduce) const;
+
     bool operator==(const PayloadContents & input) const;
 
     static bool IsValidSetupPIN(uint32_t setupPIN);

src/setup_payload/tests/TestQRCode.cpp

@@ -307,6 +307,13 @@ TEST(TestQRCode, TestSetupPayloadVerify)
     invalid.SetRaw(static_cast<uint8_t>(invalid.Raw() + 1));
     test_payload.rendezvousInformation.SetValue(invalid);
     EXPECT_EQ(test_payload.isValidQRCodePayload(), false);
+    // When validating in Consume mode, unknown rendezvous flags are OK.
+    EXPECT_TRUE(test_payload.isValidQRCodePayload(PayloadContents::ValidationMode::kConsume));
+    test_payload.rendezvousInformation.SetValue(RendezvousInformationFlags(0xff));
+    EXPECT_TRUE(test_payload.isValidQRCodePayload(PayloadContents::ValidationMode::kConsume));
+    // Rendezvous information is still required even in Consume mode.
+    test_payload.rendezvousInformation.ClearValue();
+    EXPECT_FALSE(test_payload.isValidQRCodePayload(PayloadContents::ValidationMode::kConsume));
 
     // test invalid setup PIN
     test_payload              = payload;