Secure Sockets Library - Secure Network Communication for IoT Applications

Overview

The secure sockets library provides APIs to create software that can send and/or receive data over the network using sockets. This library supports both secure and non-secure sockets, and abstracts the complexity involved in directly using network stack and security stack APIs. It supports both IPv4 and IPv6 addressing modes for UDP and TCP sockets.

The library has been designed to support different flavors of TCP/IP and security stacks. Currently, it supports two combinations:

• lwIP + Mbed TLS (for Wi-Fi and Ethernet kits on FreeRTOS)
• NetXDuo + NetXSecure (for CYW955913EVK-01 on ThreadX)

For the full API reference, see the Secure Sockets Reference Manual.

Features

• Wi-Fi and Ethernet connectivity - Supports both Wi-Fi and Ethernet connections with non-secure TCP and UDP sockets
• Secure TLS communication - Secure TCP (TLS) socket communication using Mbed TLS or NetXSecure library, supporting TLS 1.2 and TLS 1.3
• Dual-stack IPv4/IPv6 - Supports both IPv4 and IPv6 addressing, including link-local IPv6, UDP multicast, and broadcast
• Client and Server operations - Provides thread-safe APIs for both client and server modes, with synchronous and asynchronous receive, and asynchronous server accept
• PKCS integration - Integrated with PSA Lib through the PKCS interface to support secure client TCP (TLS) connections using device certificates and keys provisioned in the secure element
• Flexible socket options - Socket-option API to configure send/receive timeouts, callbacks for asynchronous mode, TCP keepalive parameters, certificates/keys, and TLS extensions

When to Use

Use the secure sockets library when your IoT application needs to:

• Establish secure (TLS) or non-secure TCP/UDP connections over Wi-Fi or Ethernet
• Communicate with cloud services (e.g., AWS IoT, Azure IoT) using TLS-secured connections
• Implement a TCP server that accepts client connections
• Send/receive UDP multicast or broadcast messages
• Leverage hardware-based secure element (PKCS) for TLS authentication on secure platforms such as CY8CKIT-064S0S2-4343W, CYW955913EVK-01, or PSOC™ Edge E84

Prerequisites

Hardware Requirements

This library runs on Infineon Wi-Fi- and Ethernet-capable device families:

• PSOC™ 6 with CYW4343W / CYW43012 / CYW4373 / CYW43439 / CYW43022 / CYW955513 connectivity
• PSOC™ 64 secure MCUs (for PKCS / secure-element TLS)
• XMC7200 with CYW43xxx connectivity
• CYW943907 / CYW954907 standalone Wi-Fi SoCs
• CYW955913 single-chip Wi-Fi + Bluetooth®
• PSOC™ Edge E84

The set of validated kits grows over time; see RELEASE.md for the specific kits validated in each release.

Software Requirements

Software and Tools	Version
ModusToolbox™ Software Environment	3.9
ModusToolbox™ Device Configurator	5.90
GCC Compiler	14.2.1
IAR Compiler	9.50.2
Arm Compiler 6	6.22
LLVM Compiler	22.1.0

Read Documentation First

• Secure Sockets Reference Manual - Complete API reference
• Connectivity Utilities API Documentation - Logging utilities (cy-log)

Choose Starting Template

Create an Empty application (always prefer starting from an Empty template).

Add Required Libraries

Depending on your kit and connectivity type, pull one of the following core libraries which will internally bring in secure-sockets and all other required dependencies:

• Wi-Fi kits (FreeRTOS + lwIP + Mbed TLS): wifi-core-freertos-lwip-mbedtls >= latest-v4.X - Pulls secure-sockets, wifi-connection-manager, FreeRTOS, lwIP, Mbed TLS, and other dependencies
• CYW955913EVK-01 kit (ThreadX + NetXDuo + NetXSecure): wifi-core-threadx-cat5 >= latest-v1.X - Pulls secure-sockets and other dependencies
• Ethernet kits (FreeRTOS + lwIP + Mbed TLS): ethernet-core-freertos-lwip-mbedtls >= latest-v2.X - Pulls secure-sockets, ethernet-connection-manager, FreeRTOS, lwIP, Mbed TLS, and other dependencies

Add the appropriate core library using the ModusToolbox™ Library Manager (available in the ModusToolbox™ for VS Code extension and the Eclipse IDE), or by creating the corresponding .mtb file in the application's deps folder and running make getlibs. This applies to secure-sockets latest-3.X and later. For example, for Wi-Fi kits:

# deps/wifi-core-freertos-lwip-mbedtls.mtb
https://github.com/Infineon/wifi-core-freertos-lwip-mbedtls#latest-v4.X#$$ASSET_REPO$$/wifi-core-freertos-lwip-mbedtls/latest-v4.X

Note: To use TLS version 1.3, upgrade wifi-core-freertos-lwip-mbedtls to latest-v2.X (supported on all platforms except CY8CKIT-064S0S2-4343W). On non-secure kits, Optiga-PKCS11 is not supported with wifi-core-freertos-lwip-mbedtls latest-v2.X.

Configure Makefile (if applicable)

For lwIP + Mbed TLS combination, add the following COMPONENTS to your project's Makefile:

COMPONENTS+=LWIP MBEDTLS

For NetXDuo + NetXSecure combination (CYW955913EVK-01 only), no additional COMPONENTS are required.

WPS support: To enable Wi-Fi Protected Setup (WPS) alongside the lwIP + Mbed TLS combination, add the WPS component to the Makefile:

COMPONENTS+=WPS MBEDTLS

Add Headers

• For non-secure connections, include only:

  #include "cy_secure_sockets.h"

• For secure (TLS) connections, include both:

  #include "cy_secure_sockets.h"
  #include "cy_tls.h"

Quick Start

This quick start demonstrates creating a non-secure TCP client socket that connects to a TCP server, sends a message, and receives a response. Follow these steps to get from an empty template to a working example:

Step 1: Create an Empty application in ModusToolbox™ and add the appropriate core library (e.g., wifi-core-freertos-lwip-mbedtls for Wi-Fi kits) using the Library Manager (or by creating the .mtb file in deps/), then run make getlibs.

Step 2: Add COMPONENTS+=LWIP MBEDTLS to the project Makefile (for lwIP + Mbed TLS combination).

Step 3: Include cy_secure_sockets.h in your source file.

Step 4: Add the following code to your main.c (see the Sample Code section below for a complete example).

Expected Outcome: The TCP client connects to the specified server, sends a message, and receives a response. See the Expected Outcome section below for details.

Sample Code

This section provides complete, runnable code examples for TCP client and TCP server use cases using FreeRTOS. Each example demonstrates proper initialization, connection handling, and error management.

FreeRTOS TCP Client Example

#include "cy_secure_sockets.h"
#include "cyabs_rtos.h"
#include <string.h>
#include <stdbool.h>
 
#define MAKE_IPV4_ADDRESS(a, b, c, d)  ((((uint32_t) d) << 24) | \
                                        (((uint32_t)  c) << 16) | \
                                        (((uint32_t)  b) << 8) |\
                                        ((uint32_t)   a))
 
/* Change the server IP address and port to match your TCP server. */
#define TCP_SERVER_IP_ADDRESS          MAKE_IPV4_ADDRESS(192, 168, 18, 9)
#define TCP_SERVER_PORT                (50007)
#define MAX_TCP_RECV_BUFFER_SIZE       (20)
#define RTOS_TASK_MILLISECONDS_TO_WAIT (1000)
 
cy_socket_t client_handle;
bool received_msg_from_server;
 
/* Callback to handle incoming messages from the TCP server. */
cy_rslt_t tcp_client_recv_handler(cy_socket_t socket_handle, void *arg)
{
    cy_rslt_t result;
    uint32_t bytes_received = 0;
    char rx_buffer[MAX_TCP_RECV_BUFFER_SIZE];
 
    result = cy_socket_recv(socket_handle, rx_buffer, MAX_TCP_RECV_BUFFER_SIZE,
                            CY_SOCKET_FLAGS_NONE, &bytes_received);
    received_msg_from_server = true;
    return result;
}
 
void tcp_client_task(void *arg)
{
    cy_rslt_t result;
    uint32_t bytes_sent = 0;
 
    cy_socket_sockaddr_t tcp_server_addr = {
        .ip_address.ip.v4 = TCP_SERVER_IP_ADDRESS,
        .ip_address.version = CY_SOCKET_IP_VER_V4,
        .port = TCP_SERVER_PORT
    };
 
    char tx_buffer[] = "Hello from TCP client";
 
    /* Initialize the Secure Sockets Library. */
    result = cy_socket_init();
 
    /* Create a TCP socket. */
    result = cy_socket_create(CY_SOCKET_DOMAIN_AF_INET, CY_SOCKET_TYPE_STREAM,
                              CY_SOCKET_IPPROTO_TCP, &client_handle);
 
    /* Register receive callback. */
    cy_socket_opt_callback_t tcp_recv_option = {
        .callback = tcp_client_recv_handler,
        .arg = NULL
    };
    result = cy_socket_setsockopt(client_handle, CY_SOCKET_SOL_SOCKET,
                                  CY_SOCKET_SO_RECEIVE_CALLBACK,
                                  &tcp_recv_option, sizeof(cy_socket_opt_callback_t));
 
    /* Connect to the TCP server. */
    result = cy_socket_connect(client_handle, &tcp_server_addr, sizeof(cy_socket_sockaddr_t));
 
    /* Send a message to the TCP server. */
    result = cy_socket_send(client_handle, tx_buffer, strlen(tx_buffer),
                            CY_SOCKET_FLAGS_NONE, &bytes_sent);
 
    /* Wait for a response from the server. */
    while (!received_msg_from_server)
    {
        cy_rtos_delay_milliseconds(RTOS_TASK_MILLISECONDS_TO_WAIT);
    }
}

FreeRTOS Secure TLS Client Example

#include "cy_secure_sockets.h"
#include "cy_tls.h"
#include <string.h>
 
/* Initialize with your TLS certificate. Must include the PEM header and footer. */
static const char tls_cert[] = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
static const char private_key[] = "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n";
 
void secure_tcp_client_task(void *arg)
{
    cy_rslt_t result;
    cy_socket_t socket_handle;
    void *tls_identity;
 
    cy_socket_tls_auth_mode_t tls_auth_mode = CY_SOCKET_TLS_VERIFY_REQUIRED;
 
    /* Initialize the Secure Sockets Library. */
    result = cy_socket_init();
 
    /* Create a secure TLS socket. */
    result = cy_socket_create(CY_SOCKET_DOMAIN_AF_INET, CY_SOCKET_TYPE_STREAM,
                              CY_SOCKET_IPPROTO_TLS, &socket_handle);
 
    /* Create a TLS identity using certificate and private key. */
    result = cy_tls_create_identity(tls_cert, strlen(tls_cert),
                                    private_key, strlen(private_key), &tls_identity);
 
    /* Set the TLS identity on the socket. */
    result = cy_socket_setsockopt(socket_handle, CY_SOCKET_SOL_TLS,
                                  CY_SOCKET_SO_TLS_IDENTITY,
                                  tls_identity, sizeof(tls_identity));
 
    /* Set the TLS authentication mode. */
    result = cy_socket_setsockopt(socket_handle, CY_SOCKET_SOL_TLS,
                                  CY_SOCKET_SO_TLS_AUTH_MODE,
                                  &tls_auth_mode, sizeof(cy_socket_tls_auth_mode_t));
 
    /* Proceed to connect, send, and receive as with a non-secure socket. */
}

FreeRTOS TCP Server Example

#include "cy_secure_sockets.h"
#include "cyabs_rtos.h"
#include <string.h>
#include <stdbool.h>
 
#define MAKE_IPV4_ADDRESS(a, b, c, d)     ((((uint32_t) d) << 24) | \
                                          (((uint32_t)  c) << 16) | \
                                          (((uint32_t)  b) << 8) |\
                                          ((uint32_t)   a))
 
/* Change the server IP address and port to match the TCP server address. */
#define TCP_SERVER_IP_ADDRESS                     MAKE_IPV4_ADDRESS(192, 168, 18, 9)
#define TCP_SERVER_PORT                           (50007)
#define TCP_SERVER_MAX_PENDING_CONNECTIONS        (3)
#define MAX_TCP_RECV_BUFFER_SIZE                  (20)
#define RTOS_TASK_MILLISECONDS_TO_WAIT            (1000)
 
cy_socket_t server_handle, client_handle;
bool send_msg_to_client;
 
/* Incoming TCP client connection handler. */
cy_rslt_t tcp_connection_handler(cy_socket_t socket_handle, void *arg)
{
    cy_socket_sockaddr_t client_addr;
    uint32_t client_addr_len;
 
    /* Accept a new incoming connection from a TCP client. */
    return cy_socket_accept(socket_handle, &client_addr, &client_addr_len, &client_handle);
}
 
/* Handle an incoming message from the TCP client. */
cy_rslt_t tcp_server_recv_handler(cy_socket_t socket_handle, void *arg)
{
    cy_rslt_t result;
    uint32_t bytes_received = 0;
    char rx_buffer[MAX_TCP_RECV_BUFFER_SIZE];
 
    result = cy_socket_recv(socket_handle, rx_buffer, MAX_TCP_RECV_BUFFER_SIZE,
                            CY_SOCKET_FLAGS_NONE, &bytes_received);
    send_msg_to_client = true;
    return result;
}
 
void tcp_server_task(void *arg)
{
    cy_rslt_t result;
    uint32_t bytes_sent = 0;
 
    cy_socket_sockaddr_t tcp_server_addr = {
        .ip_address.ip.v4 = TCP_SERVER_IP_ADDRESS,
        .ip_address.version = CY_SOCKET_IP_VER_V4,
        .port = TCP_SERVER_PORT
    };
 
    char tx_buffer[] = "Message to TCP client";
 
    /* Initialize the Secure Sockets Library. */
    result = cy_socket_init();
 
    /* Create a TCP socket (use CY_SOCKET_IPPROTO_TLS for a secure server). */
    result = cy_socket_create(CY_SOCKET_DOMAIN_AF_INET, CY_SOCKET_TYPE_STREAM,
                              CY_SOCKET_IPPROTO_TCP, &server_handle);
 
    /* Register the connection-request callback. */
    cy_socket_opt_callback_t tcp_connection_option = {
        .callback = tcp_connection_handler,
        .arg = NULL
    };
    result = cy_socket_setsockopt(server_handle, CY_SOCKET_SOL_SOCKET,
                                  CY_SOCKET_SO_CONNECT_REQUEST_CALLBACK,
                                  &tcp_connection_option, sizeof(cy_socket_opt_callback_t));
 
    /* Register the receive callback. */
    cy_socket_opt_callback_t tcp_recv_option = {
        .callback = tcp_server_recv_handler,
        .arg = NULL
    };
    result = cy_socket_setsockopt(server_handle, CY_SOCKET_SOL_SOCKET,
                                  CY_SOCKET_SO_RECEIVE_CALLBACK,
                                  &tcp_recv_option, sizeof(cy_socket_opt_callback_t));
 
    /* Bind and listen. */
    result = cy_socket_bind(server_handle, &tcp_server_addr, sizeof(tcp_server_addr));
    result = cy_socket_listen(server_handle, TCP_SERVER_MAX_PENDING_CONNECTIONS);
 
    for (;;)
    {
        if (send_msg_to_client)
        {
            result = cy_socket_send(client_handle, tx_buffer, strlen(tx_buffer),
                                    CY_SOCKET_FLAGS_NONE, &bytes_sent);
            send_msg_to_client = false;
        }
        cy_rtos_delay_milliseconds(RTOS_TASK_MILLISECONDS_TO_WAIT);
    }
}

FreeRTOS UDP Client Example

#include "cy_secure_sockets.h"
#include "cyabs_rtos.h"
#include <string.h>
#include <stdbool.h>
 
#define MAKE_IPV4_ADDRESS(a, b, c, d)     ((((uint32_t) d) << 24) | \
                                          (((uint32_t)  c) << 16) | \
                                          (((uint32_t)  b) << 8) |\
                                          ((uint32_t)   a))
 
#define UDP_SERVER_IP_ADDRESS                     MAKE_IPV4_ADDRESS(192, 168, 18, 9)
#define UDP_SERVER_PORT                           (50007)
#define MAX_UDP_RECV_BUFFER_SIZE                  (20)
#define RTOS_TASK_MILLISECONDS_TO_WAIT            (1000)
 
cy_socket_t client_handle;
bool received_msg_from_udp_server;
 
/* Handle an incoming message from the UDP server. */
cy_rslt_t udp_client_recv_handler(cy_socket_t socket_handle, void *arg)
{
    cy_rslt_t result;
    uint32_t bytes_received = 0;
    char rx_buffer[MAX_UDP_RECV_BUFFER_SIZE];
 
    result = cy_socket_recvfrom(socket_handle, rx_buffer, MAX_UDP_RECV_BUFFER_SIZE,
                                CY_SOCKET_FLAGS_NONE, NULL, NULL, &bytes_received);
    received_msg_from_udp_server = true;
    return result;
}
 
void udp_client_task(void *arg)
{
    cy_rslt_t result;
    uint32_t bytes_sent = 0;
 
    cy_socket_sockaddr_t udp_server_addr = {
        .ip_address.ip.v4 = UDP_SERVER_IP_ADDRESS,
        .ip_address.version = CY_SOCKET_IP_VER_V4,
        .port = UDP_SERVER_PORT
    };
 
    char tx_buffer[] = "Message to UDP server";
 
    /* Initialize the Secure Sockets Library. */
    result = cy_socket_init();
 
    /* Create a UDP socket. */
    result = cy_socket_create(CY_SOCKET_DOMAIN_AF_INET, CY_SOCKET_TYPE_DGRAM,
                              CY_SOCKET_IPPROTO_UDP, &client_handle);
 
    /* Register the receive callback. */
    cy_socket_opt_callback_t udp_recv_option = {
        .callback = udp_client_recv_handler,
        .arg = NULL
    };
    result = cy_socket_setsockopt(client_handle, CY_SOCKET_SOL_SOCKET,
                                  CY_SOCKET_SO_RECEIVE_CALLBACK,
                                  &udp_recv_option, sizeof(cy_socket_opt_callback_t));
 
    /* Send a datagram to the UDP server. */
    result = cy_socket_sendto(client_handle, tx_buffer, strlen(tx_buffer),
                              CY_SOCKET_FLAGS_NONE, &udp_server_addr,
                              sizeof(cy_socket_sockaddr_t), &bytes_sent);
 
    while (!received_msg_from_udp_server)
    {
        cy_rtos_delay_milliseconds(RTOS_TASK_MILLISECONDS_TO_WAIT);
    }
}

For additional use cases (TCP over IPv6, UDP server, IPv4/IPv6 multicast, broadcast, get-time-from-NTP, and PKCS-mode TLS connections for CY8CKIT-064S0S2-4343W and CYW955913EVK-01), see the code snippets in the Secure Sockets Reference Manual.

Expected Outcome

When you successfully run the Quick Start example, you should observe:

• Terminal Output:

  TCP client connected to server successfully
  Message sent to TCP server
  Response received from TCP server

• The client socket establishes a connection to the specified TCP server IP and port, sends a message, and receives the server's response via the registered callback.

Troubleshooting

• Socket re-use after disconnect (lwIP): When cy_socket_connect() returns CY_RSLT_MODULE_SECURE_SOCKETS_CLOSED, the socket handle cannot be reused. Call cy_socket_delete() to delete the socket and then cy_socket_create() to create a new one before retrying the connection.
• TLS connection takes ~25 seconds in PKCS mode with RSA keys: This is a known limitation of hardware crypto for RSA. Use ECDHE keys for faster client connections.
• IAR 9.40.2 build errors on Debug mode: If the application explicitly includes iar_dlmalloc.h, add --advanced_heap to LDFLAGS in the application Makefile.
• DTLS not supported: Datagram Transport Layer Security (DTLS) is not currently supported. Support will be added in a future release.
• XMC7200 TLS connections: Each TLS connection on XMC7200 kits requires 64K non-cacheable memory. By default, one TLS connection is supported. To support multiple TLS connections, update CM7_SRAM_NON_CACHE_RESERVE in bsps\<TARGET>\xmc7xxx_partition.h, replace ARM_MPU_REGION_SIZE_128KB with ARM_MPU_REGION_SIZE_256KB in the BSP startup file, update cm7_sram_non_cache_reserve in the linker script, and define CYCFG_MBEDTLS_BUFFER_SIZE (e.g., DEFINES+=CYCFG_MBEDTLS_BUFFER_SIZE=128*1024 for two connections).
• Debug logging: The library disables all debug log messages by default. To enable, add DEFINES+=ENABLE_SECURE_SOCKETS_LOGS to the Makefile and call cy_log_init() from the connectivity-utilities library.
• **cy_socket_listen() fails on more than one socket:** The default lwIP configuration sets MEMP_NUM_TCP_PCB_LISTEN to 1, so calling cy_socket_listen() on a second socket fails with CY_RSLT_MODULE_SECURE_SOCKETS_NOMEM. Increase MEMP_NUM_TCP_PCB_LISTEN in lwipopts.h to support more than one server socket.
• **cy_socket_recv() blocks for ~10 seconds:** cy_socket_recv() returns after the default 10-second receive timeout if the requested number of bytes is not available. Change the timeout with cy_socket_setsockopt() using the CY_SOCKET_SO_RCVTIMEO option.
• TCP packets are dropped: If the application consumes data more slowly than it arrives, the network stack's receive queue can overflow. Tune DEFAULT_TCP_RECVMBOX_SIZE and TCP_WND in lwipopts.h so the TCP window reaches zero when the receive queue is full.
• **cy_socket_create() fails with CY_RSLT_MODULE_SECURE_SOCKETS_NOMEM:** The maximum number of TCP/UDP sockets is limited by the network stack. Increase MEMP_NUM_TCP_PCB / MEMP_NUM_UDP_PCB in lwipopts.h (their total must not exceed MEMP_NUM_NETCONN).
• **cy_socket_sendto() with a multicast destination fails on the SoftAP interface:** Multicast over SoftAP fails with CY_RSLT_MODULE_SECURE_SOCKETS_ERROR_ROUTING if the socket is not bound to the SoftAP interface. Bind it using cy_socket_setsockopt() with the CY_SOCKET_SO_BINDTODEVICE option.

Related Code Examples

• ModusToolbox™ Code Examples

Configuration Reference

This section provides comprehensive documentation of all configuration parameters for the secure sockets library.

TCP/IP and Security Stack Selection

The library supports two TCP/IP + security stack combinations:

Combination	COMPONENTS Required	Supported Platforms
lwIP + Mbed TLS	COMPONENTS+=LWIP MBEDTLS	All platforms except CYW955913EVK-01 (ThreadX)
NetXDuo + NetXSecure	None	CYW955913EVK-01 only

Stack Size

The default stack size is 7 KB (7*1024). To customize:

DEFINES+=SECURE_SOCKETS_THREAD_STACKSIZE=8*1024

Send and Receive Timeout

Default send and receive timeout is 10 seconds for newly created sockets. Configure using:

• CY_SOCKET_SO_SNDTIMEO - Send timeout (via cy_socket_setsockopt)
• CY_SOCKET_SO_RCVTIMEO - Receive timeout (via cy_socket_setsockopt)

Validity Period Verification

The default Mbed TLS configuration disables certificate validity period verification. To enable:

1. Enable MBEDTLS_HAVE_TIME_DATE in mbedtls_user_config.h
   • See mbedtls_user_config.h for Wi-Fi
   • See mbedtls_user_config.h for Ethernet
2. Set the system time prior to cy_socket_connect() using cyhal_rtc_init(), cyhal_rtc_write(), and cy_set_rtc_instance(). See time support details.

PKCS/Non-PKCS Mode

The library can be built using PKCS and Non-PKCS mode on secure platforms. In PKCS mode, certificates and keys are provisioned in the secure element and used during TLS handshake. In Non-PKCS mode, certificates/keys are passed from the application stored in flash/RAM.

Non-PKCS Mode (Secure Platforms)

1. Provision the kit. See Device provisioning steps.
2. Add the following to the Makefile:

   DEFINES+=CY_TFM_PSA_SUPPORTED TFM_MULTI_CORE_NS_OS

PKCS Mode - Secure Kits

CYW955913EVK-01 Kit

The CYW955913EVK-01 has an inbuilt secure element holding a unique device private key. A device certificate must be generated using the CSR from the device via the edgeprotect tool.

Dependencies:

• aws-iot-device-sdk-embedded-C.mtb: https://github.com/aws/aws-iot-device-sdk-embedded-C/#202103.00#$$ASSET_REPO$$/aws-iot-device-sdk-embedded-C/202103.00

Enable PKCS mode:

DEFINES+= CY_SECURE_SOCKETS_PKCS_SUPPORT

Note: To use the private key from the secure element, pass private_key as NULL and private_key_len as 0 when calling cy_tls_create_identity.

CY8CKIT-064S0S2-4343W

Dependencies:

• aws-iot-device-sdk-embedded-C.mtb: https://github.com/aws/aws-iot-device-sdk-embedded-C/#202103.00#$$ASSET_REPO$$/aws-iot-device-sdk-embedded-C/202103.00
• freertos-pkcs11-psa.mtb: https://github.com/Linaro/freertos-pkcs11-psa/#80292d24f4978891b0fd35feeb5f1d6f6f0fff06#$$ASSET_REPO$$/freertos-pkcs11-psa/master

Enable PKCS mode:

DEFINES+=CY_TFM_PSA_SUPPORTED TFM_MULTI_CORE_NS_OS CY_SECURE_SOCKETS_PKCS_SUPPORT

Trusted firmware include path:

INCLUDES=$(SEARCH_trusted-firmware-m)/COMPONENT_TFM_NS_INTERFACE/include
INCLUDES+=./libs/trusted-firmware-m/COMPONENT_TFM_NS_INTERFACE/include

PSOC™ Edge E84 Evaluation Kit

The PSOCE84 kit features ARM TrustZone support with Trusted Firmware (TF-M) on the secure side and connectivity middleware on the non-secure side.

1. Pull ifx-tf-m to the secure project and ifx-tf-m-ns to the non-secure project using library manager.
2. Add to non-secure project Makefile:

   DEFINES += CY_TFM_PSA_SUPPORTED

3. Add PSA & MBEDTLS configuration defines to non-secure project Makefile.

   If the application pulls the wifi-core-freertos-lwip-mbedtls/latest-v3.X library, use the following:

   DEFINES+=MBEDTLS_CONFIG_FILE='"mbedtls/mbedtls_config.h"'
   DEFINES+=MBEDTLS_USER_CONFIG_FILE='"configs/mbedtls_user_config.h"'
   DEFINES+=MBEDTLS_PSA_CRYPTO_CONFIG_FILE='"configs/ifx_psa_crypto_config.h"'
   DEFINES+=IFX_PSA_MXCRYPTO_USER_CONFIG_FILE='"configs/ifx_psa_mxcrypto_config.h"'

   If the application pulls the wifi-core-freertos-lwip-mbedtls/latest-v4.X library, use the following:

   DEFINES+=IFX_TF_PSA IFX_TF_PSA_CRYPTO
   DEFINES+=MBEDTLS_CONFIG_FILE='"mbedtls/mbedtls_config.h"'
   DEFINES+=MBEDTLS_USER_CONFIG_FILE='"configs/mbedtls_user_config.h"'
   # PSA configuration of mbedtls library.
   DEFINES+=TF_PSA_CRYPTO_CONFIG_FILE='"configs/tf_psa_crypto_config.h"'
   DEFINES+=TF_PSA_CRYPTO_USER_CONFIG_FILE='"configs/tf_psa_crypto_user_config.h"'

4. Add TFM configuration to secure project Makefile.

   If the application pulls the wifi-core-freertos-lwip-mbedtls/latest-v3.X library, use the following:

   TFM_CONFIGURE_EXT_OPTIONS+= -DTFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH=configs/ifx_psa_crypto_config.h (provide full path)
   TFM_CONFIGURE_EXT_OPTIONS+= -DIFX_PROJECT_CONFIG_PATH=configs/ifx_tfm_config.h (provide full path)

   If the application pulls the wifi-core-freertos-lwip-mbedtls/latest-v4.X library, use the following:

   TFM_CONFIGURE_EXT_OPTIONS+= -DIFX_MBEDTLS_CONFIG_PATH=configs/tf_psa_crypto_config.h (provide full path)
   TFM_CONFIGURE_EXT_OPTIONS+= -DIFX_PROJECT_CONFIG_PATH=configs/ifx_tfm_config.h (provide full path)

5. To change from TF-M medium profile to large (for additional crypto algorithms), open "edge protect configurator", change profile from medium to large, save and close.

PKCS Mode - Non-Secure Kits (Optiga)

Dependencies:

• aws-iot-device-sdk-embedded-C.mtb: https://github.com/aws/aws-iot-device-sdk-embedded-C/#202103.00#$$ASSET_REPO$$/aws-iot-device-sdk-embedded-C/202103.00
• optiga-trust-m.mtb: https://github.com/Infineon/optiga-trust-m#release-v5.3.0#$$ASSET_REPO$$/optiga-trust-m/release-v5.3.0

Enable PKCS mode:

COMPONENTS+= OPTIGA
DEFINES+= $(OPTIGAFLAGS) CY_SECURE_SOCKETS_PKCS_SUPPORT
OPTIGAFLAGS=OPTIGA_LIB_EXTERNAL='"optiga_config.h"'

For CYW955913EVK-01 with Optiga, add:

MBEDTLSFLAGS = MBEDTLS_USER_CONFIG_FILE='"mbedtls_default_config.h"'
DEFINES+= $(MBEDTLSFLAGS) $(OPTIGAFLAGS) CY_SECURE_SOCKETS_PKCS_SUPPORT

PKCS11 Configuration

A pre-defined core_pkcs11_config.h is bundled with the library. Copy it to the top-level application directory to customize.

• Secure Kits: CYW955913EVK-01 and CY8CKIT-064S0S2-4343W support only SHA-256 hashing algorithm for PKCS11.
• Non-Secure Kits (Optiga): The library uses 3 OID values from the Optiga chip. Default OIDs (configurable via Makefile defines):
  • Device private key: LABEL_DEVICE_PRIVATE_KEY_FOR_TLS (0xE0F0)
  • Device certificate: LABEL_DEVICE_CERTIFICATE_FOR_TLS (0xE0E0)
  • Root certificate: LABEL_ROOT_CERTIFICATE (0xE0E8)

Note: Optiga-trust-m has a limitation on the maximum size of Public Key Certificate/Device Certificate. Using a certificate larger than 1728 bytes may result in erroneous outputs.

Decoding Error Codes

Secure Sockets Library APIs return cy_rslt_t values. On error, the returned value encodes a module base, a type, and a library-specific error code in a single 32-bit integer. The error base for this library is CY_RSLT_SECURE_SOCKETS_ERR_BASE = 0x082A0000, and each error is defined as CY_RSLT_SECURE_SOCKETS_ERR_BASE + <offset>.

To decode a returned error, subtract the base and look up the offset in cy_secure_sockets_error.h. For example, 0x082A0003 - 0x082A0000 = 3, which corresponds to CY_RSLT_MODULE_SECURE_SOCKETS_NOMEM. See the Secure Sockets Reference Manual (Secure Sockets Results group) for the full list of error constants and their descriptions.

Industry Standards and Compliance

Communication Standards:

• TLS 1.2 and TLS 1.3 - Transport Layer Security for secure socket communication
• TCP/IP (RFC 793, RFC 791) - Transmission Control Protocol / Internet Protocol
• UDP (RFC 768) - User Datagram Protocol
• IPv4 (RFC 791) and IPv6 (RFC 8200) - Internet Protocol addressing

Release Notes and Changelog

• RELEASE.md - Detailed release notes for all versions

License

This library is provided under Infineon software license terms. Depending on the enabled features, it optionally pulls third-party components governed by their own respective license terms: the AWS IoT Device SDK for Embedded-C and Linaro freertos-pkcs11-psa (for PKCS mode on secure kits), optiga-trust-m (for OPTIGA-based PKCS on non-secure kits), and the Mbed TLS or NetXSecure security stacks (pulled via the wifi-core / ethernet-core bundles). You are responsible for reviewing and accepting all applicable third-party license terms.

• LICENSE

Copyright

(c) 2026, Infineon Technologies AG, or an affiliate of Infineon

Technologies AG. All rights reserved.