1.1.29.1 TLS Contexts

TLS contexts encapsulate a TLS configuration which can then be associated with a service needing TLS support such as socket or MQTT connections.

To use a TLS context it must first be opened by calling WDRV_WINC_TLSCtxOpen, this presents a WDRV_WINC_TLS_HANDLE handle value which can be used when configuring the context and associating the context with other services.

A TLS context can be closed by calling WDRV_WINC_TLSCtxClose when it is no longer required.

WDRV_WINC_TLS_HANDLE handles can be used with WDRV_WINC_MQTTBrokerSet and WDRV_WINC_OTAUpdateFromURL directly. To use the handles with the Berkeley Sockets layer through setsockopt the handle must be converted to a context index using the function WDRV_WINC_TLSCtxHandleToCfgIdx.

TLS contexts consist of:

FieldFunction
Certificate Authority CertificateWDRV_WINC_TLSCtxCACertFileSet
CertificateWDRV_WINC_TLSCtxCertFileSet
Private KeyWDRV_WINC_TLSCtxPrivKeySet
Diffie-Hellman parametersWDRV_WINC_TLSCtxDHParamtersFileSet
Server Name IndicationWDRV_WINC_TLSCtxSNISet
Host Name ValidationWDRV_WINC_TLSCtxHostnameCheckSet
CiphersuiteWDRV_WINC_TLSCtxCipherSuiteSet

General usage of TLS contexts

In order to use a TLS context, the application must set at least the Certificate Authority Certificate and Host Name Validation fields. The other fields relate to additional TLS features.

The application calls WDRV_WINC_TLSCtxCACertFileSet to either:

  • Enable the authentication of peers, using a specified Certificate file in the WINCS02 file system to verify the peer's certificate chain of trust;or

  • Disable the authentication of peers.

The application calls WDRV_WINC_TLSCtxHostnameCheckSet to either:

  • Enable the validation of the peer certificate's subject name against a specified host name; or

  • Disable the validation of the peer certificate's subject name.

To enable authentication of the device by a peer, the application calls WDRV_WINC_TLSCtxCertFileSet to specify a Certificate file in the WINCS02 file system. The certificate (or chain) in that file will be sent to the peer for authentication. The application also indicates signing capabilites with the private key corresponding to its certificate, by either:

  • Calling WDRV_WINC_TLSCtxPrivKeySet to specify a Private Key file in the WINCS02 file system; or

  • Calling WDRV_WINC_TLSCtxSetSignCallback to register a callback with signing capabilities.

If the TLS context may be used for a TLS Server with Diffie-Hellman key exchange, the application calls WDRV_WINC_TLSCtxDHParamtersFileSet to specify a Diffie-Hellman Parameters file in the WINCS02 file system.

To enable the Server Name Indication extension (as TLS Client), the application calls WDRV_WINC_TLSCtxSNISet to set the Server Name to be sent in the extension.

To associate a ciphersuite list with a TLS context, the application calls WDRV_WINC_TLSCtxCipherSuiteSet.

Specific usage of TLS contexts

The WINCS02 driver interfaces which make use of TLS contexts include Berkeley Socket APIs, MQTT APIs and OTA APIs. Refer to those interfaces for further details of TLS context usage.