Symmetric key attestation

This article describes the identity attestation process when using symmetric keys with the Device Provisioning Service. Symmetric key attestation is a simple approach to authenticating a device with a Device Provisioning Service instance. This attestation method represents a "Hello world" experience for developers who are new to device provisioning, or don't have strict security requirements. Device attestation using an X.509 certificate is more secure, and should be used for more stringent security requirements.

Symmetric key enrollments also provide a way for legacy devices with limited security functionality to bootstrap to the cloud via Azure IoT.

Symmetric key creation

By default, the Device Provisioning Service creates new symmetric keys with a length of 64 bytes when new enrollments are created with the Generate symmetric keys automatically option enabled.

You can also provide your own symmetric keys for enrollments by disabling this option. Symmetric keys must be in Base 64 format and have a key length between 16 bytes and 64 bytes.

Detailed attestation process

Symmetric key attestation with the Device Provisioning Service is performed using the same security tokens supported by IoT hubs to identify devices. These security tokens are Shared Access Signature (SAS) tokens.

SAS tokens have a hashed signature that is created using the symmetric key. The Device Provisioning Service recreates the signature to verify whether or not a security token presented during attestation is authentic.

SAS tokens have the following form:

SharedAccessSignature sig={signature}&se={expiry}&skn={policyName}&sr={URL-encoded-resourceURI}

Here are the components of each token:

For code examples that create a SAS token, see SAS tokens.

Individual enrollments with symmetric keys

When a device is attesting with an individual enrollment, the device uses the symmetric key defined in the individual enrollment entry to create the hashed signature for the SAS token.

Group enrollments with symmetric keys

Unlike an individual enrollment, the symmetric key of an enrollment group isn't used directly by devices when they provision. Instead, devices that provision through an enrollment group do so using a derived device key. The derived device key is a hash of the device's registration ID and is computed using the symmetric key of the enrollment group. The device can then use its derived device key to sign the SAS token it uses to register with DPS. Because the device sends its registration ID when it registers, DPS can use the enrollment group symmetric key to regenerate the device's derived device key and verify the signature on the SAS token.

First, a unique registration ID is defined for each device authenticating through an enrollment group. The registration ID is a case-insensitive string (up to 128 characters long) of alphanumeric characters plus valid special characters: - . _ :. The last character must be alphanumeric or dash ('-'). The registration ID should be something unique that identifies the device. For example, a MAC address or serial number available to uniquely identify a device. In that case, a registration ID can be composed of the MAC address and serial number similar to the following:

sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6

This exact example is used in the How to provision legacy devices using symmetric keys article.

Once a registration ID has been defined for the device, the symmetric key for the enrollment group is used to compute an HMAC-SHA256 hash of the registration ID to produce a derived device key. Some example approaches to computing the derived device key are given in the tabs below.

az iot dps enrollment-group compute-device-key --key 8isrFI1sGsIlvvFSSFRiMfCNzv21fjbE/+ah/lSh3lF8e2YG1Te7w1KpZhJFFXJrqYKi9yegxkqIChbqOS9Egw== --registration-id sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6

"Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc="

$KEY='8isrFI1sGsIlvvFSSFRiMfCNzv21fjbE/+ah/lSh3lF8e2YG1Te7w1KpZhJFFXJrqYKi9yegxkqIChbqOS9Egw=='
$REG_ID='sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6'

$hmacsha256 = New-Object System.Security.Cryptography.HMACSHA256
$hmacsha256.key = [Convert]::FromBase64String($KEY)
$sig = $hmacsha256.ComputeHash([Text.Encoding]::ASCII.GetBytes($REG_ID))
$derivedkey = [Convert]::ToBase64String($sig)
echo "`n$derivedkey`n"

Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=

KEY=8isrFI1sGsIlvvFSSFRiMfCNzv21fjbE/+ah/lSh3lF8e2YG1Te7w1KpZhJFFXJrqYKi9yegxkqIChbqOS9Egw==
REG_ID=sn-007-888-abc-mac-a1-b2-c3-d4-e5-f6

keybytes=$(echo $KEY | base64 --decode | xxd -p -u -c 1000)
echo -n $REG_ID | openssl sha256 -mac HMAC -macopt hexkey:$keybytes -binary | base64

Jsm0lyGpjaVYVP2g3FnmnmG9dI/9qU24wNoykUmermc=

using System; 
using System.Security.Cryptography; 
using System.Text;  

public static class Utils 
{ 
    public static string ComputeDerivedSymmetricKey(byte[] masterKey, string registrationId) 
    { 
        using (var hmac = new HMACSHA256(masterKey)) 
        { 
            return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(registrationId))); 
        } 
    } 
} 

String deviceKey = Utils.ComputeDerivedSymmetricKey(Convert.FromBase64String(masterKey), registrationId);

The resulting device key is then used to generate a SAS token to be used for attestation. Each device in an enrollment group is required to attest using a security token generated from a unique derived key. The enrollment group symmetric key can't be used directly for attestation.

Install the derived device key

Ideally, device keys are derived and installed in the factory. This method guarantees that the group key is never included in any software deployed to the device. When the device is assigned a MAC address or serial number, the key can be derived and injected into the device however the manufacturer chooses to store it.

Consider the following diagram that shows a table of device keys generated in a factory by hashing each device registration ID with the group enrollment key (K).

The identity of each device is represented by the registration ID and derived device key that is installed at the factory. The device key is never copied to another location and the group key is never stored on a device.

Next steps

Now that you have an understanding of symmetric key attestation, check out the following articles to learn more:

• Understand custom allocation policies for assigning devices to IoT hubs
• Device reprovisioning concepts
• Roles and operations in the provisioning process