Functions

group group_cy_tls_functions

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.

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

note

  1. 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.

  2. 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.

Return

CY_RSLT_SUCCESS on success; an error code on failure.

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.

Return

CY_RSLT_SUCCESS on success; an error code on failure.

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.

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.

Return

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

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.

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.

Return

cy_rslt_t CY_RESULT_SUCCESS on success; an error code on failure.

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.

Return

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

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.

cy_rslt_t cy_tls_delete_identity(void *tls_identity)

Releases resources allocated by the cy_tls_create_identity API function.

Return

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

CY_RSLT_MODULE_TLS_BADARG

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

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.

Return

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

Parameters
  • [out] context: Context handle returned by the TLS layer.

  • [in] params: TLS parameters specified by the caller such as the server certificate.

cy_rslt_t cy_tls_connect(cy_tls_context_t context, cy_tls_endpoint_type_t endpoint)

Performs a TLS handshake and connects to the server.

Return

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

CY_RSLT_MODULE_TLS_ERROR

Parameters
  • [in] context: Context handle for the TLS Layer created using cy_tls_create_context.

  • [in] endpoint: Endpoint type for the TLS handshake.

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

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

Return

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

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.

  • [out] bytes_sent: Number of bytes sent.

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

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

Return

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

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.

  • [out] bytes_received: Number of bytes received.

cy_rslt_t cy_tls_delete_context(cy_tls_context_t context)

Releases the resources allocated for the TLS connection.

Return

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

CY_RSLT_MODULE_TLS_BADARG

Parameters

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.

Return

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

CY_RSLT_MODULE_TLS_BADARG

Parameters
  • [in] mds_type: Message digest type.

  • [in] rsa_bit_len: Minimum RSA key length in bits.