Add a sample that demonstrates TLS 1.3 support (#1224)

* Add sample for TLS 1.3 support

* more

* note

* simplify sample

* comments

Author: timtay-microsoft

samples/how-to-guides/connect_with_tls13.md

@@ -0,0 +1,50 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+## SCENARIO
+
+Connect to an IoT hub using TLS 1.3 (currently in preview) and then periodically send telemetry messages.
+
+## CONTEXT
+
+### IoT hub support for TLS 1.3
+IoT Hub is currently previewing the ability to use TLS 1.3, but accessing that requires some small changes on the client side.
+
+Up until now, connection strings would always follow a format like:
+
+```
+<hub name>.azure-devices.<dnsSuffix> 
+```
+
+and this IoT hub endpoint supports TLS versions 1.0, 1.1, and 1.2
+
+IoT hub is previewing offering TLS version 1.2 + 1.3 support in endpoints with connection strings like
+
+```
+device connection string:
+<hub name>.device.azure-devices.<dnsSuffix> 
+```
+
+and
+
+```
+service connection string:
+<hub name>.service.azure-devices.<dnsSuffix> 
+```
+
+This sample expects the environment variable "IOTHUB_DEVICE_CONNECTION_STRING" to contain a connection string that follows the device connection string pattern above
+
+### SDK behavior
+
+When you run this sample, the "Client Hello" message in the TLS layer will advertise to IoT hub that this client supports TLS 1.2 and TLS 1.3. In the "Server Hello" response, IoT hub will then choose TLS 1.3 as the version for both client and server to use for this connection.
+
+Note that the SDK behavior here is unchanged as it has always advertised support for TLS 1.2 and TLS 1.3. The only change to make the connection use TLS 1.3 is to connect with the connection string of the host that also supports TLS 1.3
+
+## ADDITIONAL CONSIDERATIONS
+
+This feature is not generally available yet nor is it available in preview for all IoT hubs. As such, the above connection string pattern my yield a "host not found" exception.
+
+Note that this library currently uses the SSL library for all TLS connections. This SSL library has a few feature gaps around TLS 1.3 specifically as documented [here](https://docs.python.org/3/library/ssl.html#tls-1-3)

samples/how-to-guides/connect_with_tls13.py

@@ -0,0 +1,32 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+import os
+from azure.iot.device import IoTHubDeviceClient, Message
+
+# The device connection string to authenticate the device with your IoT hub.
+CONNECTION_STRING = os.getenv("IOTHUB_DEVICE_CONNECTION_STRING")
+
+if ".device.azure-devices." not in CONNECTION_STRING:
+    # classic connection strings that look like '<hub-name>.azure-devices.<dns suffix>' only support up to TLS 1.2
+    raise ValueError(
+        "Device connection string must match the format '<hub name>.device.azure-devices.<dns suffix>' in order to use TLS 1.3"
+    )
+
+# The client object is used to interact with your Azure IoT hub.
+device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)
+
+# Connect the client.
+print("opening the connection")
+device_client.connect()
+
+print("sending message")
+msg = Message("Hello from TLS 1.3 connection!")
+device_client.send_message(msg)
+
+# finally, shut down the client
+print("closing the connection")
+device_client.shutdown()