Merge pull request #228010 from KennedyDMSFT/US61355

User Story 61355

Author: v-regandowner

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

@@ -1128,6 +1128,11 @@
       "redirect_url": "/azure/iot-hub/reference-x509-certificates",
       "redirect_document_id": true
     },
+    {
+      "source_path_from_root": "/articles/iot-hub/tutorial-x509-scripts.md",
+      "redirect_url": "/azure/iot-hub/tutorial-x509-openssl",
+      "redirect_document_id": false
+    },
     {
       "source_path_from_root": "/articles/iot-hub/iot-hub-reliability-features-in-sdks.md",
       "redirect_url": "/azure/iot-develop/how-to-use-reliability-features-in-sdks",

articles/iot-hub/TOC.yml

@@ -50,9 +50,6 @@
         - name: Use OpenSSL to create test certificates
           displayName: X.509 certificates, root CA
           href: tutorial-x509-openssl.md
-        - name: Use Microsoft-supplied scripts to create test certificates
-          displayName: PowerShell scripts, Windows Certificate Store, CA certificate
-          href: tutorial-x509-scripts.md
         - name: Create self-signed certificates
           displayName: X.509 certificates, OpenSSL, CSR, thumbprint
           href: tutorial-x509-self-sign.md

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

@@ -267,7 +267,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-scripts.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, see [Set up X.509 security in your Azure IoT hub](./tutorial-x509-prove-possession.md).
 
 ### Enforcing X.509 authentication
 

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

@@ -146,7 +146,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-scripts.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 [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).
 
   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-x509-certificate-concepts.md

@@ -121,7 +121,6 @@ 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 Microsoft-supplied scripts to create test certificates](tutorial-x509-scripts.md)
 * [Tutorial: Use OpenSSL to create test certificates](tutorial-x509-openssl.md)
 * [Tutorial: Use OpenSSL to create self-signed certificates](tutorial-x509-self-sign.md)
 

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

@@ -54,21 +54,21 @@ 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.  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.
 
-Learn how to [register your CA certificate](./tutorial-x509-scripts.md)
+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).
 
-Learn how to [manually create a device in IoT Hub](./tutorial-x509-scripts.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).
 
 ## Authenticate devices signed with X.509 CA certificates
 
 With your X.509 CA certificate registered and devices signed into a certificate chain of trust, the final step is device authentication when the device connects.  When an X.509 CA-signed device connects, it uploads its certificate chain for validation. The chain includes all intermediate CA and device certificates.  With this information, IoT Hub authenticates the device in a two-step process.  IoT Hub cryptographically validates the certificate chain for internal consistency, and then issues a proof-of-possession challenge to the device.  IoT Hub declares the device authentic on a successful proof-of-possession response from the device.  This declaration assumes that the device's private key is protected and that only the device can successfully respond to this challenge.  We recommend using secure chips like Hardware Secure Modules (HSM) in devices to protect private keys.
 
 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-scripts.md).
+Learn how to [complete this device connection step](./tutorial-x509-prove-possession.md).
 
 ## Next Steps
 

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 [Set up X.509 security in your Azure IoT hub](tutorial-x509-scripts.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 [Set up X.509 security in your Azure IoT hub](tutorial-x509-prove-possession.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.

articles/iot-hub/tutorial-x509-introduction.md

@@ -45,15 +45,12 @@ Using a CA-signed certificate chain backed by a PKI to authenticate a device pro
 
 - For testing purposes, we recommend using OpenSSL to create an X.509 certificate chain. OpenSSL is used widely across the industry to work with X.509 certificates. You can follow the steps in [Tutorial: Use OpenSSL to create test certificates](tutorial-x509-openssl.md) to create a root CA and intermediate CA certificate with which to create and sign device certificates. The tutorial also shows how to upload and verify a CA certificate. Then, follow the instructions in [Tutorial: Test certificate authentication](tutorial-x509-test-certificate.md) to authenticate a device with your IoT hub.
 
-- Several of the Azure IoT SDKs provide convenience scripts to help you create test certificate chains. For instructions about how to create certificate chains in PowerShell or Bash using scripts provided in the Azure IoT C SDK, see [Tutorial: Use Microsoft-supplied scripts to create test certificates](tutorial-x509-scripts.md). The tutorial also shows how to upload and verify a CA certificate. Then follow the instructions in [Tutorial: Test certificate authentication](tutorial-x509-test-certificate.md) to authenticate a device with your IoT hub.
-
 ## Next steps
 
 To learn more about the fields that make up an X.509 certificate, see [X.509 certificates](reference-x509-certificates.md).
 
 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 Microsoft-supplied scripts to create test certificates](tutorial-x509-scripts.md)
 * [Tutorial: Use OpenSSL to create test certificates](tutorial-x509-openssl.md)
 * [Tutorial: Use OpenSSL to create self-signed certificates](tutorial-x509-self-sign.md)
 

articles/iot-hub/tutorial-x509-openssl.md

@@ -14,14 +14,19 @@ ms.custom: [mvc, 'Role: Cloud Development', 'Role: Data Analytics']
 
 # Tutorial: Use OpenSSL to create test certificates
 
-Although you can purchase X.509 certificates from a trusted certification authority, creating your own test certificate hierarchy or using self-signed certificates is adequate for testing IoT hub device authentication. The following example uses [OpenSSL](https://www.openssl.org/) and the [OpenSSL Cookbook](https://www.feistyduck.com/library/openssl-cookbook/online/ch-openssl.html) to create a certification authority (CA), a subordinate CA, and a device certificate. The example then signs the subordinate CA and the device certificate into a certificate hierarchy. This is presented for example purposes only.
+For production environments, we recommend that you purchase an X.509 CA certificate from a public root certificate authority (CA). However, creating your own test certificate hierarchy is adequate for testing IoT Hub device authentication. For more information about getting an X.509 CA certificate from a public root CA, see the [Get an X.509 CA certificate](iot-hub-x509ca-overview.md#get-an-x509-ca-certificate) section of [Authenticate devices using X.509 CA certificates](iot-hub-x509ca-overview.md).
+
+The following example uses [OpenSSL](https://www.openssl.org/) and the [OpenSSL Cookbook](https://www.feistyduck.com/library/openssl-cookbook/online/ch-openssl.html) to create a certificate authority (CA), a subordinate CA, and a device certificate. The example then signs the subordinate CA and the device certificate into a certificate hierarchy. This example is presented for demonstration purposes only.
+
+>[!NOTE]
+>Microsoft provides PowerShell and Bash scripts to help you understand how to create your own X.509 certificates and authenticate them to an IoT hub. The scripts are included with the [Azure IoT Hub Device SDK for C](https://github.com/Azure/azure-iot-sdk-c). The scripts are provided for demonstration purposes only. Certificates created by them must not be used for production. The certificates contain hard-coded passwords (“1234”) and expire after 30 days. You must use your own best practices for certificate creation and lifetime management in a production environment. 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).
 
 ## Step 1 - Create the root CA directory structure
 
-Create a directory structure for the certification authority.
+Create a directory structure for the certificate authority.
 
 * The *certs* directory stores new certificates.
-* The *db* directory is used for the certificate database.
+* The *db* directory stores the certificate database.
 * The *private* directory stores the CA private key.
 
 ```bash
@@ -112,7 +117,7 @@ First, generate a private key and the certificate signing request (CSR) in the *
   openssl req -new -config rootca.conf -out rootca.csr -keyout private/rootca.key
 ```
 
-Next, create a self-signed CA certificate. Self-signing is suitable for testing purposes. Specify the `ca_ext` configuration file extensions on the command line. These indicate that the certificate is for a root CA and can be used to sign certificates and certificate revocation lists (CRLs). Sign the certificate, and commit it to the database.
+Next, create a self-signed CA certificate. Self-signing is suitable for testing purposes. Specify the `ca_ext` configuration file extensions on the command line. These extensions indicate that the certificate is for a root CA and can be used to sign certificates and certificate revocation lists (CRLs). Sign the certificate, and commit it to the database.
 
 ```bash
   openssl ca -selfsign -config rootca.conf -in rootca.csr -out rootca.crt -extensions ca_ext
@@ -203,7 +208,7 @@ subjectKeyIdentifier     = hash
 
 ## Step 6 - Create a subordinate CA
 
-This example shows you how to create a subordinate or registration CA. Because you can use the root CA to sign certificates, creating a subordinate CA isn’t strictly necessary. Having a subordinate CA does, however, mimic real world certificate hierarchies in which the root CA is kept offline and subordinate CAs issue client certificates.
+This example shows you how to create a subordinate or registration CA. Because you can use the root CA to sign certificates, creating a subordinate CA isn’t strictly necessary. Having a subordinate CA does, however, mimic real world certificate hierarchies in which the root CA is kept offline and a subordinate CA issues client certificates.
 
 From the *subca* directory, use the configuration file to generate a private key and a certificate signing request (CSR).
 

articles/iot-hub/tutorial-x509-prove-possession.md

@@ -47,9 +47,9 @@ If you didn't choose to automatically verify your certificate during upload, you
 
 5. 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 [Tutorial: Use Microsoft-supplied scripts to create test certificates](tutorial-x509-scripts.md).
+    * 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 [Tutorial: Use OpenSSL to create test certificates](tutorial-x509-openssl.md).
 
-    * 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 [Tutorial: Use Microsoft-supplied scripts to create test certificates](tutorial-x509-scripts.md).
+    * 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 [Tutorial: Use OpenSSL to create test certificates](tutorial-x509-openssl.md).
 
     * 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: