Incorp, round 1

KennedyDMSFT · KennedyDMSFT · commit 6e05f1a1ff9c · 2023-04-05T11:56:25.000-07:00
diff --git a/articles/iot-hub/.openpublishing.redirection.iot-hub.json b/articles/iot-hub/.openpublishing.redirection.iot-hub.json
@@ -1265,37 +1265,37 @@
     },
     {
       "source_path_from_root": "/articles/iot-hub/tutorial-x509-certificates.md",
-      "redirect_url": "/azure/iot-hub/tutorial-x509-test-ca-certs",
+      "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-test-ca-certs",
+      "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-ca-certs",
+      "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-ca-certs",
+      "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/tutorial-x509-test-ca-certs",
+      "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-test-ca-certs",
+      "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-ca-certs",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-test-certs",
       "redirect_document_id": false
     },
     {
diff --git a/articles/iot-hub/TOC.yml b/articles/iot-hub/TOC.yml
@@ -42,11 +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: 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: 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
diff --git a/articles/iot-hub/index.yml b/articles/iot-hub/index.yml
@@ -73,7 +73,7 @@ landingContent:
    - linkListType: tutorial
      links:
      - text: Create and upload certificates for testing
-       url: tutorial-x509-test-ca-certs.md
+       url: tutorial-x509-test-certs.md
    - linkListType: concept
      links:
      - text: Security best practices
diff --git a/articles/iot-hub/iot-hub-dev-guide-sas.md b/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 for testing, see [Tutorial: Create and upload certificates for testing](tutorial-x509-test-ca-certs.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
 
diff --git a/articles/iot-hub/iot-hub-mqtt-support.md b/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 [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).
+  > 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-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).
 
diff --git a/articles/iot-hub/iot-hub-tls-support.md b/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-test-ca-certs.md#create-a-client-certificate-for-a-device). _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.
 
diff --git a/articles/iot-hub/iot-hub-x509-certificate-concepts.md b/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: Create and upload certificates for testing](tutorial-x509-test-ca-certs.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: Create and upload certificates for testing](tutorial-x509-test-ca-certs.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).
diff --git a/articles/iot-hub/iot-hub-x509ca-overview.md b/articles/iot-hub/iot-hub-x509ca-overview.md
@@ -30,7 +30,7 @@ The X.509 CA certificate is at the top of the chain of certificates for each of
 
 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 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).
+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).
 
 >[!NOTE]
 >We do not recommend the use of self-signed certificates for production environments.
@@ -55,7 +55,7 @@ The upload process entails uploading a file that contains your certificate.  Thi
 
 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-test-ca-certs.md#register-your-subordinate-ca-certificate-to-your-iot-hub).
+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
 
diff --git a/articles/iot-hub/media/reference-x509-certificates/certificate-details.png b/articles/iot-hub/media/reference-x509-certificates/certificate-details.png
diff --git a/articles/iot-hub/media/tutorial-x509-test-certs/skip-pop.png b/articles/iot-hub/media/tutorial-x509-test-certs/skip-pop.png
diff --git a/articles/iot-hub/reference-x509-certificates.md b/articles/iot-hub/reference-x509-certificates.md
@@ -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:
diff --git a/articles/iot-hub/troubleshoot-error-codes.md b/articles/iot-hub/troubleshoot-error-codes.md
@@ -55,7 +55,7 @@ For device developers, if the volume of errors is a concern, switch to the C SDK
 In general, the error message presented should explain how to fix the error. If for some reason you don't have access to the error message detail, make sure:
 
 * The SAS or other security token you use isn't expired.
-* For X.509 certificate authentication, the device certificate or the CA certificate associated with the device isn't expired. To learn how to register X.509 CA certificates with IoT Hub, see [Tutorial: Create and upload certificates for testing](tutorial-x509-test-ca-certs.md).
+* For X.509 certificate authentication, the device certificate or the CA certificate associated with the device isn't expired. To learn how to register X.509 CA certificates with IoT Hub, see [Tutorial: Create and upload certificates for testing](tutorial-x509-test-certs.md).
 * For X.509 certificate thumbprint authentication, the thumbprint of the device certificate is registered with IoT Hub.
 * The authorization credential is well formed for the protocol that you use. To learn more, see [Control access to IoT Hub](iot-hub-devguide-security.md).
 * The authorization rule used has the permission for the operation requested.
diff --git a/articles/iot-hub/tutorial-x509-test-certs.md b/articles/iot-hub/tutorial-x509-test-certs.md
