7.2 KiB
Configure TLS Protocol Version and Ciphers
How to configure the Azure IoT C SDK TLS platforms to disable TLS 1.0 and TLS 1.1
SChannel (Microsoft Windows)
To use exclusively TLS 1.2 in Microsoft Windows using SChannel, disable the support for TLS 1.0 and 1.1.
Be aware that this action might impact other applications in the systems that might not support higher versions of TLS.
To disable support in SChannel for TLS 1.0, follow this documentation.
To disable support in SChannel for TLS 1.1, follow this documentation.
For more information on TLS configuration please see the following documentation.
OpenSSL
The latest Azure IoT C SDK uses TLS 1.2 by default with OpenSSL.
The SDK creates the SSL context using the method related to the TLS version selected (1.2 by default).
According to the OpenSSL documentation the method selected causes OpenSSL to use only the TLS version associated with that method.
WolfSSL
To use only TLS 1.2 or higher, WolfSSL library MUST be built without using “--enable-oldtls”.
Please check the WolfSSL documentation as this option is enabled by default on the binaries distributed by them.
In its adapter layer, Azure IoT C SDK does not directly set the TLS version that wolfSSL should use. The result is that the wolfSSL library will use its default TLS version.
Apple iOS
TLS 1.2+ should already be the default for the latest versions of Apple iOS.
mbedTLS
mbedTLS can be configured to use only higher versions of TLS. That is achieved by calling mbedtls_ssl_conf_min_version.
In its adapter layer, Azure IoT C SDK already sets the minimum TLS version that mbedTLS should use to TLS 1.2.
BearSSL/esp8266 Arduino
TLS version can be set on BearSSL by using br_ssl_engine_set_versions.
Currently the Azure IoT C SDK does not directly set the minimum version of TLS to be used by BearSSL.
How to configure ciphers in the Azure IoT C SDK supported TLS platforms
SChannel (Microsoft Windows)
To configure additional ciphers for SChannel please follow this documentation.
OpenSSL
The OpenSSL API function SSL_CTX_set_cipher_list can be used to set the list of ciphers used by the OpenSSL library.
In the current Azure IoT C SDK code the OpenSSL adapter already calls SSL_CTX_set_cipher_list.
To take advantage of that functionality please use:
IoTHubDeviceClient_LL_SetOption, if using "iothub_device_client_ll.h", or;
#include "azure_c_shared_utility/shared_util_options.h" // for OPTION_OPENSSL_CIPHER_SUITE
...
const char* ciphers = "list of ciphers, in the format expected by OpenSSL API's SSL_CTX_set_cipher_list()"; // please modify this string to have the desired ciphers.
IoTHubDeviceClient_LL_SetOption(iotHubClientHandle, OPTION_OPENSSL_CIPHER_SUITE, ciphers);
IoTHubDeviceClient_SetOption, if using "iothub_device_client.h", or;
#include "azure_c_shared_utility/shared_util_options.h" // for OPTION_OPENSSL_CIPHER_SUITE
...
const char* ciphers = "list of ciphers, in the format expected by OpenSSL API's SSL_CTX_set_cipher_list()"; // please modify this string to have the desired ciphers.
IoTHubDeviceClient_SetOption(iotHubClientHandle, OPTION_OPENSSL_CIPHER_SUITE, ciphers);
IoTHubModuleClient_LL_SetOption, if using "iothub_module_client_ll.h", or;
#include "azure_c_shared_utility/shared_util_options.h" // for OPTION_OPENSSL_CIPHER_SUITE
...
const char* ciphers = "list of ciphers, in the format expected by OpenSSL API's SSL_CTX_set_cipher_list()"; // please modify this string to have the desired ciphers.
IoTHubModuleClient_LL_SetOption(iotHubModuleClientHandle, OPTION_OPENSSL_CIPHER_SUITE, ciphers);
IoTHubModuleClient_SetOption, if using "iothub_module_client.h", or;
#include "azure_c_shared_utility/shared_util_options.h" // for OPTION_OPENSSL_CIPHER_SUITE
...
const char* ciphers = "list of ciphers, in the format expected by OpenSSL API's SSL_CTX_set_cipher_list()"; // please modify this string to have the desired ciphers.
IoTHubModuleClient_SetOption(iotHubClientHandle, OPTION_OPENSSL_CIPHER_SUITE, ciphers);
WolfSSL
Please check the WolfSSL documentation to build the WolfSSL library to support the desired ciphers.
In its adapter layer, Azure IoT C SDK does not directly set the ciphers that wolfSSL should use.
Apple iOS
Please follow the same guidelines above for using OpenSSL.
mbedTLS
This mbedTLS documentation provides details of how to set supported ciphers.
Any additional calls to mbedTLS API should be done in the Azure IoT C SDK mbedTLS adapter code (tlsio_mbedtls.c, on tlsio_mbedtls.c after mbedtls_ssl_config_init).
BearSSL/esp8266 Arduino
Set the cipher suite while defining profile at initialization (see "Profiles" in the BearSSL documentation) or use setCiphers.
Any additional calls to BearSSL API should be done in the Azure IoT C SDK BearSSL adapter code (tlsio_bearssl.c, on tlsio_bearssl_open after br_ssl_client_init_full).