General Description

All the API functions except cy_tls_init cy_tls_deinit cy_tls_load_global_root_ca_certificates and cy_tls_release_global_root_ca_certificates are thread-safe.

All the API functions are blocking API functions.

Functions
cy_rslt_t	cy_tls_init (void)
	Does general allocation and initialization of resources needed for the library. More...

cy_rslt_t	cy_tls_deinit (void)
	Releases the resources allocated in the cy_tls_init function. More...

cy_rslt_t	cy_tls_load_global_root_ca_certificates (const char *trusted_ca_certificates, const uint32_t cert_length)
	Initializes the global trusted RootCA certificates used for verifying certificates received during TLS handshake. More...

cy_rslt_t	cy_tls_release_global_root_ca_certificates (void)
	Releases the resources allocated by the cy_tls_load_global_root_ca_certificates API function. More...

cy_rslt_t	cy_tls_create_identity (const char certificate_data, const uint32_t certificate_len, const char private_key, uint32_t private_key_len, void **tls_identity)
	Creates an identity structure from the supplied certificate and private key. More...

cy_rslt_t	cy_tls_delete_identity (void *tls_identity)
	Releases resources allocated by the cy_tls_create_identity API function. More...

cy_rslt_t	cy_tls_create_context (cy_tls_context_t context, cy_tls_params_t params)
	Creates a TLS context structure from the input parameters. More...

cy_rslt_t	cy_tls_connect (cy_tls_context_t context, cy_tls_endpoint_type_t endpoint, uint32_t timeout)
	Performs a TLS handshake and connects to the server. More...

cy_rslt_t	cy_tls_send (cy_tls_context_t context, const unsigned char data, uint32_t length, uint32_t timeout, uint32_t bytes_sent)
	Encrypts the given data and sends it over a secure connection. More...

cy_rslt_t	cy_tls_recv (cy_tls_context_t context, unsigned char buffer, uint32_t length, uint32_t timeout, uint32_t bytes_received)
	Reads the encrypted data from the network, decrypts the data, and then stores it in the given buffer. More...

cy_rslt_t	cy_tls_delete_context (cy_tls_context_t context)
	Releases the resources allocated for the TLS connection. More...

cy_rslt_t	cy_tls_config_cert_profile_param (cy_tls_md_type_t mds_type, cy_tls_rsa_min_key_len_t rsa_bit_len)
	Configures a custom certificate profile using the message digest and RSA min key length. More...

cy_rslt_t	cy_tls_is_certificate_valid_x509 (const char *certificate_data, const uint32_t certificate_len)
	Checks if given buffer is in valid certificate format. More...

Function Documentation

◆ cy_tls_init()

cy_rslt_t cy_tls_init ( void )

Does general allocation and initialization of resources needed for the library.

This API function must be called before using any other context-based TLS API functions.

Note

Helper APIs cy_tls_load_global_root_ca_certificates, cy_tls_release_global_root_ca_certificates, cy_tls_create_identity, and cy_tls_delete_identity can be called without calling cy_tls_init.
cy_tls_init and cy_tls_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Returns: CY_RSLT_SUCCESS on success; an error code on failure.

◆ cy_tls_deinit()

cy_rslt_t cy_tls_deinit ( void )

Releases the resources allocated in the cy_tls_init function.

Note: cy_tls_init and cy_tls_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Returns: CY_RSLT_SUCCESS on success; an error code on failure.

◆ cy_tls_load_global_root_ca_certificates()

cy_rslt_t cy_tls_load_global_root_ca_certificates	(	const char *	trusted_ca_certificates,
		const uint32_t	cert_length
	)

Initializes the global trusted RootCA certificates used for verifying certificates received during TLS handshake.

This function parses the RootCA certificate chain and converts it to the underlying TLS stack format. It also stores the converted RootCA in its internal memory. This function overrides previously loaded RootCA certificates.

If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is disabled: a. RootCA attached to the context will take first preference. b. RootCA set as global will take the last preference.
If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is enabled: a. By default, RootCA certificates which is provisioned to secure element will be used. b. If socket option CY_SOCKET_SO_ROOTCA_CERTIFICATE_LOCATION is set with value CY_SOCKET_ROOTCA_RAM then
- RootCA attached to the context will take first preference.
- RootCA set as global will take the last preference.

Note: cy_tls_load_global_root_ca_certificates and cy_tls_release_global_root_ca_certificates API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Parameters

[in]	trusted_ca_certificates	A chain of x509 certificates in PEM or DER format. It should be a null-terminated string. This chain of certificates comprise the public keys of the signing authorities. During the handshake, these public keys are used to verify the authenticity of the peer.
[in]	cert_length	Length of the trusted RootCA certificates excluding the 'null' terminator. The buffer pointed by trusted_ca_certificates is treated as a byte stream.

Returns: cy_rslt_t CY_RESULT_SUCCESS on success; an error code on failure. Important error codes related to this API function are:
CY_RSLT_MODULE_TLS_BADARG
CY_RSLT_MODULE_TLS_OUT_OF_HEAP_SPACE
CY_RSLT_MODULE_TLS_PARSE_CERTIFICATE

◆ cy_tls_release_global_root_ca_certificates()

cy_rslt_t cy_tls_release_global_root_ca_certificates ( void )

Releases the resources allocated by the cy_tls_load_global_root_ca_certificates API function.

Note: cy_tls_load_global_root_ca_certificates and cy_tls_release_global_root_ca_certificates API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Returns: cy_rslt_t CY_RESULT_SUCCESS on success; an error code on failure.

◆ cy_tls_create_identity()

cy_rslt_t cy_tls_create_identity	(	const char *	certificate_data,
		const uint32_t	certificate_len,
		const char *	private_key,
		uint32_t	private_key_len,
		void **	tls_identity
	)

Creates an identity structure from the supplied certificate and private key.

If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is disabled: a. TLS identity created using cy_tls_create_identity and set to context using socket option CY_SOCKET_SO_TLS_IDENTITY will be used for device certificate & key
If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is enabled: a. By default, device certificates & private keys which are provisioned to secure element will be used. b. If socket option CY_SOCKET_SO_DEVICE_CERT_KEY_LOCATION is set with value CY_SOCKET_DEVICE_CERT_KEY_RAM then TLS identity created with cy_tls_create_identity API and set to context using socket option CY_SOCKET_SO_TLS_IDENTITY will be used.

Parameters

[in]	certificate_data	x509 certificate in PEM format. It should be a null-terminated string.
[in]	certificate_len	Length of the certificate excluding the 'null' terminator.
[in]	private_key	Private key in PEM format. It should be a null-terminated string.
[in]	private_key_len	Length of the private key excluding the 'null' terminator.
[out]	tls_identity	Pointer to a memory location containing the certificate and key in the underlying TLS stack format.

Returns: CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are:
CY_RSLT_MODULE_TLS_BADARG
CY_RSLT_MODULE_TLS_OUT_OF_HEAP_SPACE
CY_RSLT_MODULE_TLS_PARSE_CERTIFICATE
CY_RSLT_MODULE_TLS_PARSE_KEY

◆ cy_tls_delete_identity()

cy_rslt_t cy_tls_delete_identity ( void * tls_identity )

Releases resources allocated by the cy_tls_create_identity API function.

Parameters

[in] tls_identity Pointer to a memory location containing the certificate and key in the underlying TLS stack format.

Returns: CY_RSLT_SUCCESS on success; an error code on failure. Important error code related to this API function is:
CY_RSLT_MODULE_TLS_BADARG

◆ cy_tls_create_context()

cy_rslt_t cy_tls_create_context	(	cy_tls_context_t *	context,
		cy_tls_params_t *	params
	)

Creates a TLS context structure from the input parameters.

It allocates a TLS context structure and stores the RootCA, TLS identity, send/receive callback functions, server name to be used in the SNI extension, protocol list to be added to the ALPN extension, and user context. TLS parameters provided by the user are used in later cy_tls API function calls. The memory holding the parameters should not be freed until completely done with using cy_tls API functions.

Parameters

[out]	context	Context handle returned by the TLS layer.
[in]	params	TLS parameters specified by the caller such as the server certificate.

Returns: CY_RSLT_SUCCESS on success; an error code on failure. Important error codes related to this API function are:
CY_RSLT_MODULE_TLS_BADARG
CY_RSLT_MODULE_TLS_OUT_OF_HEAP_SPACE

◆ cy_tls_connect()

cy_rslt_t cy_tls_connect	(	cy_tls_context_t	context,
		cy_tls_endpoint_type_t	endpoint,
		uint32_t	timeout
	)

Performs a TLS handshake and connects to the server.

RootCA certificate will be used for peer certificate verification as below:

If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is disabled: a. By default, global RootCA certificate loaded will be used for verification. b. If context specific RootCA is set using CY_SOCKET_SO_TRUSTED_ROOTCA_CERTIFICATE socket option then context specific RootCA certificate will be used for verification.
If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is enabled: a. By default, RootCA certificates which is provisioned to secure element will be used. b. If socket option CY_SOCKET_SO_ROOTCA_CERTIFICATE_LOCATION is set with value CY_SOCKET_ROOTCA_RAM then
- RootCA attached to the context will take first preference.
- RootCA set as global will take the last preference.

Device certificate & keys will be loaded as below:

If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is disabled: a. If device certificate and keys are loaded by application/library using cy_tls_create_identity API and TLS identity set using socket option CY_SOCKET_SO_TLS_IDENTITY will be used for device certificate and keys. 2.If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is enabled: a. By default, device certificates and keys which are provisioned to secure element will be used. b. If socket option CY_SOCKET_SO_DEVICE_CERT_KEY_LOCATION is set with value CY_SOCKET_DEVICE_CERT_KEY_RAM then identity set to the TLS context will be used.

Parameters

[in]	context	Context handle for the TLS Layer created using cy_tls_create_context.
[in]	endpoint	Endpoint type for the TLS handshake.
[in]	timeout	Maximum amount of time to wait in milliseconds to complete TLS connection.

Returns: CY_RSLT_SUCCESS on success; an error code on failure. Important error code related to this API function is:
CY_RSLT_MODULE_TLS_ERROR

◆ cy_tls_send()

cy_rslt_t cy_tls_send	(	cy_tls_context_t	context,
		const unsigned char *	data,
		uint32_t	length,
		uint32_t	timeout,
		uint32_t *	bytes_sent
	)

Encrypts the given data and sends it over a secure connection.

Parameters

[in]	context	Context handle for TLS Layer created using cy_tls_create_context.
[in]	data	Byte array of data to be encrypted and then sent to the network.
[in]	length	Length in bytes of the write buffer.
[in]	timeout	Maximum amount of time to wait in milliseconds to complete send operation.
[out]	bytes_sent	Number of bytes sent.

Returns: CY_RSLT_SUCCESS on success; an error code on failure. On success, it also returns the number of bytes sent. Important error codes related to this API function are:
CY_RSLT_MODULE_TLS_BADARG
CY_RSLT_MODULE_TLS_ERROR

◆ cy_tls_recv()

cy_rslt_t cy_tls_recv	(	cy_tls_context_t	context,
		unsigned char *	buffer,
		uint32_t	length,
		uint32_t	timeout,
		uint32_t *	bytes_received
	)

Reads the encrypted data from the network, decrypts the data, and then stores it in the given buffer.

Parameters

[in]	context	Context handle for the TLS Layer created using cy_tls_create_context.
[out]	buffer	Byte array to store the decrypted data received from the network.
[in]	length	Length in bytes of the read buffer.
[in]	timeout	Maximum amount of time to wait in milliseconds to complete receive operation.
[out]	bytes_received	Number of bytes received.

Returns: CY_RSLT_SUCCESS on success; an error code on failure. On Success, it also returns the number of bytes received. Important error codes related to this API function are:
CY_RSLT_MODULE_TLS_BADARG
CY_RSLT_MODULE_TLS_ERROR

◆ cy_tls_delete_context()

cy_rslt_t cy_tls_delete_context ( cy_tls_context_t context )

Releases the resources allocated for the TLS connection.

Parameters

[in] context Context handle returned by the TLS Layer created using cy_tls_create_context.

Returns: CY_RSLT_SUCCESS on success; an error code on failure. Important error code related to this API function is:
CY_RSLT_MODULE_TLS_BADARG

◆ cy_tls_config_cert_profile_param()

cy_rslt_t cy_tls_config_cert_profile_param	(	cy_tls_md_type_t	mds_type,
		cy_tls_rsa_min_key_len_t	rsa_bit_len
	)

Configures a custom certificate profile using the message digest and RSA min key length.

Parameters

[in]	mds_type	Message digest type.
[in]	rsa_bit_len	Minimum RSA key length in bits.

Returns: CY_RSLT_SUCCESS on success; an error code on failure. Important error code related to this API function is:
CY_RSLT_MODULE_TLS_BADARG

◆ cy_tls_is_certificate_valid_x509()

cy_rslt_t cy_tls_is_certificate_valid_x509	(	const char *	certificate_data,
		const uint32_t	certificate_len
	)

Checks if given buffer is in valid certificate format.

Parameters

[in]	certificate_data	x509 certificate in PEM format. It should be a null-terminated string.
[in]	certificate_len	Length of the certificate excluding the 'null' terminator.

Returns: CY_RSLT_SUCCESS on success; an error code on failure.

General Description

Functions

Function Documentation

◆ cy_tls_init()

◆ cy_tls_deinit()

◆ cy_tls_load_global_root_ca_certificates()

◆ cy_tls_release_global_root_ca_certificates()

◆ cy_tls_create_identity()

◆ cy_tls_delete_identity()

◆ cy_tls_create_context()

◆ cy_tls_connect()

◆ cy_tls_send()

◆ cy_tls_recv()

◆ cy_tls_delete_context()

◆ cy_tls_config_cert_profile_param()

◆ cy_tls_is_certificate_valid_x509()