Quickstart: Provision a device with symmetric keys
In this quickstart, you will learn how to run device provisioning code on a Windows development machine to connect it to an IoT Hub as an IoT device. You will configure this device to use a symmetric key authentication with a Device Provisioning Service instance and be assigned to an IoT hub. Sample code from the Azure IoT C SDK will be used to provision the device. The device will be recognized based on an individual enrollment with a provisioning service instance and assigned to an IoT hub.
Although this article demonstrates provisioning with an individual enrollment, you can use enrollment groups. There are some differences when using enrollment groups. For example, you must use a derived device key with a unique registration ID for the device. Although symmetric key enrollment groups are not limited to legacy devices, How to provision legacy devices using Symmetric key attestation provides an enrollment group example. For more information, see Group Enrollments for Symmetric Key Attestation.
If you're unfamiliar with the process of autoprovisioning, review the provisioning overview.
Also, make sure you've completed the steps in Set up IoT Hub Device Provisioning Service with the Azure portal before continuing with this quickstart. This quickstart requires you to have already created your Device Provisioning Service instance.
This article is oriented toward a Windows-based workstation. However, you can perform the procedures on Linux. For a Linux example, see How to provision for multitenancy.
The following prerequisites are for a Windows development environment. For Linux or macOS, see the appropriate section in Prepare your development environment in the SDK documentation.
Latest version of Git installed.
Prepare an Azure IoT C SDK development environment
In this section, you will prepare a development environment used to build the Azure IoT C SDK.
The SDK includes the provisioning sample code for devices. This code attempt provisioning during the device's boot sequence.
Download the CMake build system.
It is important that the Visual Studio prerequisites (Visual Studio and the 'Desktop development with C++' workload) are installed on your machine, before starting the
CMakeinstallation. Once the prerequisites are in place, and the download is verified, install the CMake build system.
Older versions of the CMake build system fail to generate the solution file used in this article. Make sure to use a newer version of CMake.
Click Tags and find the tag name for the latest release on the Release page of the Azure IoT C SDK.
Open a command prompt or Git Bash shell. Run the following commands to clone the latest release of the Azure IoT C SDK GitHub repository. Use the tag you found in the previous step as the value for the
git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git cd azure-iot-sdk-c git submodule update --init
You should expect this operation to take several minutes to complete.
cmakesubdirectory in the root directory of the git repository, and navigate to that folder. Run the following commands from the
mkdir cmake cd cmake
Run the following command, which builds a version of the SDK specific to your development client platform. A Visual Studio solution for the device provisioning code will be generated in the
cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON ..
cmakedoes not find your C++ compiler, you might get build errors while running the above command. If that happens, try running this command in the Visual Studio command prompt.
Once the build succeeds, the last few output lines will look similar to the following output:
$ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON .. -- Building for: Visual Studio 15 2017 -- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134. -- The C compiler identification is MSVC 19.12.25835.0 -- The CXX compiler identification is MSVC 19.12.25835.0 ... -- Configuring done -- Generating done -- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
Create a device enrollment entry in the portal
Sign in to the Azure portal, select the All resources button on the left-hand menu and open your Device Provisioning service.
Select the Manage enrollments tab, and then select the Add individual enrollment button at the top.
In the Add Enrollment panel, enter the following information, and press the Save button.
Mechanism: Select Symmetric Key as the identity attestation Mechanism.
Auto-generate keys: Check this box.
Registration ID: Enter a registration ID to identify the enrollment. Use only lowercase alphanumeric and dash ('-') characters. For example, symm-key-device-007.
IoT Hub Device ID: Enter a device identifier. For example, device-007.
Once you have saved your enrollment, the Primary Key and Secondary Key will be generated and added to the enrollment entry. Your symmetric key device enrollment appears as symm-key-device-007 under the Registration ID column in the Individual Enrollments tab.
Open the enrollment and copy the value of your generated Primary Key.
Run the provisioning code for the device
In this section, update the sample code to send the device's boot sequence to your Device Provisioning Service instance. This boot sequence will cause the device to be recognized and assigned to an IoT hub linked to the Device Provisioning Service instance.
In the Azure portal, select the Overview tab for your Device Provisioning service and note the ID Scope value.
In Visual Studio, open the azure_iot_sdks.sln solution file that was generated by running CMake. The solution file should be in the following location:
If the file was not generated in your cmake directory, make sure you used a recent version of the CMake build system.
In Visual Studio's Solution Explorer window, navigate to the Provision_Samples folder. Expand the sample project named prov_dev_client_sample. Expand Source Files, and open prov_dev_client_sample.c.
id_scopeconstant, and replace the value with your ID Scope value that you copied earlier.
static const char* id_scope = "0ne00002193";
Find the definition for the
main()function in the same file. Make sure the
hsm_typevariable is set to
SECURE_DEVICE_TYPE_SYMMETRIC_KEYas shown below:
SECURE_DEVICE_TYPE hsm_type; //hsm_type = SECURE_DEVICE_TYPE_TPM; //hsm_type = SECURE_DEVICE_TYPE_X509; hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
Find the call to
prov_dev_set_symmetric_key_info()in prov_dev_client_sample.c that is commented out.
// Set the symmetric key if using they auth type //prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");
Uncomment the function call, and replace the placeholder values (including the angle brackets) with your registration ID and primary key values.
// Set the symmetric key if using they auth type prov_dev_set_symmetric_key_info("symm-key-device-007", "your primary key here");
Save the file.
Right-click the prov_dev_client_sample project and select Set as Startup Project.
On the Visual Studio menu, select Debug > Start without debugging to run the solution. In the rebuild the project prompt, select Yes to rebuild the project before running.
The following output is an example of the device successfully connecting to the provisioning Service instance to be assigned to an IoT hub:
Provisioning API Version: 1.2.8 Registering Device Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING Registration Information received from service: test-docs-hub.azure-devices.net, deviceId: device-007 Press enter key to exit:
In the portal, navigate to the IoT hub your device was assigned to and select the IoT devices tab. On successful provisioning of the device to the hub, its device ID appears on the IoT Devices blade, with STATUS as enabled. You might need to press the Refresh button at the top.
Clean up resources
If you plan to continue working on and exploring the device client sample, do not clean up the resources created in this quickstart. If you do not plan to continue, use the following steps to delete all resources created by this quickstart.
- Close the device client sample output window on your machine.
- From the left-hand menu in the Azure portal, select All resources and then select your Device Provisioning service. Open Manage Enrollments for your service, and then select the Individual Enrollments tab. Select the check box next to the REGISTRATION ID of the device you enrolled in this quickstart, and press the Delete button at the top of the pane.
- From the left-hand menu in the Azure portal, select All resources and then select your IoT hub. Open IoT devices for your hub, select the check box next to the DEVICE ID of the device you registered in this quickstart, and then press the Delete button at the top of the pane.
In this quickstart, you ran device provisioning code on your Windows machine. The device was authenticated and provisioned to your IoT hub using a symmetric key. To learn how to provision an X.509 certificate device, continue to the quickstart for X.509 devices.