Merge pull request #232374 from KennedyDMSFT/US61440-2

IoT Hub: Combine remaining cert tutorials

Author: JamesJBarnett

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

@@ -1270,22 +1270,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-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-certs",
+      "redirect_document_id": false
+    },
+    {
+      "source_path_from_root": "/articles/iot-hub/tutorial-x509-openssl.md",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-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-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-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-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-certs",
       "redirect_document_id": false
     },
     {

articles/iot-hub/TOC.yml

@@ -42,17 +42,9 @@
     - name: Data visualization in Power BI
       displayName: Stream Analytics
       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-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-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-certs.md).
 
 ### Enforcing X.509 authentication
 

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-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-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-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-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-certs.md#register-your-subordinate-ca-certificate-to-your-iot-hub).
 
 ## 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).

articles/iot-hub/media/reference-x509-certificates/certificate-details.png

@@ -187,6 +187,58 @@ You can use [OpenSSL](https://www.openssl.org/) to create self-signed certificat
     openssl x509 -in {CrtFile} -noout -fingerprint
     ```
 
+### Verify certificate manually after upload
+
+When you upload your root certificate authority (CA) certificate or subordinate CA certificate to your IoT hub, you can choose to automatically verify the certificate. If you didn't choose to automatically verify your certificate during upload, your certificate is shown with its status set to **Unverified**. You must perform the following steps to manually verify your certificate. 
+
+1. Select the certificate to view the **Certificate Details** dialog.
+ 
+1. Select **Generate Verification Code** in the dialog.
+
+    :::image type="content" source="media/reference-x509-certificates/certificate-details.png" alt-text="Screenshot showing the certificate details dialog.":::
+    
+1. Copy the verification code to the clipboard. You must use this verification code as the certificate subject in subsequent steps. For example, if the verification code is `75B86466DA34D2B04C0C4C9557A119687ADAE7D4732BDDB3`, add that as the subject of your certificate as shown in the next step.
+
+1. There are three ways to generate a verification certificate:
+
+    - If you're using the PowerShell script supplied by Microsoft, run `New-CACertsVerificationCert "<verification code>"` to create a certificate named `VerifyCert4.cer`, replacing `<verification code>` with the previously generated verification code. For more information, see [Managing test CA certificates for samples and tutorials](https://github.com/Azure/azure-iot-sdk-c/blob/main/tools/CACertificates/CACertificateOverview.md) in the GitHub repository for the [Azure IoT Hub Device SDK for C](https://github.com/Azure/azure-iot-sdk-c).
+
+    - If you're using the Bash script supplied by Microsoft, run `./certGen.sh create_verification_certificate "<verification code>"` to create a certificate named verification-code.cert.pem, replacing `<verification code>` with the previously generated verification code. For more information, see [Managing test CA certificates for samples and tutorials](https://github.com/Azure/azure-iot-sdk-c/blob/main/tools/CACertificates/CACertificateOverview.md) in the GitHub repository for the Azure IoT Hub Device SDK for C.
+
+    - If you're using OpenSSL to generate your certificates, you must first generate a private key, then generate a certificate signing request (CSR) file. In the following example, replace `<verification code>` with the previously generated verification code:
+    
+    ```bash
+    openssl genpkey -out pop.key -algorithm RSA -pkeyopt rsa_keygen_bits:2048
+
+    openssl req -new -key pop.key -out pop.csr
+
+    -----
+    Country Name (2 letter code) [XX]:.
+    State or Province Name (full name) []:.
+    Locality Name (eg, city) [Default City]:.
+    Organization Name (eg, company) [Default Company Ltd]:.
+    Organizational Unit Name (eg, section) []:.
+    Common Name (eg, your name or your server hostname) []:<verification code>
+    Email Address []:
+    
+    Please enter the following 'extra' attributes
+    to be sent with your certificate request
+    A challenge password []:
+    An optional company name []:
+    ```
+
+    Then, create a certificate using the appropriate configuration file for either the root CA or the subordinate CA, and the CSR file. The following example demonstrates how to use OpenSSL to create the certificate from a root CA configuration file and the CSR file.
+
+    ```bash
+    openssl ca -config rootca.conf -in pop.csr -out pop.crt -extensions client_ext
+    ```
+
+    For more information, see [Tutorial - Create and upload certificates for testing](tutorial-x509-test-certs.md).
+
+1. Select the new certificate in the **Certificate Details** view.
+
+1. After the certificate uploads, select **Verify**. The certificate status should change to **Verified**.
+
 ## For more information
 
 For more information about X.509 certificates and how they're used in IoT Hub, see the following articles: