Merge pull request #229172 from kgremban/mar1-hubdisabledevices

Document disabling devices as a workaround for checking CRLs

Author: JamesJBarnett

articles/iot-hub/iot-hub-create-through-portal.md

@@ -1,5 +1,5 @@
 ---
-title: Use the Azure portal to create an IoT Hub | Microsoft Docs
+title: Use the Azure portal to create an IoT Hub
 description: How to create, manage, and delete Azure IoT hubs through the Azure portal. Includes information about pricing tiers, scaling, security, and messaging configuration.
 author: kgremban
 ms.service: iot-hub
@@ -26,7 +26,7 @@ You can change the settings of an existing IoT hub after it's created from the I
 
 **Pricing and scale**: Migrate to a different tier or set the number of IoT Hub units.
 
-**IP Filter**: Specify a range of IP addresses that will be accepted or rejected by the IoT hub.
+**IP Filter**: Specify a range of IP addresses for the IoT hub to accept or reject.
 
 **Properties**: A list of properties that you can copy and use elsewhere, such as the resource ID, resource group, location, and so on.
 
@@ -54,6 +54,28 @@ For more detailed information about the access granted by specific permissions,
 
 [!INCLUDE [iot-hub-include-create-device](../../includes/iot-hub-include-create-device.md)]
 
+## Disable or delete a device in an IoT hub
+
+If you want to keep a device in your IoT hub's identity registry, but want to prevent it from connecting then you can change its status to *disabled.*
+
+1. In the [Azure portal](https://portal.azure.com), navigate to your IoT hub.
+
+1. Select **Devices** from the navigation menu.
+
+1. Select the name of the device that you want to disable to view its device details page.
+
+1. On the device details page, set the **Enable connection to IoT Hub** parameter to **Disable**.
+
+   :::image type="content" source="./media/iot-hub-create-through-portal/disable-device.png" alt-text="Screenshot that shows disabling a device connection.":::
+
+If you want to remove a device from your IoT hub's identity registry, you can delete its registration.
+
+1. From the **Devices** page of your IoT hub, select the checkbox next to the device that you want to delete.
+
+1. Select **Delete** to remove the device registration.
+
+   :::image type="content" source="./media/iot-hub-create-through-portal/delete-device.png" alt-text="Screenshot that shows deleting a device."::: 
+
 ## Delete an IoT hub
 
 To delete an IoT hub, open your IoT hub in the Azure portal, then choose **Delete**.

articles/iot-hub/iot-hub-devguide-identity-registry.md

@@ -58,8 +58,13 @@ You can disable devices by updating the **status** property of an identity in th
 
 * If you think a device is compromised or has become unauthorized for any reason.
 
+   >[!IMPORTANT]
+   >IoT Hub doesn't check certificate revocation lists when authenticating devices with certificate-based authentication. If you have a device that needs to be blocked from connecting to IoT Hub because of a potentially compromised certificate, you should disable the device in the identity registry.
+
 This feature isn't available for modules.
 
+For more information, see [Disable or delete a device in an IoT hub](./iot-hub-create-through-portal.md#disable-or-delete-a-device-in-an-iot-hub).
+
 ## Import and export device identities
 
 Use asynchronous operations on the [IoT Hub resource provider endpoint](iot-hub-devguide-endpoints.md) to export device identities in bulk from an IoT hub's identity registry. Exports are long-running jobs that use a customer-supplied blob container to save device identity data read from the identity registry.
@@ -72,13 +77,13 @@ Device identities can also be exported and imported from an IoT Hub via the Serv
 
 ## Device provisioning
 
-The device data that a given IoT solution stores depends on the specific requirements of that solution. But, as a minimum, a solution must store device identities and authentication keys. Azure IoT Hub includes an identity registry that can store values for each device such as IDs, authentication keys, and status codes. A solution can use other Azure services such as Table storage, Blob storage, or Azure Cosmos DB to store any additional device data.
+The device data that a given IoT solution stores depends on the specific requirements of that solution. But, as a minimum, a solution must store device identities and authentication keys. Azure IoT Hub includes an identity registry that can store values for each device such as IDs, authentication keys, and status codes. A solution can use other Azure services such as Table storage, Blob storage, or Azure Cosmos DB to store other device data.
 
 *Device provisioning* is the process of adding the initial device data to the stores in your solution. To enable a new device to connect to your hub, you must add a device ID and keys to the IoT Hub identity registry. As part of the provisioning process, you might need to initialize device-specific data in other solution stores. You can also use the Azure IoT Hub Device Provisioning Service to enable zero-touch, just-in-time provisioning to one or more IoT hubs without requiring human intervention. To learn more, see the [provisioning service documentation](../iot-dps/index.yml).
 
 ## Device and module lifecycle notifications
 
-IoT Hub can notify your IoT solution when a device identity is created or deleted by sending lifecycle notifications. To do so, your IoT solution needs to create a route and set the data source equal to *DeviceLifecycleEvents*. By default, no lifecycle notifications are sent, that is, no such routes pre-exist. By creating a route with Data Source equal to *DeviceLifecycleEvents*, lifecycle events will be sent for both device identities and module identities; however, the message contents will differ depending on whether the events are generated for module identities or device identities.  It should be noted that for IoT Edge modules, the module identity creation flow is different than for other modules, as a result for IoT Edge modules the create notification is only sent if the corresponding IoT Edge Device for the updated IoT Edge module identity is running. For all other modules, lifecycle notifications are sent whenever the module identity is updated on the IoT Hub side.  To learn more about the properties and body returned in the notification message, see  [Non-telemetry event schemas](iot-hub-non-telemetry-event-schema.md).
+IoT Hub can notify your IoT solution when a device identity is created or deleted by sending lifecycle notifications. To do so, your IoT solution needs to create a route and set the data source equal to *DeviceLifecycleEvents*. By default, no lifecycle notifications are sent, that is, no such routes pre-exist. By creating a route with Data Source equal to *DeviceLifecycleEvents*, lifecycle events are sent for both device identities and module identities; however, the message contents differ depending on whether the events are generated for module identities or device identities.  It should be noted that for IoT Edge modules, the module identity creation flow is different than for other modules, as a result for IoT Edge modules the create notification is only sent if the corresponding IoT Edge Device for the updated IoT Edge module identity is running. For all other modules, lifecycle notifications are sent whenever the module identity is updated on the IoT Hub side.  To learn more about the properties and body returned in the notification message, see  [Non-telemetry event schemas](iot-hub-non-telemetry-event-schema.md).
 
 ## Device identity properties
 
@@ -96,7 +101,7 @@ Device identities are represented as JSON documents with the following propertie
 | status |required |An access indicator. Can be **Enabled** or **Disabled**. If **Enabled**, the device is allowed to connect. If **Disabled**, this device can't access any device-facing endpoint. |
 | statusReason |optional |A 128 character-long string that stores the reason for the device identity status. All UTF-8 characters are allowed. |
 | statusUpdateTime |read-only |A temporal indicator, showing the date and time of the last status update. |
-| connectionState |read-only |A field indicating connection status: either **Connected** or **Disconnected**. This field represents the IoT Hub view of the device connection status. **Important**: This field should be used only for development/debugging purposes. The connection state is updated only for devices using MQTT or AMQP. Also, it's based on protocol-level pings (MQTT pings, or AMQP pings), and it can have a maximum delay of only 5 minutes. For these reasons, there can be false positives, such as devices reported as connected but that are disconnected. |
+| connectionState |read-only |A field indicating connection status: either **Connected** or **Disconnected**. This field represents the IoT Hub view of the device connection status. **Important**: This field should be used only for development/debugging purposes. The connection state is updated only for devices using MQTT or AMQP. Also, it's based on protocol-level pings (MQTT pings, or AMQP pings), and it can have a maximum delay of only 5 minutes. For these reasons, there can be false positives, such as disconnected devices reported as connected. |
 | connectionStateUpdatedTime |read-only |A temporal indicator, showing the date and last time the connection state was updated. |
 | lastActivityTime |read-only |A temporal indicator, showing the date and last time the device connected, received, or sent a message. This property is eventually consistent, but could be delayed up to 5 to 10 minutes. For this reason, it shouldn't be used in production scenarios. |
 
@@ -119,7 +124,7 @@ Module identities are represented as JSON documents with the following propertie
 | authentication |optional |A composite object containing authentication information and security materials. For more information, see [Authentication Mechanism](/rest/api/iothub/service/modules/get-identity#authenticationmechanism) in the REST API documentation. |
 | managedBy | optional | Identifies who manages this module. For instance, this value is "IoT Edge" if the edge runtime owns this module. |
 | cloudToDeviceMessageCount | read-only | The number of cloud-to-module messages currently queued to be sent to the module. |
-| connectionState |read-only |A field indicating connection status: either **Connected** or **Disconnected**. This field represents the IoT Hub view of the device connection status. **Important**: This field should be used only for development/debugging purposes. The connection state is updated only for devices using MQTT or AMQP. Also, it's based on protocol-level pings (MQTT pings, or AMQP pings), and it can have a maximum delay of only 5 minutes. For these reasons, there can be false positives, such as devices reported as connected but that are disconnected. |
+| connectionState |read-only |A field indicating connection status: either **Connected** or **Disconnected**. This field represents the IoT Hub view of the device connection status. **Important**: This field should be used only for development/debugging purposes. The connection state is updated only for devices using MQTT or AMQP. Also, it's based on protocol-level pings (MQTT pings, or AMQP pings), and it can have a maximum delay of only 5 minutes. For these reasons, there can be false positives, such as disconnected devices reported as connected. |
 | connectionStateUpdatedTime |read-only |A temporal indicator, showing the date and last time the connection state was updated. |
 | lastActivityTime |read-only |A temporal indicator, showing the date and last time the device connected, received, or sent a message. |
 
@@ -152,10 +157,6 @@ Now that you've learned how to use the IoT Hub identity registry, you may be int
 
 * [Schedule jobs on multiple devices](iot-hub-devguide-jobs.md)
 
-To try out some of the concepts described in this article, see the following IoT Hub tutorial:
-
-* [Get started with Azure IoT Hub](../iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-csharp)
-
-To explore using the IoT Hub Device Provisioning Service to enable zero-touch, just-in-time provisioning, see: 
+To explore using the IoT Hub Device Provisioning Service to enable zero-touch, just-in-time provisioning, see:
 
 * [Azure IoT Hub Device Provisioning Service](../iot-dps/index.yml)

articles/iot-hub/iot-hub-x509ca-overview.md

@@ -1,5 +1,5 @@
 ---
-title: Overview of Azure IoT Hub X.509 CA security | Microsoft Docs
+title: Overview of Azure IoT Hub X.509 CA security
 description: Overview - how to authenticate devices to IoT Hub using X.509 Certificate Authorities. 
 author: eustacea
 manager: arjmands
@@ -22,43 +22,43 @@ This article describes how to use X.509 certificate authority (CA) certificates
 
 [!INCLUDE [iot-hub-include-x509-ca-signed-support-note](../../includes/iot-hub-include-x509-ca-signed-support-note.md)]
 
-The X.509 CA feature enables device authentication to IoT Hub using a certificate authority (CA). It simplifies the initial device enrollment process as well as supply chain logistics during device manufacturing. If you aren't familiar with X.509 CA certificates, see [Understand how X.509 CA certificates are used in the IoT industry](iot-hub-x509ca-concept.md) for more information.
+The X.509 CA feature enables device authentication to IoT Hub using a certificate authority (CA). It simplifies the initial device enrollment process and supply chain logistics during device manufacturing. If you aren't familiar with X.509 CA certificates, see [Understand how X.509 CA certificates are used in the IoT industry](iot-hub-x509ca-concept.md) for more information.
 
 ## Get an X.509 CA certificate
 
 The X.509 CA certificate is at the top of the chain of certificates for each of your devices.  You may purchase or create one depending on how you intend to use it.
 
-For production environments, we recommend that you purchase an X.509 CA certificate from a public root certificate authority. Purchasing a CA certificate has the benefit of the root CA acting as a trusted third party to vouch for the legitimacy of your devices. Consider this option if your devices are part of an open IoT network where they will interact with third-party products or services.
+For production environments, we recommend that you purchase an X.509 CA certificate from a public root certificate authority. Purchasing a CA certificate has the benefit of the root CA acting as a trusted third party to vouch for the legitimacy of your devices. Consider this option if your devices are part of an open IoT network where they interact with third-party products or services.
 
 You may also create a self-signed X.509 CA for experimentation or for use in closed IoT networks.
 
-Regardless of how you obtain your X.509 CA certificate, make sure to keep its corresponding private key secret and protected at all times. This is necessary for building trust in the X.509 CA authentication.
+Regardless of how you obtain your X.509 CA certificate, make sure to keep its corresponding private key secret and protected always. This precaution is necessary for building trust in the X.509 CA authentication.
 
 Learn how to [create a self-signed CA certificate](https://github.com/Azure/azure-iot-sdk-c/blob/master/tools/CACertificates/CACertificateOverview.md), which you can use for testing.
 
 ## Sign devices into the certificate chain of trust
 
 The owner of an X.509 CA certificate can cryptographically sign an intermediate CA that can in turn sign another intermediate CA, and so on, until the last intermediate CA terminates this process by signing a device certificate. The result is a cascaded chain of certificates known as a *certificate chain of trust*. In real life this plays out as delegation of trust towards signing devices. This delegation is important because it establishes a cryptographically variable chain of custody and avoids sharing of signing keys.
 
-![img-generic-cert-chain-of-trust](./media/generic-cert-chain-of-trust.png)
+![Diagram that shows the certificates in a chain of trust.](./media/generic-cert-chain-of-trust.png)
 
 The device certificate (also called a leaf certificate) must have the *subject name* set to the **device ID** (`CN=deviceId`) that was used when registering the IoT device in Azure IoT Hub. This setting is required for authentication.
 
 Learn how to [create a certificate chain](https://github.com/Azure/azure-iot-sdk-c/blob/master/tools/CACertificates/CACertificateOverview.md) as done when signing devices.
 
 ## Register the X.509 CA certificate to IoT Hub
 
-Register your X.509 CA certificate to IoT Hub where it will be used to authenticate your devices during registration and connection.  Registering the X.509 CA certificate is a two-step process that includes uploading the certificate file and then establishing proof of possession.
+Register your X.509 CA certificate to IoT Hub, which uses it to authenticate your devices during registration and connection.  Registering the X.509 CA certificate is a two-step process that includes uploading the certificate file and then establishing proof of possession.
 
 The upload process entails uploading a file that contains your certificate.  This file should never contain any private keys.
 
-The proof of possession step involves a cryptographic challenge and response process between you and IoT Hub.  Given that digital certificate contents are public and therefore susceptible to eavesdropping, IoT Hub has to verify that you really own the CA certificate.  It does so by generating a random challenge that you sign with the CA certificate's corresponding private key.  If you kept the private key secret and protected as recommended, then only you will possess the knowledge to complete this step. Secrecy of private keys is the source of trust in this method.  After signing the challenge, you complete this step by uploading a file containing the results.
+The proof of possession step involves a cryptographic challenge and response process between you and IoT Hub.  Given that digital certificate contents are public and therefore susceptible to eavesdropping, IoT Hub has to verify that you really own the CA certificate.  It does so by generating a random challenge that you sign with the CA certificate's corresponding private key.  If you kept the private key secret and protected as recommended, then only you possess the knowledge to complete this step. Secrecy of private keys is the source of trust in this method.  After signing the challenge, you complete this step by uploading a file containing the results.
 
 Learn how to [register your CA certificate](./tutorial-x509-prove-possession.md)
 
 ## Create a device on IoT Hub
 
-To prevent device impersonation, IoT Hub requires that you let it know what devices to expect.  You do this by creating a device entry in the IoT hub's device registry.  This process is automated when using [IoT Hub Device Provisioning Service](../iot-dps/about-iot-dps.md).
+To prevent device impersonation, IoT Hub requires that you let it know what devices to expect. You do this by creating a device entry in the IoT hub's device registry. This process is automated when using [IoT Hub Device Provisioning Service](../iot-dps/about-iot-dps.md).
 
 Learn how to [manually create a device in IoT Hub](./iot-hub-create-through-portal.md#register-a-new-device-in-the-iot-hub).
 
@@ -70,6 +70,10 @@ A successful device connection to IoT Hub completes the authentication process a
 
 Learn how to [complete this device connection step](./tutorial-x509-prove-possession.md).
 
+## Revoke a device certificate
+
+IoT Hub doesn't check certificate revocation lists from the certificate authority when authenticating devices with certificate-based authentication. If you have a device that needs to be blocked from connecting to IoT Hub because of a potentially compromised certificate, you should disable the device in the identity registry. For more information, see [Disable or delete a device in an IoT hub](./iot-hub-create-through-portal.md#disable-or-delete-a-device-in-an-iot-hub).
+
 ## Next Steps
 
 Learn about [the value of X.509 CA authentication](iot-hub-x509ca-concept.md) in IoT.