title | description | author | ms.author | ms.date | ms.topic | ms.service | services |
---|---|---|---|---|---|---|---|
Verify X.509 CA certificates with Azure IoT Hub Device Provisioning Service |
How to do proof-of-possession for X.509 CA certificates with Azure IoT Hub Device Provisioning Service (DPS) |
kgremban |
kgremban |
06/29/2021 |
conceptual |
iot-dps |
iot-dps |
A verified X.509 Certificate Authority (CA) certificate is a CA certificate that has been uploaded and registered to your provisioning service and has gone through proof-of-possession with the service.
Verified certificates play an important role when using enrollment groups. Verifying certificate ownership provides an additional security layer by ensuring that the uploader of the certificate is in possession of the certificate's private key. Verification prevents a malicious actor sniffing your traffic from extracting an intermediate certificate and using that certificate to create an enrollment group in their own provisioning service, effectively hijacking your devices. By proving ownership of the root or an intermediate certificate in a certificate chain, you're proving that you have permission to generate leaf certificates for the devices that will be registering as a part of that enrollment group. For this reason, the root or intermediate certificate configured in an enrollment group must either be a verified certificate or must roll up to a verified certificate in the certificate chain a device presents when it authenticates with the service. To learn more about X.509 certificate attestation, see X.509 certificates and Controlling device access to the provisioning service with X.509 certificates.
If you are using an intermediate or root CA that you trust and know you have full ownernship of the certificate, you can self-attest that you have verified the certificate.
To add an auto-verified certificate, follow these steps:
-
In the Azure portal, navigate to your provisioning service and open Certificates from the left-hand menu.
-
Click Add to add a new certificate.
-
Enter a friendly display name for your certificate. Browse to the .cer or .pem file that represents the public part of your X.509 certificate. Click Upload.
-
Check the box next to Set certificate status to verified on upload.
-
Click Save.
-
Your certificate is show in the certificate tab with a status Verified.
Proof-of-possession involves the following steps:
- Get a unique verification code generated by the provisioning service for your X.509 CA certificate. You can do this from the Azure portal.
- Create an X.509 verification certificate with the verification code as its subject and sign the certificate with the private key associated with your X.509 CA certificate.
- Upload the signed verification certificate to the service. The service validates the verification certificate using the public portion of the CA certificate to be verified, thus proving that you are in possession of the CA certificate's private key.
To register a CA certificate with your provisioning service and get a verification code that you can use during proof-of-possession, follow these steps.
-
In the Azure portal, navigate to your provisioning service and open Certificates from the left-hand menu.
-
Click Add to add a new certificate.
-
Enter a friendly display name for your certificate. Browse to the .cer or .pem file that represents the public part of your X.509 certificate. Click Upload.
-
Once you get a notification that your certificate is successfully uploaded, click Save.
Your certificate will show in the Certificate Explorer list. Note that the STATUS of this certificate is Unverified.
-
Click on the certificate that you added in the previous step.
-
In Certificate Details, click Generate Verification Code.
-
The provisioning service creates a Verification Code that you can use to validate the certificate ownership. Copy the code to your clipboard.
Now, you need to sign the Verification Code with the private key associated with your X.509 CA certificate, which generates a signature. This is known as Proof of possession and results in a signed verification certificate.
Microsoft provides tools and samples that can help you create a signed verification certificate:
- The Azure IoT Hub C SDK provides PowerShell (Windows) and Bash (Linux) scripts to help you create CA and leaf certificates for development and to perform proof-of-possession using a verification code. You can download the files relevant to your system to a working folder and follow the instructions in the Managing CA certificates readme to perform proof-of-possession on a CA certificate.
- The Azure IoT Hub C# SDK contains the Group Certificate Verification Sample, which you can use to do proof-of-possession.
Important
In addition to performing proof-of-possession, the PowerShell and Bash scripts cited previously also allow you to create root certificates, intermediate certificates, and leaf certificates that can be used to authenticate and provision devices. These certificates should be used for development only. They should never be used in a production environment.
The PowerShell and Bash scripts provided in the documentation and SDKs rely on OpenSSL. You may also use OpenSSL or other third-party tools to help you do proof-of-possession. For an example using tooling provided with the SDKs, see Create an X.509 certificate chain.
-
Upload the resulting signature as a verification certificate to your provisioning service in the portal. In Certificate Details on the Azure portal, use the File Explorer icon next to the Verification Certificate .pem or .cer file field to upload the signed verification certificate from your system.
-
Once the certificate is successfully uploaded, click Verify. The STATUS of your certificate changes to Verified in the Certificate Explorer list. Click Refresh if it does not update automatically.
- To learn about how to use the portal to create an enrollment group, see Managing device enrollments with Azure portal.
- To learn about how to use the service SDKs to create an enrollment group, see Managing device enrollments with service SDKs.