When a key must be sent to any user, only the salt that was used by the administrator is actually sent to the user. The salt may be encrypted with a pre-shared symmetric key (like the example above) and it is used by every user along with the shared secret to generate again the key.
Versions of the Microsoft Rights Management Service SDK released prior to March 2020 are deprecated; applications using earlier versions must be updated to use the March 2020 release. For full details, see the deprecation notice.
No further enhancements are planned for the Microsoft Rights Management Service SDK. We strongly recommend adoption of the Microsoft Information Protection SDK for classification, labeling, and protection services.
This topic outlines steps for setting up your service application to use Azure Rights Management. For more information, see Getting started with Azure Rights Management.
In order to use your Rights Management Services SDK 2.1 service application with Azure RMS, you'll need to create your own tenants. For more information, see Azure RMS requirements: Cloud subscriptions that support Azure RMS
- RMS SDK 2.1 must be installed and configured. For more information, see Getting started with RMS SDK 2.1.
- You must create a service identity via ACS by using the symmetric key option, or through other means, and record the key information from that process.
Connecting to the Azure Rights Management Service
Note For more information, see Setting the API security mode
- The following steps are the setup for creating an instance of an IPC_PROMPT_CTX structure with the pcCredential (IPC_CREDENTIAL) member populated with connection information from the Azure Rights Management Service.
- Use the information from your symmetric key service identity creation (see the prerequisites listed earlier in this topic) to set the wszServicePrincipal, wszBposTenantId, and cbKey parameters when you create an instance of an IPC_CREDENTIAL_SYMMETRIC_KEY structure.
Note - Due to an existing condition with our discovery service, if you are not in North America, symmetric key credentials are not accepted from other regions therefore, you must specify your tenant URLs directly. This is done through the pConnectionInfo parameter, type IPC_CONNECTION_INFO, on functions IpcGetTemplateList or IpcGetTemplateIssuerList.
Generate a symmetric key and collect the needed information
Instructions to generate a symmetric key
- Install Microsoft Online Sign-in Assistant
- Install Azure AD Powershell Module.
Note - You must be a tenant administrator to use the Powershell cmdlets.
Start Powershell and run the following commands to generate a key
Connect-MsolService(type-in your admin credentials)
New-MsolServicePrincipal(type-in a display name)
After it generates a symmetric key, it will output information about the key including the key itself and an AppPrincipalId.
Instructions to find out TenantBposId and Urls
Install Azure RMS powershell module.
Start Powershell and run the following commands to get the RMS configuration of the tenant.
Connect-AipService(type-in your admin credentials)
Create an instance of an IPC_CREDENTIAL_SYMMETRIC_KEY and set a few members.
For more information see, IPC_CREDENTIAL_SYMMETRIC_KEY.
- Create an instance of an IPC_CREDENTIAL structure containing your IPC_CREDENTIAL_SYMMETRIC_KEY instance.
Note - The connectionInfo members are set with URLs from the previous call to
Get-AipServiceConfiguration and noted here with those field names.
Identify a template and then encrypt
- Select a template to use for your encryption.Call IpcGetTemplateList passing in the same instance of IPC_PROMPT_CTX.
- With the template from earlier in this topic, call IpcfEncrcyptFile, passing in the same instance of IPC_PROMPT_CTX.
Example use of IpcfEncrcyptFile:
Example use of IpcfDecryptFile:
You have now completed the steps needed to enable your application to use Azure Rights Management.
A common problem with many legacy devices is that they often have an identity that is composed of a single piece of information. This identity information is usually a MAC address or a serial number. Legacy devices may not have a certificate, TPM, or any other security feature that can be used to securely identify the device. The Device Provisioning Service for IoT hub includes symmetric key attestation. Symmetric key attestation can be used to identify a device based off information like the MAC address or a serial number.
If you can easily install a hardware security module (HSM) and a certificate, then that may be a better approach for identifying and provisioning your devices. Since that approach may allow you to bypass updating the code deployed to all your devices, and you would not have a secret key embedded in your device image.
This article assumes that neither an HSM or a certificate is a viable option. However, it is assumed that you do have some method of updating device code to use the Device Provisioning Service to provision these devices.
This article also assumes that the device update takes place in a secure environment to prevent unauthorized access to the master group key or the derived device key.
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 sample used in this article is written in C. There is also a C# device provisioning symmetric key sample available. To use this sample, download or clone the azure-iot-samples-csharp repository and follow the in-line instructions in the sample code. You can follow the instructions in this article to create a symmetric key enrollment group using the portal and to find the ID Scope and enrollment group primary and secondary keys needed to run the sample. You can also create individual enrollments using the sample.
A unique registration ID will be defined for each device based on information that identifies that device. For example, the MAC address or a serial number.
An enrollment group that uses symmetric key attestation will be created with the Device Provisioning Service. The enrollment group will include a group master key. That master key will be used to hash each unique registration ID to produce a unique device key for each device. The device will use that derived device key with its unique registration ID to attest with the Device Provisioning Service and be assigned to an IoT hub.
The device code demonstrated in this article will follow the same pattern as the Quickstart: Provision a simulated device with symmetric keys. The code will simulate a device using a sample from the Azure IoT C SDK. The simulated device will attest with an enrollment group instead of an individual enrollment as demonstrated in the quickstart.
If you don't have an Azure subscription, create a free account before you begin.
- Completion of the Set up IoT Hub Device Provisioning Service with the Azure portal quickstart.
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.
Symmetric Key Generate Callable Service Definition
Visual Studio 2019 with the 'Desktop development with C++' workload enabled. Visual Studio 2015 and Visual Studio 2017 are also supported.
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 sample code for the simulated device. This simulated device will 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.
Find the tag name for the latest release of the 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
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
Run the following command, which builds a version of the SDK specific to your development client platform. A Visual Studio solution for the simulated device will be generated in the
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:
Create a symmetric key enrollment group
Sign in to the Azure portal, and open your Device Provisioning Service instance.
Select the Manage enrollments tab, and then click the Add enrollment group button at the top of the page.
On Add Enrollment Group, enter the following information, and click the Save button.
Group name: Enter mylegacydevices.
Attestation Type: Select Symmetric Key.
Auto Generate Keys: Check this box.
Select how you want to assign devices to hubs: Select Static configuration so you can assign to a specific hub.
Select the IoT hubs this group can be assigned to: Select one of your hubs.
Once you saved your enrollment, the Primary Key and Secondary Key will be generated and added to the enrollment entry. Your symmetric key enrollment group appears as mylegacydevices under the Group Name column in the Enrollment Groups tab.
Open the enrollment and copy the value of your generated Primary Key. This key is your master group key.
Choose a unique registration ID for the device
A unique registration ID must be defined to identify each device. You can use the MAC address, serial number, or any unique information from the device.
In this example, we use a combination of a MAC address and serial number forming the following string for a registration ID.
Create a unique registration ID for your device. Valid characters are lowercase alphanumeric and dash ('-').
Derive a device key
To generate the device key, use the group master key to compute an HMAC-SHA256 of the unique registration ID for the device and convert the result into Base64 format.
Do not include your group master key in your device code.
If you are using a Linux workstation, you can use openssl to generate yourderived device key as shown in the following example.
Replace the value of KEY with the Primary Key you noted earlier.
Replace the value of REG_ID with your registration ID.
If you are using a Windows-based workstation, you can use PowerShell to generate your derived device key as shown in the following example.
Replace the value of KEY with the Primary Key you noted earlier.
Replace the value of REG_ID with your registration ID.
Your device will use the derived device key with your unique registration ID to perform symmetric key attestation with the enrollment group during provisioning.
Create a device image to provision
In this section, you will update a provisioning sample named prov_dev_client_sample located in the Azure IoT C SDK you set up earlier.
This sample code simulates a device boot sequence that sends the provisioning request to your Device Provisioning Service instance. The boot sequence will cause the device to be recognized and assigned to the IoT hub you configured on the enrollment group.
In the Azure portal, select the Overview tab for your Device Provisioning service and note down the ID Scope value.
In Visual Studio, open the azure_iot_sdks.sln solution file that was generated by running CMake earlier. The solution file should be in the following location:
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.
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:
Find the call to
prov_dev_set_symmetric_key_info()in prov_dev_client_sample.c which is commented out.
Uncomment the function call, and replace the placeholder values (including the angle brackets) with the unique registration ID for your device and the derived device key you generated.
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 prompt to rebuild the project, click Yes, to rebuild the project before running.
The following output is an example of the simulated device successfully booting up, and connecting to the provisioning Service instance to be assigned to an IoT hub:
In the portal, navigate to the IoT hub your simulated device was assigned to and click the IoT Devices tab. On successful provisioning of the simulated to the hub, its device ID appears on the IoT Devices blade, with STATUS as enabled. You might need to click the Refresh button at the top.
Be aware that this leaves the derived device key included as part of the image, which is not a recommended security best practice. This is one reason why security and ease-of-use are tradeoffs.
Free Key Generate Software
- To learn more Reprovisioning, see IoT Hub Device reprovisioning concepts
- To learn more Deprovisioning, see How to deprovision devices that were previously auto-provisioned