Công cụ cấp phép nhà máy OpenWeave

Xem nguồn trên GitHub

Công cụ cấp phép nhà máy OpenWeave cung cấp một phương thức thuận tiện để cấp phép thông tin cấu hình ổn định, theo từng thiết bị cho các thiết bị hỗ trợ Weave. Công cụ cấp phép ban đầu được dùng trong quy trình sản xuất để đóng dấu từng thiết bị bằng thông tin nhận dạng và thông tin xác thực riêng biệt trước khi vận chuyển đến khách hàng. Nhà phát triển cũng có thể sử dụng mô-đun này để cá nhân hoá phần cứng trước khi phát hành công khai được dùng trong quá trình phát triển.

Nguyên lý hoạt động

Mục tiêu của Công cụ cấp phép nhà máy OpenWeave là chèn thông tin cấu hình chọn lọc vào kho lưu trữ cấu hình ổn định của thiết bị. Tại đây, chương trình cơ sở của thiết bị có thể nhận và sử dụng thông tin cấu hình đó trong thời gian chạy. Cấu hình thiết bị ổn định thường được lưu trữ trong bộ nhớ flash nội bộ của thiết bị, mặc dù thông tin chi tiết về cách lưu trữ dữ liệu và định dạng dữ liệu sẽ khác nhau tuỳ theo nền tảng. Bản thân Công cụ cấp phép ban đầu không phụ thuộc vào định dạng bộ nhớ cuối cùng và dựa vào mã trong chương trình cơ sở của thiết bị để ghi dữ liệu đúng cách. Giao diện người dùng của công cụ này cũng phần lớn độc lập với loại phần cứng đang được định cấu hình, nghĩa là các quy trình sản xuất tương tự có thể được áp dụng trên các dòng sản phẩm dựa trên các nền tảng phần cứng khác nhau.

Công cụ cấp phép ban đầu được thiết kế để chạy trên máy chủ lưu trữ được kết nối với thiết bị mục tiêu thông qua một số dạng giao diện gỡ lỗi hoặc điều khiển - ví dụ: cổng JTAG hoặc SWD. Công cụ này hoạt động bằng cách chèn thông tin cấp phép vào RAM của thiết bị ở dạng được mã hoá đặc biệt. Sau đó, thiết bị được hướng dẫn khởi động lại. Tại thời điểm này, mã tích hợp sẵn vào phần mềm của thiết bị sẽ xác định vị trí dữ liệu đã mã hoá, xác thực tính toàn vẹn của dữ liệu đó và ghi các giá trị có trong bộ nhớ cố định theo định dạng phù hợp với nền tảng.

Mã trên thiết bị phát hiện và xử lý dữ liệu cấp phép được chèn được tích hợp sẵn vào Lớp thiết bị OpenWeave và có thể được bật trên mọi nền tảng được hỗ trợ. Sau khi được bật, mã này sẽ tự động chạy mỗi khi thiết bị khởi động, tại một thời điểm ở đầu quá trình khởi chạy thiết bị. Mã này hoạt động bằng cách quét một vùng RAM dành riêng cho nền tảng. Trên các nền tảng có bộ nhớ nhỏ (ví dụ: <1M), quá trình quét sẽ bao gồm tất cả RAM có sẵn.

Khi được đặt vào RAM, dữ liệu cấp phép được mã hoá bằng một tiền tố dễ nhận dạng, cho phép tìm thấy dữ liệu đó nhanh chóng trong quá trình quét. Giá trị kiểm tra tính toàn vẹn dựa trên hàm băm mật mã được dùng để xác nhận tính hợp lệ của dữ liệu trước khi xử lý.

Theo mặc định, công cụ cấp phép sẽ chọn vị trí RAM để chèn dữ liệu cấp phép dựa trên nền tảng thiết bị mục tiêu. Bạn có thể ghi đè lựa chọn này thông qua một đối số cho công cụ. Nhìn chung, không bắt buộc phải đặt firmware của thiết bị dành riêng một vị trí RAM để nhận dữ liệu cấp phép. Thông thường, dữ liệu cấp phép được ghi vào một vị trí RAM được phân bổ cho các mục đích khác, nhưng thường không được sử dụng trong giai đoạn đầu của quy trình khởi động thiết bị. Các lựa chọn phổ biến là phần trên cùng của ngăn xếp hệ thống ban đầu hoặc cuối vùng nhớ khối xếp.

Công cụ cấp phép ban đầu dựa vào một bộ công cụ phát triển bên ngoài để giao tiếp với thiết bị mục tiêu. Các công cụ cụ thể được sử dụng phụ thuộc vào loại thiết bị mục tiêu. Hiện có hai giao diện thiết bị được hỗ trợ:

• đầu dò gỡ lỗi SEGGER J-Link được kết nối với cổng JTAG hoặc SWD của thiết bị
• một cổng nối tiếp USB kết nối với một ESP32 Espressif

Giao diện J-Link dựa vào công cụ SEGGER J-Link Commander (JLinkExe) và bạn phải cài đặt công cụ này riêng trên máy chủ.

Giao diện ESP32 dựa vào lệnh esptool.py của Espressif, được cung cấp trong SDK ESP-IDF của Espressif.

Các loại thông tin có thể được cấp phép

Công cụ cấp phép nhà máy OpenWeave có thể cung cấp các loại thông tin sau:

• Số sê-ri thiết bị
• Mã thiết bị Weave do nhà sản xuất chỉ định
• Chứng chỉ Weave và khoá riêng tư do nhà sản xuất chỉ định
• Mã ghép nối Weave
• Số bản sửa đổi sản phẩm
• Ngày sản xuất

Mặc dù nói chung, thiết bị sẽ cần tất cả thông tin nêu trên để hoạt động đúng cách, nhưng bạn không bắt buộc phải cung cấp tất cả thông tin cùng một lúc. Do đó, việc cung cấp các loại thông tin có thể diễn ra tại các điểm khác nhau trong quy trình sản xuất. Ngoài ra, bạn có thể thay thế các giá trị đã được cấp trước đó bằng các giá trị mới trong bước cấp tiếp theo.

Nguồn thông tin cấp phép

Bạn có thể cung cấp thông tin cấp phép thiết bị cho Công cụ cấp phép ban đầu theo các cách sau:

• Đối số dòng lệnh
• Sử dụng tệp CSV cấp phép
• Bằng cách tìm nạp các giá trị từ máy chủ cấp phép Nest

Dòng lệnh

Ở dạng đơn giản nhất, thông tin cấp phép thiết bị được chỉ định trực tiếp trên dòng lệnh cho Công cụ cấp phép nhà máy OpenWeave. Ví dụ:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --pairing-code NESTUS --mfg-date 2019/04/01

Bạn có thể chỉ định các giá trị dữ liệu nhị phân, chẳng hạn như chứng chỉ Weave và khoá riêng tư, dưới dạng chuỗi cơ sở 64 hoặc dưới dạng tên của các tệp chứa dữ liệu mong muốn ở dạng thô (nhị phân).

Hãy xem bên dưới để biết danh sách đầy đủ các đối số dòng lệnh có sẵn.

Tệp CSV cấp phép

Để hỗ trợ việc cấp phép hàng loạt thiết bị, Công cụ cấp phép ban đầu cũng có thể đọc dữ liệu cấp phép từ tệp dữ liệu cấp phép có định dạng CSV. Các cột của tệp này dự kiến sẽ tương ứng với các loại dữ liệu cấp phép cụ thể – tức là Serial_Num, Certificate, Private_Key, v.v. Các hàng trong tệp cung cấp các giá trị riêng lẻ cho các thiết bị cụ thể, được lập chỉ mục theo mã thiết bị Weave (Device_Id). Bạn phải chỉ định mã của thiết bị cụ thể cần cấp phép trên dòng lệnh. Ví dụ:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-csv-file ./dev-provisioning-data.csv

Các cột CSV sau đây được hỗ trợ:

Tên	Định dạng	Mô tả
Device_Id	16 chữ số thập lục phân	Mã thiết bị Weave. Phải có.
Serial_Num	chuỗi	Số sê-ri của thiết bị.
Certificate	chuỗi base-64	Chứng chỉ thiết bị Weave do nhà sản xuất chỉ định.
Private_Key	chuỗi base-64	Khoá riêng tư Weave do nhà sản xuất chỉ định.
Pairing_Code	chuỗi	Mã ghép nối Weave.
Product_Rev	số nguyên	Số bản sửa đổi sản phẩm.
Mfg_Date	DD/MM/YYYY	Ngày sản xuất thiết bị.

Các cột có thể xuất hiện trong tệp CSV theo thứ tự bất kỳ. Tất cả các cột đều không bắt buộc, ngoại trừ Device_Id. Đơn giản là mọi giá trị không có trong tệp CSV sẽ không được cấp phép trên thiết bị.

Người dùng có thể chỉ định từng giá trị cấp phép trên dòng lệnh ngoài tệp CSV. Trong trường hợp này, giá trị dòng lệnh sẽ được ưu tiên hơn các giá trị trong tệp.

Định dạng tệp CSV được Công cụ cấp phép ban đầu hỗ trợ tương thích với kết quả của lệnh gen-provisioning-data của công cụ weave.

Máy chủ cấp phép Nest

Công cụ cấp phép ban đầu hỗ trợ tìm nạp một số thông tin cấp phép từ máy chủ cấp phép Nest bằng giao thức dựa trên HTTPS. Bạn có thể dùng giao thức máy chủ cấp phép để tìm nạp chứng chỉ thiết bị Weave do Nhà sản xuất chỉ định, khoá riêng tư tương ứng và mã ghép nối Weave từ máy chủ cấp phép.

Vị trí mạng của máy chủ cấp phép được chỉ định bằng cách cung cấp URL cơ sở trên dòng lệnh của công cụ cấp phép. Thông tin cấp phép mong muốn được chọn bằng cách chỉ định mã thiết bị Weave trên dòng lệnh. Ví dụ:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-server https://192.168.172.2:8000/

Người dùng có thể chỉ định từng giá trị cấp phép trên dòng lệnh ngoài URL máy chủ cấp phép. Trong trường hợp này, các giá trị được cung cấp trên dòng lệnh sẽ có trước các giá trị do máy chủ trả về.

Bật / tắt tính năng hỗ trợ cấp phép ban đầu

Hỗ trợ cấp phát OpenWeave từ nhà máy trong phần mềm cơ sở của thiết bị được kiểm soát bằng tuỳ chọn cấu hình thời gian biên dịch WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING. Tuỳ chọn này được bật theo mặc định. Bạn có thể tắt tính năng này bằng cách ghi đè tuỳ chọn trong tệp WeaveProjectConfig.h của ứng dụng. Ví dụ:

#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0

Nhìn chung, bạn có thể an toàn bật tính năng cấp phép ban đầu trong chương trình cơ sở của thiết bị chính thức miễn là giao diện gỡ lỗi của thiết bị được tắt một cách thích hợp trên thiết bị chính thức. Bạn có thể thực hiện việc này thông qua các phương tiện phần cứng (ví dụ: bằng cách thổi cầu chì trong SoC) hoặc trong phần mềm (ví dụ: qua trình tải khởi động bảo mật giúp chặn quyền truy cập gỡ lỗi trong quá trình khởi động).

Chạy Công cụ cấp phép gốc

Công cụ cấp phép nhà máy OpenWeave hỗ trợ các tuỳ chọn dòng lệnh sau:

Phương thức	Mô tả
--target <string>	Loại thiết bị mục tiêu. Các lựa chọn là: nrf52840, esp32
--load-addr <hex-digits>	Địa chỉ trong bộ nhớ thiết bị mà dữ liệu cấp phép sẽ được ghi.
--verbose, -v	Điều chỉnh mức độ chi tiết của đầu ra. Sử dụng nhiều đối số để tăng độ chi tiết.
--serial-num <string>	Đặt số sê-ri của thiết bị.
--device-id <hex-digits>	Đặt mã thiết bị do nhà sản xuất chỉ định.
--device-cert <base-64> | <file-name>	Đặt chứng chỉ thiết bị Weave do nhà sản xuất chỉ định.
--device-key <base-64> | <file-name>	Đặt khoá riêng tư của thiết bị Weave do nhà sản xuất chỉ định.
--pairing-code <string>	Đặt mã ghép nối thiết bị.
--product-rev <integer>	Đặt bản sửa đổi sản phẩm cho thiết bị.
--mfg-date <YYYY/MM/DD> | today | now	Đặt ngày sản xuất cho thiết bị.
--jlink-cmd <path-name>	Đường dẫn đến lệnh JLink. Giá trị mặc định là "JLinkExe".
--jlink-if SWD | JTAG	Loại giao diện J-Link. Giá trị mặc định là SWD.
--jlink-speed <integer> | thích ứng | tự động	Tốc độ giao diện J-Link.
--jlink-sn <string>	Số sê-ri của đầu dò J-Link.
--esptool-cmd <path-name>	Đường dẫn đến lệnh esptool. Giá trị mặc định là "esptool.py".
--cổng <path-name>	Tên thiết bị cổng COM cho ESP32. Giá trị mặc định là /tty/USB0.
--tốc độ <integer>	Tốc độ truyền của cổng COM. Giá trị mặc định là 115200.
-- vừa-tệp-csv-<file-name>	Đọc dữ liệu cấp phép thiết bị từ tệp CSV cấp phép.
--prov-server <url>	Đọc dữ liệu cấp phép thiết bị từ máy chủ cấp phép.
--disable-server-validation	Khi sử dụng HTTPS, hãy tắt tính năng xác thực chứng chỉ do máy chủ cấp phép cung cấp.

Ví dụ

Lệnh sau đây đặt mã thiết bị, số sê-ri, bản sửa đổi sản phẩm và mã ghép nối thành các giá trị cụ thể. Ngày sản xuất được đặt thành ngày hiện tại. Chứng chỉ thiết bị và khoá riêng tư được đặt để kiểm thử các giá trị được cung cấp trong tệp CSV đi kèm với kho lưu trữ nguồn openweave-core.

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000042 \
    --serial-num JAYS_DEVICE_42 --product-rev 1 --pairing-code NESTUS --mfg-date today \
    --prov-csv-file ~/projects/openweave-core/certs/development/device/test-dev-provisioning-data.csv