Draft, in progress

Author: KennedyDMSFT

articles/iot-hub/.openpublishing.redirection.iot-hub.json

@@ -1265,22 +1265,37 @@
     },
     {
       "source_path_from_root": "/articles/iot-hub/tutorial-x509-certificates.md",
-      "redirect_url": "/azure/iot-hub/reference-x509-certificates",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-ca-certs",
       "redirect_document_id": true
     },
     {
       "source_path_from_root": "/articles/iot-hub/tutorial-x509-introduction.md",
-      "redirect_url": "/azure/iot-hub/tutorial-x509-prove-possession",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-ca-certs",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/articles/iot-hub/tutorial-x509-openssl.md",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-ca-certs",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/articles/iot-hub/tutorial-x509-prove-possession.md",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-ca-certs",
       "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-hub/tutorial-x509-self-sign.md",
-      "redirect_url": "/azure/iot-hub/reference-x509-certificates",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-ca-certs",
       "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/iot-hub/tutorial-x509-scripts.md",
-      "redirect_url": "/azure/iot-hub/tutorial-x509-openssl",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-ca-certs",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/articles/iot-hub/tutorial-x509-test-certificate.md",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-ca-certs",
       "redirect_document_id": false
     },
     {

articles/iot-hub/TOC.yml

@@ -44,15 +44,9 @@
       href: iot-hub-live-data-visualization-in-power-bi.md
     - name: Use X.509 certificates
       items:
-        - name: Use OpenSSL to create test certificates
-          displayName: X.509 certificates, root CA
-          href: tutorial-x509-openssl.md
-        - name: Upload and verify CA certificates
-          displayName: root certification authority (CA), verify certificate, manual verification, verification code, certificate signing request (CSR)
-          href: tutorial-x509-prove-possession.md
-        - name: Test certificate authentication
-          displayName: X.509 certificates
-          href: tutorial-x509-test-certificate.md
+        - name: Create and upload certificates for testing
+          displayName: X.509 certificates, root certificate authority (CA), verify certificate, certificate signing request (CSR)
+          href: tutorial-x509-test-ca-certs.md
 - name: Concepts
   items:
     - name: IoT Hub concepts overview

articles/iot-hub/index.yml

@@ -72,8 +72,8 @@ landingContent:
    linkLists:
    - linkListType: tutorial
      links:
-     - text: Use X.509 certificates to authenticate
-       url: tutorial-x509-prove-possession.md
+     - text: Create and upload certificates for testing
+       url: tutorial-x509-test-ca-certs.md
    - linkListType: concept
      links:
      - text: Security best practices

articles/iot-hub/iot-hub-dev-guide-sas.md

@@ -266,7 +266,7 @@ The result, which would grant access to read all device identities, would be:
 
 ### Supported X.509 certificates
 
-You can use any X.509 certificate to authenticate a device with IoT Hub by uploading either a certificate thumbprint or a certificate authority (CA) to Azure IoT Hub. To learn more, see [Device Authentication using X.509 CA Certificates](iot-hub-x509ca-overview.md). For information about how to upload and verify a certificate authority with your IoT hub, see [Set up X.509 security in your Azure IoT hub](./tutorial-x509-prove-possession.md).
+You can use any X.509 certificate to authenticate a device with IoT Hub by uploading either a certificate thumbprint or a certificate authority (CA) to Azure IoT Hub. To learn more, see [Device Authentication using X.509 CA Certificates](iot-hub-x509ca-overview.md). For information about how to upload and verify a certificate authority with your IoT hub for testing, see [Tutorial: Create and upload certificates for testing](tutorial-x509-test-ca-certs.md).
 
 ### Enforcing X.509 authentication
 

articles/iot-hub/iot-hub-mqtt-support.md

@@ -114,7 +114,7 @@ If a device can't use the device SDKs, it can still connect to the public device
   `SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}`
 
   > [!NOTE]
-  > If you use X.509 certificate authentication, SAS token passwords are not required. For more information, see [Set up X.509 security in your Azure IoT Hub](./tutorial-x509-prove-possession.md) and follow code instructions in the [TLS/SSL configuration section](#tlsssl-configuration).
+  > If you use X.509 certificate authentication, SAS token passwords are not required. For more information, see [Tutorial: Create and upload certificates for testing](tutorial-x509-test-ca-certs.md) and follow code instructions in the [TLS/SSL configuration section](#tlsssl-configuration).
 
   For more information about how to generate SAS tokens, see the [Use SAS tokens as a device](iot-hub-dev-guide-sas.md#use-sas-tokens-as-a-device) section of [Control access to IoT Hub using Shared Access Signatures](iot-hub-dev-guide-sas.md).
 

articles/iot-hub/iot-hub-tls-support.md

@@ -128,7 +128,7 @@ After a successful TLS handshake, IoT Hub can authenticate a device using a symm
 
 ## Mutual TLS support
 
-Mutual TLS authentication ensures that the client _authenticates_ the server (IoT Hub) certificate and the server (IoT Hub) _authenticates_ the [X.509 client certificate or X.509 thumbprint](tutorial-x509-prove-possession.md). _Authorization_ is performed by IoT Hub after _authentication_ is complete.
+Mutual TLS authentication ensures that the client _authenticates_ the server (IoT Hub) certificate and the server (IoT Hub) _authenticates_ the [X.509 client certificate or X.509 thumbprint](tutorial-x509-test-ca-certs.md#create-a-client-certificate-for-a-device). _Authorization_ is performed by IoT Hub after _authentication_ is complete.
 
 For AMQP and MQTT protocols, IoT Hub requests a client certificate in the initial TLS handshake. If one is provided, IoT Hub _authenticates_ the client certificate and the client _authenticates_ the IoT Hub certificate. This process is called mutual TLS authentication. When IoT Hub receives an MQTT connect packet or an AMQP link opens, IoT Hub performs _authorization_ for the requesting client and determines if the client requires X.509 authentication. If mutual TLS authentication was completed and the client is authorized to connect as the device, it is allowed. However, if the client requires X.509 authentication and client authentication was not completed during the TLS handshake, then IoT Hub rejects the connection.
 

articles/iot-hub/iot-hub-x509-certificate-concepts.md

@@ -121,10 +121,10 @@ To learn more about the fields that make up an X.509 certificate, see [X.509 cer
 
 If you're already familiar with X.509 certificates, and you want to generate test versions that you can use to authenticate to your IoT hub, see the following articles:
 
-* [Tutorial: Use OpenSSL to create test certificates](tutorial-x509-openssl.md)
+* [Tutorial: Create and upload certificates for testing](tutorial-x509-test-ca-certs.md)
 * If you want to use self-signed certificates for testing, see the [Create a self-signed certificate](reference-x509-certificates.md#create-a-self-signed-certificate) section of [X.509 certificates](reference-x509-certificates.md).
 
     >[!IMPORTANT]
     >We recommend that you use certificates signed by an issuing Certificate Authority (CA), even for testing purposes. Never use self-signed certificates in production.
 
-If you have a root CA certificate or subordinate CA certificate and you want to upload it to your IoT hub, you must verify that you own that certificate. For more information, see [Tutorial: Upload and verify a CA certificate to IoT Hub](tutorial-x509-prove-possession.md).
+If you have a root CA certificate or subordinate CA certificate and you want to upload it to your IoT hub, you must verify that you own that certificate. For more information, see [Tutorial: Create and upload certificates for testing](tutorial-x509-test-ca-certs.md).

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

@@ -28,13 +28,14 @@ The X.509 CA feature enables device authentication to IoT Hub using a certificat
 
 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 interact with third-party products or services.
+For production environments, we recommend that you purchase an X.509 CA certificate from a professional certificate services provider. 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.
+You may also create a self-signed X.509 CA certificate for testing purposes. For more information about creating certificates for testing, see [Create and upload certificates for testing](tutorial-x509-test-ca-certs.md).
 
-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.
+>[!NOTE]
+>We do not recommend the use of self-signed certificates for production environments.
 
-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.
+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.
 
 ## Sign devices into the certificate chain of trust
 
@@ -52,9 +53,9 @@ Register your X.509 CA certificate to IoT Hub, which uses it to authenticate you
 
 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 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.  You can choose to either automatically or manually verify ownership. For manual verification, Azure IoT Hub generates 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 and manually verify your certificate by uploading a file containing the results.
 
-Learn how to [register your CA certificate](./tutorial-x509-prove-possession.md)
+Learn how to [register your CA certificate](tutorial-x509-test-ca-certs.md#upload-and-verify-your-subordinate-ca-certificate)
 
 ## Create a device on IoT Hub
 
@@ -68,8 +69,6 @@ With your X.509 CA certificate registered and devices signed into a certificate
 
 A successful device connection to IoT Hub completes the authentication process and is also indicative of a proper setup. Every time a device connects, IoT Hub renegotiates the TLS session and verifies the device’s X.509 certificate.
 
-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).