src/setup_payload/SetupPayload.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 /**
  19  *    @file
  20  *      This file describes a QRCode Setup Payload class to hold
  21  *      data enumerated from a byte stream
  22  */
  23
  24 #pragma once
  25
  26 #include <map>
  27 #include <stdint.h>
  28 #include <string>
  29 #include <vector>
  30
  31 #include <core/CHIPError.h>
  32
  33 namespace chip {
  34
  35 // TODO this should point to the spec
  36 const int kVersionFieldLengthInBits                   = 3;
  37 const int kVendorIDFieldLengthInBits                  = 16;
  38 const int kProductIDFieldLengthInBits                 = 16;
  39 const int kCustomFlowRequiredFieldLengthInBits        = 1;
  40 const int kRendezvousInfoFieldLengthInBits            = 8;
  41 const int kPayloadDiscriminatorFieldLengthInBits      = 12;
  42 const int kManualSetupDiscriminatorFieldLengthInBits  = 4;
  43 const int kManualSetupChunk1DiscriminatorMsbitsPos    = 0;
  44 const int kManualSetupChunk1DiscriminatorMsbitsLength = 2;
  45 const int kManualSetupChunk1VidPidPresentBitPos =
  46     (kManualSetupChunk1DiscriminatorMsbitsPos + kManualSetupChunk1DiscriminatorMsbitsLength);
  47 const int kManualSetupChunk2PINCodeLsbitsPos       = 0;
  48 const int kManualSetupChunk2PINCodeLsbitsLength    = 14;
  49 const int kManualSetupChunk2DiscriminatorLsbitsPos = (kManualSetupChunk2PINCodeLsbitsPos + kManualSetupChunk2PINCodeLsbitsLength);
  50 const int kManualSetupChunk2DiscriminatorLsbitsLength = 2;
  51 const int kManualSetupChunk3PINCodeMsbitsPos          = 0;
  52 const int kManualSetupChunk3PINCodeMsbitsLength       = 13;
  53 const int kSetupPINCodeFieldLengthInBits              = 27;
  54 const int kPaddingFieldLengthInBits                   = 5;
  55
  56 const int kRawVendorTagLengthInBits = 7;
  57
  58 const int kManualSetupShortCodeCharLength  = 10;
  59 const int kManualSetupLongCodeCharLength   = 20;
  60 const int kManualSetupCodeChunk1CharLength = 1;
  61 const int kManualSetupCodeChunk2CharLength = 5;
  62 const int kManualSetupCodeChunk3CharLength = 4;
  63 const int kManualSetupVendorIdCharLength   = 5;
  64 const int kManualSetupProductIdCharLength  = 5;
  65
  66 const uint8_t kSerialNumberTag = 128;
  67
  68 // The largest value of the 12-bit Payload discriminator
  69 const uint16_t kMaxDiscriminatorValue = 0xFFF;
  70
  71 // clang-format off
  72 const int kTotalPayloadDataSizeInBits =
  73     kVersionFieldLengthInBits +
  74     kVendorIDFieldLengthInBits +
  75     kProductIDFieldLengthInBits +
  76     kCustomFlowRequiredFieldLengthInBits +
  77     kRendezvousInfoFieldLengthInBits +
  78     kPayloadDiscriminatorFieldLengthInBits +
  79     kSetupPINCodeFieldLengthInBits +
  80     kPaddingFieldLengthInBits;
  81 // clang-format on
  82
  83 const int kTotalPayloadDataSizeInBytes = kTotalPayloadDataSizeInBits / 8;
  84
  85 const char * const kQRCodePrefix = "CH:";
  86
  87 /// The rendezvous type this device supports.
  88 enum class RendezvousInformationFlags : uint16_t
  89 {
  90     kNone     = 0,      ///< Device does not support any method for rendezvous
  91     kWiFi     = 1 << 0, ///< Device supports Wi-Fi
  92     kBLE      = 1 << 1, ///< Device supports BLE
  93     kThread   = 1 << 2, ///< Device supports Thread
  94     kEthernet = 1 << 3, ///< Device MAY be attached to a wired 802.3 connection
  95
  96     kAllMask = kWiFi | kBLE | kThread | kEthernet,
  97 };
  98
  99 enum optionalQRCodeInfoType
 100 {
 101     optionalQRCodeInfoTypeUnknown,
 102     optionalQRCodeInfoTypeString,
 103     optionalQRCodeInfoTypeInt32,
 104     optionalQRCodeInfoTypeInt64,
 105     optionalQRCodeInfoTypeUInt32,
 106     optionalQRCodeInfoTypeUInt64
 107 };
 108
 109 /**
 110  * A structure to hold optional QR Code info
 111  */
 112 struct OptionalQRCodeInfo
 113 {
 114     OptionalQRCodeInfo() { int32 = 0; }
 115
 116     /*@{*/
 117     uint8_t tag;                      /**< the tag number of the optional info */
 118     enum optionalQRCodeInfoType type; /**< the type (String or Int) of the optional info */
 119     std::string data;                 /**< the string value if type is optionalQRCodeInfoTypeString, otherwise should not be set */
 120     int32_t int32;                    /**< the integer value if type is optionalQRCodeInfoTypeInt, otherwise should not be set */
 121     /*@}*/
 122 };
 123
 124 struct OptionalQRCodeInfoExtension : OptionalQRCodeInfo
 125 {
 126     OptionalQRCodeInfoExtension()
 127     {
 128         int32  = 0;
 129         int64  = 0;
 130         uint32 = 0;
 131         uint64 = 0;
 132     }
 133
 134     int64_t int64;
 135     uint64_t uint32;
 136     uint64_t uint64;
 137 };
 138
 139 bool IsCHIPTag(uint8_t tag);
 140 bool IsVendorTag(uint8_t tag);
 141
 142 class SetupPayload
 143 {
 144
 145     friend class QRCodeSetupPayloadGenerator;
 146     friend class QRCodeSetupPayloadParser;
 147
 148 public:
 149     uint8_t version;
 150     uint16_t vendorID;
 151     uint16_t productID;
 152     bool requiresCustomFlow;
 153     RendezvousInformationFlags rendezvousInformation;
 154     uint16_t discriminator;
 155     uint32_t setUpPINCode;
 156
 157     /** @brief A function to add an optional vendor data
 158      * @param tag 7 bit [0-127] tag number
 159      * @param data String representation of data to add
 160      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
 161      **/
 162     CHIP_ERROR addOptionalVendorData(uint8_t tag, std::string data);
 163
 164     /** @brief A function to add an optional vendor data
 165      * @param tag 7 bit [0-127] tag number
 166      * @param data Integer representation of data to add
 167      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
 168      **/
 169     CHIP_ERROR addOptionalVendorData(uint8_t tag, int32_t data);
 170
 171     /** @brief A function to remove an optional vendor data
 172      * @param tag 7 bit [0-127] tag number
 173      * @return Returns a CHIP_ERROR_KEY_NOT_FOUND on error, CHIP_NO_ERROR otherwise
 174      **/
 175     CHIP_ERROR removeOptionalVendorData(uint8_t tag);
 176     /**
 177      * @brief A function to retrieve the vector of OptionalQRCodeInfo infos
 178      * @return Returns a vector of optionalQRCodeInfos
 179      **/
 180     std::vector<OptionalQRCodeInfo> getAllOptionalVendorData();
 181
 182     /** @brief A function to add a string serial number
 183      * @param serialNumber string serial number
 184      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
 185      **/
 186     CHIP_ERROR addSerialNumber(std::string serialNumber);
 187
 188     /** @brief A function to add a uint32_t serial number
 189      * @param serialNumber uint32_t serial number
 190      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
 191      **/
 192     CHIP_ERROR addSerialNumber(uint32_t serialNumber);
 193
 194     /** @brief A function to retrieve serial number as a string
 195      * @param outSerialNumber retrieved string serial number
 196      * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
 197      **/
 198     CHIP_ERROR getSerialNumber(std::string & outSerialNumber);
 199
 200     /** @brief A function to remove the serial number from the payload
 201      * @return Returns a CHIP_ERROR_KEY_NOT_FOUND on error, CHIP_NO_ERROR otherwise
 202      **/
 203     CHIP_ERROR removeSerialNumber();
 204
 205     // Test that the Setup Payload is within expected value ranges
 206     SetupPayload() :
 207         version(0), vendorID(0), productID(0), requiresCustomFlow(0), rendezvousInformation(RendezvousInformationFlags::kNone),
 208         discriminator(0), setUpPINCode(0)
 209     {}
 210
 211     bool isValidQRCodePayload();
 212     bool isValidManualCode();
 213     bool operator==(SetupPayload & input);
 214
 215 private:
 216     std::map<uint8_t, OptionalQRCodeInfo> optionalVendorData;
 217     std::map<uint8_t, OptionalQRCodeInfoExtension> optionalExtensionData;
 218
 219     /** @brief A function to add an optional QR Code info vendor object
 220      * @param info Optional QR code info object to add
 221      * @return Returns a CHIP_ERROR_INVALID_ARGUMENT on error, CHIP_NO_ERROR otherwise
 222      **/
 223     CHIP_ERROR addOptionalVendorData(const OptionalQRCodeInfo & info);
 224
 225     /** @brief A function to add an optional QR Code info CHIP object
 226      * @param info Optional QR code info object to add
 227      * @return Returns a CHIP_ERROR_INVALID_ARGUMENT on error, CHIP_NO_ERROR otherwise
 228      **/
 229     CHIP_ERROR addOptionalExtensionData(const OptionalQRCodeInfoExtension & info);
 230
 231     /**
 232      * @brief A function to retrieve the vector of CHIPQRCodeInfo infos
 233      * @return Returns a vector of CHIPQRCodeInfos
 234      **/
 235     std::vector<OptionalQRCodeInfoExtension> getAllOptionalExtensionData();
 236
 237     /** @brief A function to retrieve an optional QR Code info vendor object
 238      * @param tag 7 bit [0-127] tag number
 239      * @param info retrieved OptionalQRCodeInfo object
 240      * @return Returns a CHIP_ERROR_KEY_NOT_FOUND on error, CHIP_NO_ERROR otherwise
 241      **/
 242     CHIP_ERROR getOptionalVendorData(uint8_t tag, OptionalQRCodeInfo & info);
 243
 244     /** @brief A function to retrieve an optional QR Code info extended object
 245      * @param tag 8 bit [128-255] tag number
 246      * @param info retrieved OptionalQRCodeInfoExtension object
 247      * @return Returns a CHIP_ERROR_KEY_NOT_FOUND on error, CHIP_NO_ERROR otherwise
 248      **/
 249     CHIP_ERROR getOptionalExtensionData(uint8_t tag, OptionalQRCodeInfoExtension & info);
 250
 251     /** @brief A function to retrieve the associated expected numeric value for a tag
 252      * @param tag 8 bit [0-255] tag number
 253      * @return Returns an optionalQRCodeInfoType value
 254      **/
 255     optionalQRCodeInfoType getNumericTypeFor(uint8_t tag);
 256 };
 257
 258 } // namespace chip