Add Certificate Management support over Azure IoT Hub

azure-iot-device/azure/iot/device/constant.py

@@ -9,7 +9,7 @@
 VERSION = "2.15.0rc1"
 IOTHUB_IDENTIFIER = "azure-iot-device-iothub-py"
 PROVISIONING_IDENTIFIER = "azure-iot-device-provisioning-py"
-IOTHUB_API_VERSION = "2019-10-01"
+IOTHUB_API_VERSION = "2025-08-01-preview"
 PROVISIONING_API_VERSION = "2025-07-01-preview"
 SECURITY_MESSAGE_INTERFACE_ID = "urn:azureiot:Security:SecurityAgent:1"
 TELEMETRY_MESSAGE_SIZE_LIMIT = 262144

azure-iot-device/azure/iot/device/iothub/abstract_clients.py

@@ -18,6 +18,7 @@
 from azure.iot.device.common.auth import sastoken as st
 from azure.iot.device.iothub import client_event
 from azure.iot.device.iothub.models import Message, MethodRequest, MethodResponse
+from azure.iot.device.iothub.models import CertificateSigningResponse
 from azure.iot.device.common.models import X509
 from azure.iot.device import exceptions
 from azure.iot.device.common import auth, handle_exceptions
@@ -451,6 +452,12 @@ def patch_twin_reported_properties(self, reported_properties_patch: TwinPatch) -
     def receive_twin_desired_properties_patch(self) -> TwinPatch:
         pass
 
+    @abc.abstractmethod
+    def send_certificate_signing_request(
+        self, csr: str, replace: str
+    ) -> CertificateSigningResponse:
+        pass
+
     @property
     def connected(self) -> bool:
         """

azure-iot-device/azure/iot/device/iothub/aio/async_clients.py

@@ -16,7 +16,13 @@
     AbstractIoTHubDeviceClient,
     AbstractIoTHubModuleClient,
 )
-from azure.iot.device.iothub.models import Message, MethodRequest, MethodResponse
+from azure.iot.device.iothub.models import (
+    Message,
+    MethodRequest,
+    MethodResponse,
+    CertificateSigningResponse,
+)
+from azure.iot.device.iothub.models.certificate_signing_request import CertificateSigningRequest
 from azure.iot.device.iothub.pipeline import constant
 from azure.iot.device.iothub.pipeline import exceptions as pipeline_exceptions
 from azure.iot.device import exceptions
@@ -520,6 +526,51 @@ async def receive_twin_desired_properties_patch(self) -> TwinPatch:
         logger.info("twin patch received")
         return patch
 
+    async def send_certificate_signing_request(
+        self, request_id: str, csr: str, replace: str
+    ) -> CertificateSigningResponse:
+        """
+        Sends a Certificate Signing Request to Azure IoT Hub.
+
+        For more information about Certificate Management in Azure IoT, see the documentation:
+        https://learn.microsoft.com/azure/iot-hub/iot-hub-certificate-management-overview
+
+        :param str request_id: The unique identifier for the certificate signing request. Can only contain ASCII alphanumerics and dash. Must be 4 to 32 characters long and not begin or end with a dash.
+        :param str csr: The base64-encoded certificate signing request.
+        :param str replace: Replace any active credential operation for this device.
+        :returns: The certificate issued by Azure IoT Hub for the certificate signing request provided.
+        :rtype: CertificateSigningResponse
+
+        :raises: :class:`azure.iot.device.exceptions.CredentialError` if credentials are invalid
+            and a connection cannot be established.
+        :raises: :class:`azure.iot.device.exceptions.ConnectionFailedError` if a establishing a
+            connection results in failure.
+        :raises: :class:`azure.iot.device.exceptions.ConnectionDroppedError` if connection is lost
+            during execution.
+        :raises: :class:`azure.iot.device.exceptions.OperationTimeout` if connection attempt
+            times out
+        :raises: :class:`azure.iot.device.exceptions.NoConnectionError` if the client is not
+            connected (and there is no auto-connect enabled)
+        :raises: :class:`azure.iot.device.exceptions.ClientError` if there is an unexpected failure
+            during execution.
+        """
+        logger.info("Sending certificate signing request")
+
+        if not self._mqtt_pipeline.feature_enabled[constant.CSR]:
+            await self._enable_feature(constant.CSR)
+
+        request = CertificateSigningRequest(request_id=request_id, csr=csr, replace=replace)
+
+        send_certificate_signing_request_async = async_adapter.emulate_async(
+            self._mqtt_pipeline.send_certificate_signing_request
+        )
+
+        callback = async_adapter.AwaitableCallback(return_arg_name="response")
+        await send_certificate_signing_request_async(request=request, callback=callback)
+        certificate_signing_response = await handle_result(callback)
+        logger.info("Received certificate signing response")
+        return certificate_signing_response
+
 
 class IoTHubDeviceClient(GenericIoTHubClient, AbstractIoTHubDeviceClient):
     """An asynchronous device client that connects to an Azure IoT Hub instance."""

azure-iot-device/azure/iot/device/iothub/models/__init__.py

@@ -5,3 +5,4 @@
 
 from .message import Message  # noqa: F401
 from .methods import MethodRequest, MethodResponse  # noqa: F401
+from .certificate_signing_request import CertificateSigningResponse  # noqa: F401

azure-iot-device/azure/iot/device/iothub/models/certificate_signing_request.py

@@ -0,0 +1,61 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+"""This module contains a class representing messages that are sent or received.
+"""
+
+
+class CertificateSigningRequest(object):
+    """Represents a Certificate Signing Request message to Azure IoT Hub
+
+    :ivar csr: The base64-encoded certificate signing request.
+    :ivar replace: Replace any active credential operation for this device.
+    """
+
+    def __init__(self, request_id, csr, replace):
+        """
+        Initializer for CertificateSigningRequest
+
+        :param str request_id: The unique identifier for the certificate signing request.
+        :param str csr: The base64-encoded certificate signing request.
+        :param str replace: Replace any active credential operation for this device.
+        """
+        if request_id is None:
+            raise ValueError("Certificate Signing Request ID cannot be None.")
+
+        if csr is None:
+            raise ValueError("Certificate Signing Request cannot be None.")
+
+        self.request_id = request_id
+        self.id = None  # The device id, filled internally by the pipeline configuration.
+        self.csr = csr
+        self.replace = replace
+
+    def __str__(self):
+        return str(self.csr)
+
+    # Used for json serialization of CertificateSigningRequest.
+    def to_dict(obj):
+        data = obj.__dict__.copy()
+        data.pop("request_id") # request_id should not be serialized
+        return data
+
+
+class CertificateSigningResponse(object):
+    """Represents a Certificate Signing Response message from Azure IoT Hub
+
+    :ivar status_code: The result code for the certificate signing request.
+    :ivar certificates: An array with the base64-encoded issued certificate chain (leaf, intermediate and root, in this order).
+    """
+
+    def __init__(self, status_code, certificates):
+        """
+        Initializer for CertificateSigningResponse
+
+        :param status_code: The result code for the certificate signing request.
+        :param certificates: An array with the base64-encoded issued certificate chain (leaf, intermediate and root, in this order).
+        """
+        self.status_code = status_code
+        self.certificates = certificates

azure-iot-device/azure/iot/device/iothub/pipeline/constant.py

@@ -8,6 +8,7 @@
 
 # Feature names
 C2D_MSG = "c2d"
+CSR = "csr"
 INPUT_MSG = "input"
 METHODS = "methods"
 TWIN = "twin"

azure-iot-device/azure/iot/device/iothub/pipeline/mqtt_pipeline.py

@@ -34,6 +34,7 @@ def __init__(self, pipeline_configuration):
 
         self.feature_enabled = {
             constant.C2D_MSG: False,
+            constant.CSR: False,
             constant.INPUT_MSG: False,
             constant.METHODS: False,
             constant.TWIN: False,
@@ -82,6 +83,11 @@ def __init__(self, pipeline_configuration):
             #
             .append_stage(pipeline_stages_base.CoordinateRequestAndResponseStage())
             #
+            # CertificateSigningRequestResponseStage needs to be before IoTHubMQTTTranslationStage
+            # because that stage operates on ops that CertificateSigningRequestResponseStage produces
+            #
+            .append_stage(pipeline_stages_iothub.CertificateSigningRequestResponseStage())
+            #
             # IoTHubMQTTTranslationStage comes here because this is the point where we can translate
             # all operations directly into MQTT.  After this stage, only pipeline_stages_base stages
             # are allowed because IoTHubMQTTTranslationStage removes all the IoTHub-ness from the ops
@@ -482,6 +488,45 @@ def on_complete(op, error):
             )
         )
 
+    def send_certificate_signing_request(self, request, callback):
+        """
+        Send a certificate signing request to the service.
+
+        :param request: the certificate signing request to send
+        :param callback: callback which is called when the request attempt is complete.
+
+        :raises: :class:`azure.iot.device.iothub.pipeline.exceptions.PipelineNotRunning` if the
+            pipeline has previously been shut down
+
+        The following exceptions are not "raised", but rather returned via the "error" parameter
+        when invoking "callback":
+
+        :raises: :class:`azure.iot.device.iothub.pipeline.exceptions.NoConnectionError`
+        :raises: :class:`azure.iot.device.iothub.pipeline.exceptions.ProtocolClientError`
+
+        The following exceptions can be returned via the "error" parameter only if auto-connect
+        is enabled in the pipeline configuration:
+
+        :raises: :class:`azure.iot.device.iothub.pipeline.exceptions.ConnectionFailedError`
+        :raises: :class:`azure.iot.device.iothub.pipeline.exceptions.ConnectionDroppedError`
+        :raises: :class:`azure.iot.device.iothub.pipeline.exceptions.UnauthorizedError`
+        :raises: :class:`azure.iot.device.iothub.pipeline.exceptions.OperationTimeout`
+        """
+        self._verify_running()
+        logger.debug("Starting CertificateSigningRequestOperation on the pipeline")
+
+        def on_complete(op, error):
+            if error:
+                callback(error=error, response=None)
+            else:
+                callback(response=op.response)
+
+        self._pipeline.run_op(
+            pipeline_ops_iothub.CertificateSigningRequestOperation(
+                request=request, callback=on_complete
+            )
+        )
+
     # NOTE: Currently, this operation will retry itself indefinitely in the case of timeout
     def enable_feature(self, feature_name, callback):
         """

azure-iot-device/azure/iot/device/iothub/pipeline/mqtt_topic_iothub.py

@@ -90,6 +90,14 @@ def get_twin_patch_topic_for_subscribe():
     return "$iothub/twin/PATCH/properties/desired/#"
 
 
+def get_certificate_signing_response_topic_for_subscribe():
+    """
+    :return: The topic for Certificate Signing Response messages. It is of the format
+    "$iothub/credentials/res/#"
+    """
+    return "$iothub/credentials/res/#"
+
+
 def get_telemetry_topic_for_publish(device_id, module_id):
     """
     return the topic string used to publish telemetry
@@ -123,6 +131,16 @@ def get_twin_topic_for_publish(method, resource_location, request_id):
     )
 
 
+def get_certificate_signing_request_topic_for_publish(request_id):
+    """
+    :return: The topic for Certificate Signing Request messages. It is of the format
+    "$iothub/credentials/POST/issueCertificate/?$rid={request_id}"
+    """
+    return "$iothub/credentials/POST/issueCertificate/?$rid={request_id}".format(
+        request_id=urllib.parse.quote(str(request_id), safe="")
+    )
+
+
 def is_c2d_topic(topic, device_id):
     """
     Topics for c2d message are of the following format:
@@ -165,6 +183,53 @@ def is_method_topic(topic):
     return False
 
 
+def is_certificate_signing_response_topic(topic):
+    """
+    Topics for certificate signing responses are of the following format:
+    "$iothub/credentials/res/{status}/?$rid={request_id}"
+
+    :param str topic: The topic string.
+    """
+    return topic.startswith("$iothub/credentials/res/")
+
+
+def get_certificate_signing_response_request_id_from_topic(topic):
+    """
+    Extract the request id from the certificate signing response topic.
+    Topics for certificate signing responses are of the following format:
+    "$iothub/credentials/res/{status}/?$rid={request_id}"
+
+    :param str topic: The topic string
+    """
+    if is_certificate_signing_response_topic(topic):
+        parts = topic.split("/")
+        if len(parts) == 5:
+            properties = _extract_properties(topic.split("?")[1])
+            return properties["rid"]
+        else:
+            raise ValueError("topic has incorrect format")
+    else:
+        raise ValueError("topic has incorrect format")
+
+
+def get_certificate_signing_response_status_code_from_topic(topic):
+    """
+    Extract the status-code from the certificate signing response topic.
+    Topics for certificate signing responses are of the following format:
+    "$iothub/credentials/res/{status-code}/?$rid={request_id}"
+
+    :param str topic: The topic string
+    """
+    if is_certificate_signing_response_topic(topic):
+        parts = topic.split("/")
+        if len(parts) == 5:
+            return urllib.parse.unquote(parts[3])
+        else:
+            raise ValueError("topic has incorrect format")
+    else:
+        raise ValueError("topic has incorrect format")
+
+
 def is_twin_response_topic(topic):
     """Topics for twin responses are of the following format:
     $iothub/twin/res/{status}/?$rid={rid}

azure-iot-device/azure/iot/device/iothub/pipeline/pipeline_events_iothub.py

@@ -58,3 +58,16 @@ class TwinDesiredPropertiesPatchEvent(PipelineEvent):
     def __init__(self, patch):
         super().__init__()
         self.patch = patch
+
+
+class CertificateSigningResponseEvent(PipelineEvent):
+    """
+    A PipelineEvent object which represents an incoming response for a certificate signing request.  This
+    object is created by a Azure IoT Hub converter stage based on a protocol-specific event.
+    """
+
+    def __init__(self, request_id, status_code, payload):
+        super().__init__()
+        self.request_id = request_id
+        self.status_code = status_code
+        self.payload = payload

azure-iot-device/azure/iot/device/iothub/pipeline/pipeline_ops_iothub.py

@@ -101,3 +101,23 @@ def __init__(self, patch, callback):
         """
         super().__init__(callback=callback)
         self.patch = patch
+
+
+class CertificateSigningRequestOperation(PipelineOperation):
+    """
+    A PipelineOperation object which contains arguments used to send a certificate signing request
+    to the Azure IoT Hub.
+    """
+
+    def __init__(self, request, callback):
+        """
+        Initializer for CertificateSigningRequestOperation object
+
+        :param request: The certificate signing request to send to the service. User-provided.
+        :type request: CertificateSigningRequest
+        :param response: The certificate signing response received by the service. Generated by this SDK.
+        :type response: CertificateSigningResponse
+        """
+        super().__init__(callback=callback)
+        self.request = request
+        self.response = None