Merge pull request #228000 from KennedyDMSFT/US61610

User Story 61610

Author: v-shils

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-self-sign.md",
+      "redirect_url": "/azure/iot-hub/reference-x509-certificates",
+      "redirect_document_id": false
+    },
     {
       "source_path_from_root": "/articles/iot-hub/tutorial-x509-scripts.md",
       "redirect_url": "/azure/iot-hub/tutorial-x509-openssl",

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: Create self-signed certificates
-          displayName: X.509 certificates, OpenSSL, CSR, thumbprint
-          href: tutorial-x509-self-sign.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
@@ -538,7 +535,7 @@
     - name: Azure Policy built-ins
       href: ./policy-reference.md
     - name: X.509 certificates
-      displayName: certification authority (CA), subordinate CA, certificate versions, unique identifier, key identifier, binary certificate, PEM certificate, PKCS 
+      displayName: certificate authority (CA), subordinate CA, certificate versions, unique identifier, key identifier, binary certificate, PEM certificate, PKCS, X.509 certificates, OpenSSL, CSR, thumbprint 
       href: reference-x509-certificates.md
     - name: Feature and API retirement
       items:

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

@@ -122,6 +122,9 @@ 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: Use OpenSSL to create self-signed certificates](tutorial-x509-self-sign.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).

articles/iot-hub/reference-x509-certificates.md

@@ -14,7 +14,7 @@ ms.custom: [mvc, 'Role: Cloud Development', 'Role: Data Analytics']
 
 # X.509 certificates
 
-X.509 certificates are digital documents that represent a user, computer, service, or device. They're issued by a certification authority (CA), subordinate CA, or registration authority and contain the public key of the certificate subject. They don't contain the subject's private key, which must be stored securely. Public key certificates are documented by [RFC 5280](https://tools.ietf.org/html/rfc5280). They're digitally signed and, in general, contain the following information:
+X.509 certificates are digital documents that represent a user, computer, service, or device. A certificate authority (CA), subordinate CA, or registration authority issues X.509 certificates. The certificates contain the public key of the certificate subject. They don't contain the subject's private key, which must be stored securely. [RFC 5280](https://tools.ietf.org/html/rfc5280) documents public key certificates, including their fields and extensions. Public key certificates are digitally signed and typically contain the following information:
 
 * Information about the certificate subject
 * The public key that corresponds to the subject's private key
@@ -42,7 +42,7 @@ The following table describes Version 1 certificate fields for X.509 certificate
 | [Serial Number](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.2) | An integer that represents the unique number for each certificate issued by a certificate authority (CA). |
 | [Signature](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.3) | The identifier for the cryptographic algorithm used by the CA to sign the certificate. The value includes both the identifier of the algorithm and any optional parameters used by that algorithm, if applicable. |
 | [Issuer](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.4) | The distinguished name (DN) of the certificate's issuing CA. |
-| [Validity](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.5) | The inclusive time period for which the certificate is considered valid. |
+| [Validity](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.5) | The inclusive time period for which the certificate is valid. |
 | [Subject](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.6) | The distinguished name (DN) of the certificate subject. |
 | [Subject Public Key Info](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.7) | The public key owned by the certificate subject. |
 
@@ -69,7 +69,7 @@ Certificate extensions, introduced with Version 3, provide methods for associati
 
 ### Standard extensions
 
-The extensions included in this section are defined as part of the X.509 standard, for use in the Internet public key infrastructure (PKI). 
+The X.509 standard defines the extensions included in this section, for use in the Internet public key infrastructure (PKI). 
 
 | Name | Description |
 | --- | --- |
@@ -108,9 +108,84 @@ Certificates can be saved in various formats. Azure IoT Hub authentication typic
 | Binary certificate | A raw form binary certificate using Distinguished Encoding Rules (DER) ASN.1 encoding. |
 | ASCII PEM format | A PEM certificate (.pem) file contains a Base64-encoded certificate beginning with `-----BEGIN CERTIFICATE-----` and ending with `-----END CERTIFICATE-----`. One of the most common formats for X.509 certificates, PEM format is required by IoT Hub when uploading certain certificates, such as device certificates. |
 | ASCII PEM key | Contains a Base64-encoded DER key, optionally with more metadata about the algorithm used for password protection. |
-| PKCS #7 certificate | A format designed for the transport of signed or encrypted data. It can include the entire certificate chain. It's defined by [RFC 2315](https://tools.ietf.org/html/rfc2315). |
-| PKCS #8 key | The format for a private key store. It's defined by [RFC 5208](https://tools.ietf.org/html/rfc5208). |
-| PKCS #12 key and certificate | A complex format that can store and protect a key and the entire certificate chain. It's commonly used with a .p12 or .pfx extension. PKCS #12 is synonymous with the PFX format. It's defined by [RFC 7292](https://tools.ietf.org/html/rfc7292). |
+| PKCS #7 certificate | A format designed for the transport of signed or encrypted data. It can include the entire certificate chain. [RFC 2315](https://tools.ietf.org/html/rfc2315) defines this format. |
+| PKCS #8 key | The format for a private key store. [RFC 5208](https://tools.ietf.org/html/rfc5208) defines this format. |
+| PKCS #12 key and certificate | A complex format that can store and protect a key and the entire certificate chain. It's commonly used with a .p12 or .pfx extension. PKCS #12 is synonymous with the PFX format. [RFC 7292](https://tools.ietf.org/html/rfc7292) defines this format. |
+
+## Self-signed certificates
+
+You can authenticate a device to your IoT hub for testing purposes by using two self-signed certificates. This type of authentication is sometimes called *thumbprint authentication* because the certificates are identified by calculated hash values called *fingerprints* or *thumbprints*. These calculated hash values are used by IoT Hub to authenticate your devices.
+
+>[!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.
+
+### Create a self-signed certificate
+
+You can use [OpenSSL](https://www.openssl.org/) to create self-signed certificates. The following steps show you how to run OpenSSL commands in a bash shell to create a self-signed certificate and retrieve a certificate fingerprint that can be used for authenticating your device in IoT Hub. 
+
+>[!NOTE]
+>If you want to use self-signed certificates for testing, you must create two certificates for each device. 
+
+1. Run the following command to generate a private key and create a PEM-encoded private key (.key) file, replacing the following placeholders with their corresponding values. The private key generated by the following command uses the RSA algorithm with 2048-bit encryption.
+
+    *{KeyFile}*. The name of your private key file.
+
+    ```bash
+    openssl genpkey -out {KeyFile} -algorithm RSA -pkeyopt rsa_keygen_bits:2048
+    ```
+
+1. Run the following command to generate a PKCS #10 certificate signing request (CSR) and create a CSR (.csr) file, replacing the following placeholders with their corresponding values. Make sure that you specify the device ID of the IoT device for your self-signed certificate when prompted.
+
+    *{KeyFile}*. The name of your private key file.
+
+    *{CsrFile}*. The name of your CSR file.
+
+    *{DeviceID}*. The name of your IoT device.
+
+    ```bash
+    openssl req -new -key {KeyFile} -out {CsrFile}
+    
+    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) []:{DeviceID}
+    Email Address []:.
+    
+    Please enter the following 'extra' attributes
+    to be sent with your certificate request
+    A challenge password []:.
+    An optional company name []:.
+    ```
+
+1.  Run the following command to examine and verify your CSR, replacing the following placeholders with their corresponding values. 
+
+    *{CsrFile}*. The name of your certificate file.
+
+    ```bash
+    openssl req -text -in {CsrFile} -verify -noout
+    ```
+    
+1. Run the following command to generate a self-signed certificate and create a PEM-encoded certificate (.crt) file, replacing the following placeholders with their corresponding values. The command converts and signs your CSR with your private key, generating a self-signed certificate that expires in 365 days. 
+
+    *{KeyFile}*. The name of your private key file.
+
+    *{CsrFile}*. The name of your CSR file.
+
+    *{CrtFile}*. The name of your certificate file.
+
+    ```bash
+    openssl x509 -req -days 365 -in {CsrFile} -signkey {KeyFile} -out {CrtFile}
+    ```
+
+1. Run the following command to retrieve the fingerprint of the certificate, replacing the following placeholders with their corresponding values. The fingerprint of a certificate is a calculated hash value that is unique to that certificate. You need the fingerprint to configure your IoT device in IoT Hub for testing.
+
+    *{CrtFile}*. The name of your certificate file.
+
+    ```bash
+    openssl x509 -in {CrtFile} -noout -fingerprint
+    ```
 
 ## For more information
 

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

@@ -37,8 +37,6 @@ Before starting any of the articles in this tutorial, you should be familiar wit
 
 ## X.509 certificate scenario paths
 
-Using a self-signed certificate to authenticate a device provides a quick and easy way to test IoT Hub features. Self-signed certificates shouldn't be used in production as they provide less security than a certificate chain anchored with a CA-signed certificate backed by a PKI. To learn more about creating and using a self-signed X.509 certificate to authenticate with IoT Hub, see [Tutorial: Use OpenSSL to create self-signed certificates](tutorial-x509-self-sign.md).
-
 Using a CA-signed certificate chain backed by a PKI to authenticate a device provides the best level of security for your devices:
 
 - In production, we recommend you get your X.509 CA certificates 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. If you already have an X.509 CA certificate, and you know how to create and sign device certificates into a certificate chain, follow the instructions in [Tutorial: Upload and verify a CA certificate to IoT Hub](/tutorial-x509-prove-possession.md) to upload your CA certificate to your IoT hub. Then, follow the instructions in [Tutorial: Test certificate authentication](tutorial-x509-test-certificate.md) to authenticate a device with your IoT hub.
@@ -52,6 +50,9 @@ 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: Use OpenSSL to create self-signed certificates](tutorial-x509-self-sign.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).