Updating documentation for ECC server certificate chain support. (#1979)

Updating documentation for ECC server certificate chain support.
Azure · Jun 5, 2021 · 24497d7 · 24497d7
1 parent 1139bc0
commit 24497d7
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 1 deletion.
diff --git a/certs/readme.md b/certs/readme.md
@@ -33,3 +33,34 @@ A couple of examples:
 ## Additional Information
 
 For additional guidance and important information about certificates, please refer to [this blog post](https://techcommunity.microsoft.com/t5/internet-of-things/azure-iot-tls-critical-changes-are-almost-here-and-why-you/ba-p/2393169) from the security team.
+
+## IoT Hub ECC Server Certificate Chain
+
+To work with the new Azure Cloud ECC server certificate chain, the TLS stack must be configured to prevent RSA cipher-suites from being advertised as described [here](https://docs.microsoft.com/azure/iot-hub/iot-hub-tls-support#elliptic-curve-cryptography-ecc-server-tls-certificate-preview).
+
+### Using OpenSSL
+
+Use the following option to limit the advertised cipher-suites:
+```C
+IoTHubDeviceClient_LL_SetOption(device_ll_handle, OPTION_OPENSSL_CIPHER_SUITE, "ECDH+ECDSA+HIGH");
+```
+
+### Using wolfSSL
+
+Rebuild wolfSSL without RSA support by adding `--disable-rsa` to the `configure` step.
+
+### Using mbedTLS
+
+Change `include/mbedtls/config.h` by commenting out all `_RSA_ENABLED` defines:
+```C
+MBEDTLS_KEY_EXCHANGE_RSA_ENABLED
+MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED
+MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED
+MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED
+```
+
+Also, ensure you have the following two options enabled for ECC P-384 and SHA384 support:
+```C
+MBEDTLS_ECP_DP_SECP384R1_ENABLED
+MBEDTLS_SHA512_C
+```
diff --git a/iothub_client/devdoc/iothubclient_c_library.md b/iothub_client/devdoc/iothubclient_c_library.md
@@ -500,7 +500,12 @@ const char* x509privatekey =
 "-----END RSA PRIVATE KEY-----\n";
 ```
 
-- "CypherSuite" - only available when OpenSSL is used. value is a pointer to a null terminated string that contains a list in the format specified by [SSL_set_cipher_list](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_cipher_list.html).
+- "CipherSuite" - only available when OpenSSL is used. value is a pointer to a null terminated string that contains a list in the format specified by [SSL_set_cipher_list](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_cipher_list.html). Example:
+```c
+// IoT Hub using ECC server certificate chain:
+IoTHubDeviceClient_LL_SetOption(device_ll_handle, OPTION_OPENSSL_CIPHER_SUITE, "ECDH+ECDSA+HIGH");
+```
+
 - "Engine" - only available when OpenSSL is used. It specifies the [OpenSSL built-in engine](https://www.openssl.org/docs/man1.1.1/man3/ENGINE_load_builtin_engines.html) to be loaded. value is a null terminated string that contains the engine name.
 - "x509PrivatekeyType" - only available when OpenSSL is used and OPENSSLOPT_ENGINE is configured. value is a pointer to a long. When set to 0x1, the private key is loaded from the OpenSSL Engine. The `x509privatekey` option represents the engine-specific certificate identifier.