Factory Provisioning Tool

-- Implemented a tool for factory provisioning of devices running OpenWeave firmware.  The
tool is designed to run on a host machine that is connected to a device via some form of
debug or control interface.  The tool works by injecting provisioning information into the
device’s RAM in a special encoded form designed to be easily identified.  The device is then
instructed to restart, at which point code in the initialization of the OpenWeave Device
Layer searches memory for the encoded data, validates it, and writes the contained values to
persistent storage in a format appropriate for the platform.

The tool is capable of provisioning the following information:

Device serial number
Manufacturer-assigned Weave device id
Manufacturer-assigned certificate and private key
Pairing code
Product revision number
Manufacturing date

Provisioning information is specified as command line arguments to the tool.  Alternatively,
the tool can be instructed read select information (certificate, private key and pairing
code) from a provisioning data CSV file, as produced by the weave tool’s
“gen-provisioning-data” command, or from an HTTP-based provisioning data server, as is used
in Nest factory provisioning.

Currently, the tool supports provisioning ESP32 devices using using the ESP32 serial
bootloader protocol, and nRF52840 devices using a SEGGER J-Link debug probe.

Author: Jay Logue

certs/development/device/test-dev-provisioning-data.csv

@@ -31,6 +31,10 @@
 #include <Weave/DeviceLayer/ESP32/ESP32Config.h>
 #include <Weave/DeviceLayer/internal/GenericConfigurationManagerImpl.ipp>
 
+#if WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING
+#include <Weave/DeviceLayer/internal/FactoryProvisioning.ipp>
+#endif // WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING
+
 #include "esp_wifi.h"
 #include "nvs_flash.h"
 #include "nvs.h"
@@ -89,6 +93,21 @@ WEAVE_ERROR ConfigurationManagerImpl::_Init()
     err = gGroupKeyStore.Init();
     SuccessOrExit(err);
 
+#if WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING
+
+    {
+        FactoryProvisioning factoryProv;
+        uint8_t * const kInternalSRAM12Start = (uint8_t *)0x3FFAE000;
+        uint8_t * const kInternalSRAM12End = kInternalSRAM12Start + (328 * 1024) - 1;
+
+        // Scan ESP32 Internal SRAM regions 1 and 2 for injected provisioning data and save
+        // to persistent storage if found.
+        err = factoryProv.ProvisionDeviceFromRAM(kInternalSRAM12Start, kInternalSRAM12End);
+        SuccessOrExit(err);
+    }
+
+#endif // WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING
+
     // If the fail-safe was armed when the device last shutdown, initiate a factory reset.
     if (_GetFailSafeArmed(failSafeArmed) == WEAVE_NO_ERROR && failSafeArmed)
     {

src/adaptations/device-layer/ESP32/ConfigurationManagerImpl.cpp

@@ -73,6 +73,8 @@ noinst_HEADERS                          = \
     include/Weave/DeviceLayer/internal/EchoServer.h \
     include/Weave/DeviceLayer/internal/EventLogging.h \
     include/Weave/DeviceLayer/internal/FabricProvisioningServer.h \
+    include/Weave/DeviceLayer/internal/FactoryProvisioning.h \
+    include/Weave/DeviceLayer/internal/FactoryProvisioning.ipp \
     include/Weave/DeviceLayer/internal/GenericConfigurationManagerImpl.h \
     include/Weave/DeviceLayer/internal/GenericConfigurationManagerImpl.ipp \
     include/Weave/DeviceLayer/internal/GenericNetworkProvisioningServerImpl.h \

src/adaptations/device-layer/Makefile.am

@@ -694,6 +694,8 @@ noinst_HEADERS = \
     include/Weave/DeviceLayer/internal/EchoServer.h \
     include/Weave/DeviceLayer/internal/EventLogging.h \
     include/Weave/DeviceLayer/internal/FabricProvisioningServer.h \
+    include/Weave/DeviceLayer/internal/FactoryProvisioning.h \
+    include/Weave/DeviceLayer/internal/FactoryProvisioning.ipp \
     include/Weave/DeviceLayer/internal/GenericConfigurationManagerImpl.h \
     include/Weave/DeviceLayer/internal/GenericConfigurationManagerImpl.ipp \
     include/Weave/DeviceLayer/internal/GenericNetworkProvisioningServerImpl.h \

src/adaptations/device-layer/Makefile.in

@@ -85,15 +85,15 @@ class ConfigurationManager
     WEAVE_ERROR GetPairedAccountId(char * buf, size_t bufSize, size_t & accountIdLen);
 
     WEAVE_ERROR StoreDeviceId(uint64_t deviceId);
-    WEAVE_ERROR StoreSerialNumber(const char * serialNum);
+    WEAVE_ERROR StoreSerialNumber(const char * serialNum, size_t serialNumLen);
     WEAVE_ERROR StorePrimaryWiFiMACAddress(const uint8_t * buf);
     WEAVE_ERROR StorePrimary802154MACAddress(const uint8_t * buf);
-    WEAVE_ERROR StoreManufacturingDate(const char * mfgDate);
+    WEAVE_ERROR StoreManufacturingDate(const char * mfgDate, size_t mfgDateLen);
     WEAVE_ERROR StoreProductRevision(uint16_t productRev);
     WEAVE_ERROR StoreFabricId(uint64_t fabricId);
     WEAVE_ERROR StoreDeviceCertificate(const uint8_t * cert, size_t certLen);
     WEAVE_ERROR StoreDevicePrivateKey(const uint8_t * key, size_t keyLen);
-    WEAVE_ERROR StorePairingCode(const char * pairingCode);
+    WEAVE_ERROR StorePairingCode(const char * pairingCode, size_t pairingCodeLen);
     WEAVE_ERROR StoreServiceProvisioningData(uint64_t serviceId, const uint8_t * serviceConfig, size_t serviceConfigLen, const char * accountId, size_t accountIdLen);
     WEAVE_ERROR ClearServiceProvisioningData();
     WEAVE_ERROR StoreServiceConfig(const uint8_t * serviceConfig, size_t serviceConfigLen);
@@ -281,9 +281,9 @@ inline WEAVE_ERROR ConfigurationManager::StoreDeviceId(uint64_t deviceId)
     return static_cast<ImplClass*>(this)->_StoreDeviceId(deviceId);
 }
 
-inline WEAVE_ERROR ConfigurationManager::StoreSerialNumber(const char * serialNum)
+inline WEAVE_ERROR ConfigurationManager::StoreSerialNumber(const char * serialNum, size_t serialNumLen)
 {
-    return static_cast<ImplClass*>(this)->_StoreSerialNumber(serialNum);
+    return static_cast<ImplClass*>(this)->_StoreSerialNumber(serialNum, serialNumLen);
 }
 
 inline WEAVE_ERROR ConfigurationManager::StorePrimaryWiFiMACAddress(const uint8_t * buf)
@@ -296,9 +296,9 @@ inline WEAVE_ERROR ConfigurationManager::StorePrimary802154MACAddress(const uint
     return static_cast<ImplClass*>(this)->_StorePrimary802154MACAddress(buf);
 }
 
-inline WEAVE_ERROR ConfigurationManager::StoreManufacturingDate(const char * mfgDate)
+inline WEAVE_ERROR ConfigurationManager::StoreManufacturingDate(const char * mfgDate, size_t mfgDateLen)
 {
-    return static_cast<ImplClass*>(this)->_StoreManufacturingDate(mfgDate);
+    return static_cast<ImplClass*>(this)->_StoreManufacturingDate(mfgDate, mfgDateLen);
 }
 
 inline WEAVE_ERROR ConfigurationManager::StoreProductRevision(uint16_t productRev)
@@ -321,9 +321,9 @@ inline WEAVE_ERROR ConfigurationManager::StoreDevicePrivateKey(const uint8_t * k
     return static_cast<ImplClass*>(this)->_StoreDevicePrivateKey(key, keyLen);
 }
 
-inline WEAVE_ERROR ConfigurationManager::StorePairingCode(const char * pairingCode)
+inline WEAVE_ERROR ConfigurationManager::StorePairingCode(const char * pairingCode, size_t pairingCodeLen)
 {
-    return static_cast<ImplClass*>(this)->_StorePairingCode(pairingCode);
+    return static_cast<ImplClass*>(this)->_StorePairingCode(pairingCode, pairingCodeLen);
 }
 
 inline WEAVE_ERROR ConfigurationManager::StoreServiceProvisioningData(uint64_t serviceId, const uint8_t * serviceConfig, size_t serviceConfigLen, const char * accountId, size_t accountIdLen)

src/adaptations/device-layer/include/Weave/DeviceLayer/ConfigurationManager.h

@@ -105,6 +105,18 @@
 #define WEAVE_DEVICE_CONFIG_LOG_MESSAGE_MAX_SIZE 256
 #endif
 
+/**
+ * WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING
+ *
+ * Enable the device factory provisioning feature.
+ *
+ * The factory provisioning feature allows factory or developer-supplied provisioning information
+ * to be injected into a device at boot time and automatically stored in persistent storage.
+ */
+#ifndef WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING
+#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 1
+#endif
+
 // -------------------- Device Identification Configuration --------------------
 
 /**

src/adaptations/device-layer/include/Weave/DeviceLayer/WeaveDeviceConfig.h

@@ -0,0 +1,118 @@
+/*
+ *
+ *    Copyright (c) 2019 Google LLC.
+ *    All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+/**
+ *    @file
+ *          Support for device factory provisioning.
+ */
+
+#ifndef FACTORY_PROVISIONING_H
+#define FACTORY_PROVISIONING_H
+
+#include <Weave/DeviceLayer/internal/WeaveDeviceLayerInternal.h>
+
+namespace nl {
+namespace Weave {
+namespace TLV {
+class TLVReader;
+} // namespace TLV
+} // namespace Weave
+} // namespace nl
+
+namespace nl {
+namespace Weave {
+namespace DeviceLayer {
+namespace Internal {
+
+/**
+ * Supports device factory provisioning at boot time.
+ *
+ * The factory provisioning feature allows factory or developer-supplied provisioning information
+ * to be injected into a device at boot time and automatically stored in persistent storage.
+ * Provisioning information is written into device memory (typically RAM) by an external tool,
+ * where it is picked by the OpenWeave initialization code and stored into persistent storage
+ * early in the boot process.
+ *
+ * The factory provisioning feature allows the following values to be set:
+ *
+ * - Device Serial number
+ * - Manufacturer-assigned Device Id
+ * - Manufacturer-assigned Device Certificate
+ * - Manufacturer-assigned Device Key
+ * - Pairing Code
+ * - Product Revision
+ * - Manufacturing Date
+ *
+ * This template class provides a default base implementation of the device provisioning feature
+ * that can be specialized as needed by compile-time derivation.
+ */
+template<class DerivedClass>
+class FactoryProvisioningBase
+{
+public:
+    WEAVE_ERROR ProvisionDeviceFromRAM(uint8_t * memRangeStart, uint8_t * memRangeEnd);
+
+protected:
+    bool LocateProvisioningData(uint8_t * memRangeStart, uint8_t * memRangeEnd, uint8_t * & dataStart, size_t & dataLen);
+    WEAVE_ERROR StoreProvisioningData(TLV::TLVReader & reader);
+    WEAVE_ERROR StoreProvisioningValue(uint8_t tagNum, TLV::TLVReader & reader);
+
+private:
+    DerivedClass * Derived() { return static_cast<DerivedClass *>(this); }
+};
+
+/**
+ * Default implementation of the device factory provisioning feature.
+ */
+class FactoryProvisioning
+    : public FactoryProvisioningBase<FactoryProvisioning>
+{
+};
+
+namespace FactoryProvisioningData {
+
+/**
+ * Context-specific tags for Device Provisioning Data Weave TLV structure
+ */
+enum
+{
+    kTag_SerialNumber           = 0,    // [ utf-8 string ] Serial number
+    kTag_DeviceId               = 1,    // [ uint, 64-bit max ] Manufacturer-assigned device id
+    kTag_DeviceCert             = 2,    // [ byte string ] Manufacturer-assigned device certificate
+    kTag_DevicePrivateKey       = 3,    // [ byte string ] Manufacturer-assigned device key
+    kTag_PairingCode            = 4,    // [ utf-8 string ] Pairing code
+    kTag_ProductRev             = 5,    // [ uint, 16-bit max ] Product revision
+    kTag_MfgDate                = 6     // [ utf-8 string ] Manufacturing date
+};
+
+/**
+ * Marker used to mark the location of device provisioning data in memory.
+ */
+const char kMarker[] = "^OW-PROV-DATA^";
+constexpr size_t kMarkerLen = sizeof(kMarker) - 1;
+
+} // namespace FactoryProvisioningData
+
+
+
+} // namespace Internal
+} // namespace DeviceLayer
+} // namespace Weave
+} // namespace nl
+
+#endif // FACTORY_PROVISIONING_H