Secure Sockets

General Description

API Reference

 Secure Sockets results/error codes
 Secure Sockets Library APIs return results of type cy_rslt_t and consist of three parts:
 

Macros

#define CY_SOCKET_INVALID_HANDLE   ( ( cy_socket_t ) ~0U )
 Assigned to a cy_socket_t variable when the socket handle is not valid.
 
#define DEFAULT_RECV_TIMEOUT_IN_MSEC   10000
 Default socket receive timeout value, in milliseconds.
 
#define DEFAULT_SEND_TIMEOUT_IN_MSEC   10000
 Default socket send timeout value, in milliseconds.
 
#define ARP_WAIT_TIME_IN_MSEC   30000
 Maximum time in milliseconds the cy_socket_sendto function waits for MAC address-to-IP address resolution.
 
#define CY_SOCKET_DOMAIN_AF_INET   ( 2 )
 Domain option for cy_socket_create() - IPv4 internet protocols.
 
#define CY_SOCKET_DOMAIN_AF_INET6   ( 10 )
 Domain option for cy_socket_create() - IPv6 internet protocols.
 
#define CY_SOCKET_TYPE_DGRAM   ( 2 )
 Type parameter for cy_socket_create() - Datagram.
 
#define CY_SOCKET_TYPE_STREAM   ( 1 )
 Type parameter for cy_socket_create() - Byte-stream.
 
#define CY_SOCKET_IPPROTO_TCP   ( 1 )
 Protocol option for cy_socket_create() - TCP.
 
#define CY_SOCKET_IPPROTO_UDP   ( 2 )
 Protocol option for cy_socket_create() - UDP.
 
#define CY_SOCKET_IPPROTO_TLS   ( 3 )
 Protocol option for cy_socket_create() - TLS.
 
#define CY_SOCKET_SOL_SOCKET   ( 1 )
 Level option for cy_socket_setsockopt() - Socket-level option.
 
#define CY_SOCKET_SOL_TCP   ( 2 )
 Level option for cy_socket_setsockopt() - TCP protocol-level option.
 
#define CY_SOCKET_SOL_TLS   ( 3 )
 Level option for cy_socket_setsockopt() - TLS protocol-level option.
 
#define CY_SOCKET_SOL_IP   ( 4 )
 Level option for cy_socket_setsockopt() - IP protocol-level option.
 
#define CY_SOCKET_SO_RCVTIMEO   ( 0 )
 Set the receive timeout in milliseconds. More...
 
#define CY_SOCKET_SO_SNDTIMEO   ( 1 )
 Set the send timeout in milliseconds. More...
 
#define CY_SOCKET_SO_NONBLOCK   ( 2 )
 Set the blocking status of socket API function calls. More...
 
#define CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE   ( 3 )
 Enable/disable the TCP keepalive mechanism on the socket. More...
 
#define CY_SOCKET_SO_TCP_KEEPALIVE_INTERVAL   ( 4 )
 Set the interval in milliseconds between TCP keepalive probes. More...
 
#define CY_SOCKET_SO_TCP_KEEPALIVE_COUNT   ( 5 )
 Set the maximum number of TCP keepalive probes to be sent before giving up and killing the connection if no response is obtained from the other end. More...
 
#define CY_SOCKET_SO_TCP_KEEPALIVE_IDLE_TIME   ( 6 )
 Set the duration for which the connection needs to be idle (in milliseconds) before TCP begins sending out keepalive probes. More...
 
#define CY_SOCKET_SO_CONNECT_REQUEST_CALLBACK   ( 7 )
 Set the callback to be called upon an incoming client connection request. More...
 
#define CY_SOCKET_SO_RECEIVE_CALLBACK   ( 8 )
 Set the callback to be called when the socket has received data. More...
 
#define CY_SOCKET_SO_DISCONNECT_CALLBACK   ( 9 )
 Set the callback to be called when the socket is disconnected. More...
 
#define CY_SOCKET_SO_NWRITE   ( 10 )
 Get the number of bytes pending to be sent by the protocol. More...
 
#define CY_SOCKET_SO_TCP_USER_TIMEOUT   ( 11 )
 Set the user timeout value that controls the duration transmitted data may remain unacknowledged before a connection is forcefully closed. More...
 
#define CY_SOCKET_SO_TRUSTED_ROOTCA_CERTIFICATE   ( 12 )
 Set a RootCA certificate specific to the socket, in PEM format. More...
 
#define CY_SOCKET_SO_TLS_IDENTITY   ( 13 )
 Set the TLS identity. More...
 
#define CY_SOCKET_SO_SERVER_NAME_INDICATION   ( 14 )
 Set the hostname to be used for the TLS server name indication (SNI) extension of TLS ClientHello. More...
 
#define CY_SOCKET_SO_ALPN_PROTOCOLS   ( 15 )
 Set the application protocol list to be included in TLS ClientHello. More...
 
#define CY_SOCKET_SO_TLS_AUTH_MODE   ( 16 )
 Set the TLS authenticate mode. More...
 
#define CY_SOCKET_SO_TLS_MFL   ( 17 )
 Set the TLS maximum fragment length. More...
 
#define CY_SOCKET_SO_JOIN_MULTICAST_GROUP   ( 18 )
 Join an IPv4 (or) IPv6 multicast group. More...
 
#define CY_SOCKET_SO_LEAVE_MULTICAST_GROUP   ( 19 )
 Leave an IPv4 (or) IPv6 multicast group. More...
 
#define CY_SOCKET_SO_IP_MULTICAST_TTL   ( 20 )
 Set the time-to-live value of outgoing multicast packets for this socket. More...
 
#define CY_SOCKET_SO_BROADCAST   ( 21 )
 Enable/disable sending and receiving broadcast messages on the socket. More...
 
#define CY_SOCKET_SO_BINDTODEVICE   ( 22 )
 Set the network interface to be used for sending and receiving data on the socket. More...
 
#define CY_SOCKET_SO_IP_TOS   ( 23 )
 Set the Type-Of-Service (TOS) field that is sent with every IP packet originating from this socket. More...
 
#define CY_SOCKET_SO_BYTES_AVAILABLE   ( 24 )
 Get the number of bytes immediately available for reading. More...
 
#define CY_SOCKET_SO_TCP_NODELAY   ( 25 )
 Enable/disable TCP no delay socket option. More...
 
#define CY_SOCKET_SO_LOCALADDR   ( 26 )
 Get the local address details for the socket. More...
 
#define CY_SOCKET_SO_PEERADDR   ( 27 )
 Get the peer address details for the socket. More...
 
#define CY_SOCKET_ROOTCA_SECURE_STORAGE   ( 0x0 )
 Use RootCA certificate which is provisioned.
 
#define CY_SOCKET_ROOTCA_RAM   ( 0x1 )
 Use RootCA certificate which is provided from application.
 
#define CY_SOCKET_SO_ROOTCA_CERTIFICATE_LOCATION   (26)
 Set the RootCA certificate location. More...
 
#define CY_SOCKET_DEVICE_CERT_KEY_SECURE_STORAGE   ( 0x0 )
 Use device certificate and keys which are provisioned.
 
#define CY_SOCKET_DEVICE_CERT_KEY_RAM   ( 0x1 )
 Use device certificate and keys which are provided from application.
 
#define CY_SOCKET_SO_DEVICE_CERT_KEY_LOCATION   (27)
 Set the device certificate and key location. More...
 
#define CY_SOCKET_FLAGS_NONE   ( 0x0 )
 cy_socket_send() input flags - No flag.
 
#define CY_SOCKET_FLAGS_MORE   ( 0x1 )
 cy_socket_send() input flags - The caller indicates that there is additional data to be sent. More...
 
#define CY_SOCKET_FLAGS_RECVFROM_NONE   ( 0x0 )
 cy_socket_recvfrom() input flags - No flag.
 
#define CY_SOCKET_FLAGS_RECVFROM_SRC_FILTER   ( 0x1 )
 cy_socket_recvfrom() input flags - Used for filtering of input packets. More...
 
#define CY_SOCKET_POLL_READ   ( 1 )
 cy_socket_poll() input flags - Check for pending data. More...
 
#define CY_SOCKET_POLL_WRITE   ( 2 )
 cy_socket_poll() input flags - Check whether write is possible.
 
#define CY_SOCKET_SHUT_RD   ( 0x1 )
 Option for the "how" parameter of cy_socket_shutdown() - Disables further receive operations.
 
#define CY_SOCKET_SHUT_WR   ( 0x2 )
 Option for the "how" parameter of cy_socket_shutdown() - Disables further send operations.
 
#define CY_SOCKET_SHUT_RDWR   ( CY_SOCKET_SHUT_RD | CY_SOCKET_SHUT_WR )
 Option for the "how" parameter of cy_socket_shutdown() - Disables further send and receive. More...
 
#define CY_SOCKET_NEVER_TIMEOUT   ( 0xFFFFFFFFU )
 Never timeout.
 

Macro Definition Documentation

◆ CY_SOCKET_SO_RCVTIMEO

#define CY_SOCKET_SO_RCVTIMEO   ( 0 )

Set the receive timeout in milliseconds.

Arguments related to this optname:

Note
Configuring the receive timeout value on a server socket impacts the cy_socket_accept() API function. If the client does not send a connect request within the timeout, cy_socket_accept() returns the CY_RSLT_MODULE_SECURE_SOCKETS_TIMEOUT error.

◆ CY_SOCKET_SO_SNDTIMEO

#define CY_SOCKET_SO_SNDTIMEO   ( 1 )

Set the send timeout in milliseconds.

Arguments related to this optname:

◆ CY_SOCKET_SO_NONBLOCK

#define CY_SOCKET_SO_NONBLOCK   ( 2 )

Set the blocking status of socket API function calls.

This option is currently not supported; will be supported in a future release.

Arguments related to this optname:

  • Option value: Pointer holding the blocking status in uint8_t type. Value "1" indicates blocking status to non-blocking. Value "0" indicates blocking status to blocking.
  • Level: CY_SOCKET_SOL_SOCKET

◆ CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE

#define CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE   ( 3 )

Enable/disable the TCP keepalive mechanism on the socket.

Arguments related to this optname:

  • Option value: Pointer holding the keepalive configuration in int type. Value "1" indicates enable TCP keepalive. Value "0" indicates disable TCP keepalive.
  • Level: CY_SOCKET_SOL_SOCKET

◆ CY_SOCKET_SO_TCP_KEEPALIVE_INTERVAL

#define CY_SOCKET_SO_TCP_KEEPALIVE_INTERVAL   ( 4 )

Set the interval in milliseconds between TCP keepalive probes.

Keepalives are sent only when the feature is enabled with the CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE socket option.

Arguments related to this optname:

  • Option value: Pointer holding value of the keepalive interval in uint32_t type.
  • Level: CY_SOCKET_SOL_TCP

◆ CY_SOCKET_SO_TCP_KEEPALIVE_COUNT

#define CY_SOCKET_SO_TCP_KEEPALIVE_COUNT   ( 5 )

Set the maximum number of TCP keepalive probes to be sent before giving up and killing the connection if no response is obtained from the other end.

Keepalives are sent only when the feature is enabled with the CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE socket option.

Arguments related to this optname:

  • Option value: Pointer holding the value of maximum keepalive probe count in uint32_t type.
  • Level: CY_SOCKET_SOL_TCP

◆ CY_SOCKET_SO_TCP_KEEPALIVE_IDLE_TIME

#define CY_SOCKET_SO_TCP_KEEPALIVE_IDLE_TIME   ( 6 )

Set the duration for which the connection needs to be idle (in milliseconds) before TCP begins sending out keepalive probes.

Keepalive probes are sent only when the feature is enabled with CY_SOCKET_SO_TCP_KEEPALIVE_ENABLE socket option.

Arguments related to this optname:

  • Option value: Pointer holding the value of keepalive idle time in uint32_t type.
  • Level: CY_SOCKET_SOL_TCP

◆ CY_SOCKET_SO_CONNECT_REQUEST_CALLBACK

#define CY_SOCKET_SO_CONNECT_REQUEST_CALLBACK   ( 7 )

Set the callback to be called upon an incoming client connection request.

This option is supported only for TCP server sockets. The callback function registered with this option runs in the secure sockets worker thread context. This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

◆ CY_SOCKET_SO_RECEIVE_CALLBACK

#define CY_SOCKET_SO_RECEIVE_CALLBACK   ( 8 )

Set the callback to be called when the socket has received data.

The callback function registered with this option runs in the secure sockets worker thread context. This option is not supported in cy_socket_getsockopt.

Note
The registered receive callback function is invoked when a network packet is received from the network stack; therefore, this callback is invoked per network packet. If the data in the packet is consumed partially, the secure sockets library doesn't provide another callback for the remaining data in that packet. Therefore, it is recommended to read the entire network packet by providing a buffer of MTU size (1460 bytes) to the cy_socket_recv function.

Arguments related to this optname:

◆ CY_SOCKET_SO_DISCONNECT_CALLBACK

#define CY_SOCKET_SO_DISCONNECT_CALLBACK   ( 9 )

Set the callback to be called when the socket is disconnected.

This option is supported only for TCP sockets. The callback function registered with this option runs in the secure sockets worker thread context. This option is not supported in cy_socket_getsockopt.

Note
This callback is invoked whenever the peer disconnects. In the callback, cy_socket_disconnect should be invoked. This callback will not be invoked during self-initiated disconnections, i.e., when cy_socket_disconnect is called by self.

Arguments related to this optname:

◆ CY_SOCKET_SO_NWRITE

#define CY_SOCKET_SO_NWRITE   ( 10 )

Get the number of bytes pending to be sent by the protocol.

This option is used only with cy_socket_getsockopt. This option is currently not supported; will be supported in a future release.

Arguments related to this optname:

  • Option value: Pointer to the uint32_t type into which the API function fills the number of bytes.
  • Level: CY_SOCKET_SOL_SOCKET

◆ CY_SOCKET_SO_TCP_USER_TIMEOUT

#define CY_SOCKET_SO_TCP_USER_TIMEOUT   ( 11 )

Set the user timeout value that controls the duration transmitted data may remain unacknowledged before a connection is forcefully closed.

This option is currently not supported; will be supported in a future release.

Arguments related to this optname:

  • Option value: Pointer holding the timeout value in uint32_t type.
  • Level: CY_SOCKET_SOL_TCP

◆ CY_SOCKET_SO_TRUSTED_ROOTCA_CERTIFICATE

#define CY_SOCKET_SO_TRUSTED_ROOTCA_CERTIFICATE   ( 12 )

Set a RootCA certificate specific to the socket, in PEM format.

By default, the RootCA certificates loaded with cy_tls_load_global_root_ca_certificates are used to validate the peer's certificate. If a specific RootCA needs to be used for a socket, this socket option should be used to configure a connection-specific RootCA.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

  • Option value: Pointer to a buffer (char array) holding the certificate data.
  • Level: CY_SOCKET_SOL_TLS

◆ CY_SOCKET_SO_TLS_IDENTITY

#define CY_SOCKET_SO_TLS_IDENTITY   ( 13 )

Set the TLS identity.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

◆ CY_SOCKET_SO_SERVER_NAME_INDICATION

#define CY_SOCKET_SO_SERVER_NAME_INDICATION   ( 14 )

Set the hostname to be used for the TLS server name indication (SNI) extension of TLS ClientHello.

Arguments related to this optname:

  • Option value: Pointer to the stream of bytes (char array) holding the hostname.
  • Level: CY_SOCKET_SOL_TLS

◆ CY_SOCKET_SO_ALPN_PROTOCOLS

#define CY_SOCKET_SO_ALPN_PROTOCOLS   ( 15 )

Set the application protocol list to be included in TLS ClientHello.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

  • Option value: Pointer to the stream of bytes (char array) with protocol names separated by comma. e.g., "h2-16,h2-15,h2-14,h2,spdy/3.1,http/1.1"
  • Level: CY_SOCKET_SOL_TLS

◆ CY_SOCKET_SO_TLS_AUTH_MODE

#define CY_SOCKET_SO_TLS_AUTH_MODE   ( 16 )

Set the TLS authenticate mode.

Arguments related to this optname:

◆ CY_SOCKET_SO_TLS_MFL

#define CY_SOCKET_SO_TLS_MFL   ( 17 )

Set the TLS maximum fragment length.

Arguments related to this optname:

◆ CY_SOCKET_SO_JOIN_MULTICAST_GROUP

#define CY_SOCKET_SO_JOIN_MULTICAST_GROUP   ( 18 )

Join an IPv4 (or) IPv6 multicast group.

This option is not supported in cy_socket_getsockopt.

Note
  1. This implementation supports up to 10 multicast groups in total, and across the sockets. This is due to the underlying Wi-Fi host driver (WHD) limitation.
  2. The maximum number of IPv4 and IPv6 multicast groups to be supported can be configured using the configuration options provided by the network stack. However, if the total count of both IPv4 and IPv6 multicast groups is more than 10, any attempts to join a new multicast group will fail.

Arguments related to this optname:

◆ CY_SOCKET_SO_LEAVE_MULTICAST_GROUP

#define CY_SOCKET_SO_LEAVE_MULTICAST_GROUP   ( 19 )

Leave an IPv4 (or) IPv6 multicast group.

This option is not supported in cy_socket_getsockopt.

Arguments related to this optname:

◆ CY_SOCKET_SO_IP_MULTICAST_TTL

#define CY_SOCKET_SO_IP_MULTICAST_TTL   ( 20 )

Set the time-to-live value of outgoing multicast packets for this socket.

Arguments related to this optname:

  • Option value: Pointer holding the time-to-live value in uint8_t type. The value of this socket option should be in the range 0 <= value <= 255. For IPv4, this value is measured in seconds; for IPv6, it is measured in hop limit.
  • Level: CY_SOCKET_SOL_IP

◆ CY_SOCKET_SO_BROADCAST

#define CY_SOCKET_SO_BROADCAST   ( 21 )

Enable/disable sending and receiving broadcast messages on the socket.

Note
Use this socket option only when broadcast filter is enabled in the network stack configuration. If disabled, broadcast messages cannot be controlled with this socket option.

Arguments related to this optname:

  • Option value: Pointer holding the uint8_t value. Value "1" enables broadcast messages. Value "0" disables broadcast messages.
  • Level: CY_SOCKET_SOL_SOCKET

◆ CY_SOCKET_SO_BINDTODEVICE

#define CY_SOCKET_SO_BINDTODEVICE   ( 22 )

Set the network interface to be used for sending and receiving data on the socket.

This socket option can be called more than once for a socket to change the interface it's bound to.

Arguments related to this optname:

◆ CY_SOCKET_SO_IP_TOS

#define CY_SOCKET_SO_IP_TOS   ( 23 )

Set the Type-Of-Service (TOS) field that is sent with every IP packet originating from this socket.

Arguments related to this optname:

  • Option value: Pointer holding the type of service value in uint8_t type. The value of this socket option should be in the range 0 <= value <= 255.
  • Level: CY_SOCKET_SOL_IP

◆ CY_SOCKET_SO_BYTES_AVAILABLE

#define CY_SOCKET_SO_BYTES_AVAILABLE   ( 24 )

Get the number of bytes immediately available for reading.

Arguments related to this optname:

  • Option value: Pointer to the uint32_t type into which the API function fills the number of bytes available for reading.
  • Level: CY_SOCKET_SOL_SOCKET

◆ CY_SOCKET_SO_TCP_NODELAY

#define CY_SOCKET_SO_TCP_NODELAY   ( 25 )

Enable/disable TCP no delay socket option.

If this option is enabled, Nagle's algorithm is disabled. If disabled, data packets are sent as soon as possible, even if there is only a small amount of data. If enabled, data is buffered until there is a sufficient amount to send out.

Arguments related to this optname:

  • Option value: Pointer holding the uint8_t value. Value "0" enables Nagle's algorithm. Value "1" disables Nagle's algorithm.
  • Level: CY_SOCKET_SOL_TCP

◆ CY_SOCKET_SO_LOCALADDR

#define CY_SOCKET_SO_LOCALADDR   ( 26 )

Get the local address details for the socket.

Arguments related to this optname:

◆ CY_SOCKET_SO_PEERADDR

#define CY_SOCKET_SO_PEERADDR   ( 27 )

Get the peer address details for the socket.

Arguments related to this optname:

◆ CY_SOCKET_SO_ROOTCA_CERTIFICATE_LOCATION

#define CY_SOCKET_SO_ROOTCA_CERTIFICATE_LOCATION   (26)

Set the RootCA certificate location.

If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is enabled, RootCA will be read from the secure element by default. To override default behaviour, set this socket option.

Arguments related to this optname:

◆ CY_SOCKET_SO_DEVICE_CERT_KEY_LOCATION

#define CY_SOCKET_SO_DEVICE_CERT_KEY_LOCATION   (27)

Set the device certificate and key location.

If CY_SECURE_SOCKETS_PKCS_SUPPORT flag is enabled, the device certificate and keys will be read from the secure element by default. To override default behaviour, set this socket option.

Arguments related to this optname:

◆ CY_SOCKET_FLAGS_MORE

#define CY_SOCKET_FLAGS_MORE   ( 0x1 )

cy_socket_send() input flags - The caller indicates that there is additional data to be sent.

This flag is applicable only for TCP connections. Caller will not set this flag for the last data chunk to be sent.

◆ CY_SOCKET_FLAGS_RECVFROM_SRC_FILTER

#define CY_SOCKET_FLAGS_RECVFROM_SRC_FILTER   ( 0x1 )

cy_socket_recvfrom() input flags - Used for filtering of input packets.

Packets are received only from the user-specified source address.

◆ CY_SOCKET_POLL_READ

#define CY_SOCKET_POLL_READ   ( 1 )

cy_socket_poll() input flags - Check for pending data.


◆ CY_SOCKET_SHUT_RDWR

#define CY_SOCKET_SHUT_RDWR   ( CY_SOCKET_SHUT_RD | CY_SOCKET_SHUT_WR )

Option for the "how" parameter of cy_socket_shutdown() - Disables further send and receive.

operations.