From 2d153ebf0c3fc7d0f076f9593c3801219b844e60 Mon Sep 17 00:00:00 2001 From: gitlab-runner Date: Fri, 8 May 2020 01:57:27 -0500 Subject: [PATCH] Upload secure-sockets 1.0.1.446 --- RELEASE.md | 3 +++ docs/api_reference_manual/html/index.html | 14 ++++++++++++-- include/cy_secure_sockets.h | 23 ++++++++++++++++++++++- version.txt | 2 +- 4 files changed, 38 insertions(+), 4 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 7aeea69..8ddd0c5 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -9,6 +9,9 @@ Refer to the [README.md](./README.md) for a complete description of the secure s | UDP, IPv6 and DTLS are not supported in the secure sockets library | No workaround. Support will be added in a future release | ## Changelog +### v1.0.1 +* Code snippets added to the documentation + ### v1.0.0 * Initial release for secure sockets library * Provides network abstraction APIs for underlying lwIP stack and mbedTLS library diff --git a/docs/api_reference_manual/html/index.html b/docs/api_reference_manual/html/index.html index 03fe0ce..0e71f76 100644 --- a/docs/api_reference_manual/html/index.html +++ b/docs/api_reference_manual/html/index.html @@ -108,9 +108,19 @@

  • Cypress Secure Sockets Library configures default send and receive timeout values to 10 seconds for a newly created socket. Default timeout values can be changed by modifying DEFAULT_SEND_TIMEOUT and DEFAULT_RECV_TIMEOUT macros in the cy_secure_sockets.h file. To configure the timeout values specific to socket, use the cy_socket_setsockopt API function. To change the send timeout, use the CY_SOCKET_SO_SNDTIMEO socket option; similarly, for receive timeout, use the CY_SOCKET_SO_RCVTIMEO socket option. Adjust the default timeout values based on the network speed or use case.
  • Cypress secure sockets library has been designed to support different flavors of TCP/IP stack or security stack. Currently, lwIP and MbedTLS are the default network and security stacks respectively. Therefore, any application that uses secure sockets must ensure that the following COMPONENTS are defined in the code example project's Makefile - LWIP and MBEDTLS.
  • Cypress secure sockets and TLS libraries enable only error prints by default. For debugging purposes, the application may additionally enable debug and info log messages. To enable these messages, add SECURE_SOCKETS_ENABLE_PRINT_LIBRARY_INFO, SECURE_SOCKETS_ENABLE_PRINT_LIBRARY_DEBUG, TLS_ENABLE_PRINT_LIBRARY_INFO, and TLS_ENABLE_PRINT_LIBRARY_DEBUG macros to the DEFINES in the code example's Makefile. The Makefile entry would look like,
    DEFINES+=SECURE_SOCKETS_ENABLE_PRINT_LIBRARY_INFO SECURE_SOCKETS_ENABLE_PRINT_LIBRARY_DEBUG
    DEFINES+=TLS_ENABLE_PRINT_LIBRARY_INFO TLS_ENABLE_PRINT_LIBRARY_DEBUG
    • -
  • In order to ease integration of Wi-Fi connectivity components to code examples, this secure socket library has been bundled into the Wi-Fi Middleware Core Library v2.0.0
    • +
  • In order to ease integration of Wi-Fi connectivity components to code examples, this secure socket library has been bundled into the Wi-Fi Middleware Core Library v2.0.0
    • - +

    +Code Snippets

    +

    +Code Snippet1: Create TCP Socket

    +

    This code snippet demonstrates how to initialize and create a TCP socket.

    void snippet_create_socket()
    {
    cy_rslt_t result;
    /* TCP socket handle */
    cy_socket_t socket_handle;
    /* 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, &socket_handle);
    }

    +Code Snippet2: Create Secure Socket

    +

    This code snippet demonstrates how to initialize and create a TCP socket and set the TLS credentials to be used for securing the socket communication.

    void snippet_create_secure_socket()
    {
    cy_rslt_t result;
    /* TCP socket handle */
    cy_socket_t socket_handle;
    /* Variable to store the TLS identity (certificate and private key).*/
    void *tls_identity;
    /* TLS authentication mode. Setting CY_SOCKET_TLS_VERIFY_REQUIRED authentication mode
    requires a successful TLS handshake in order to establish a secure socket communication*/
    cy_socket_tls_auth_mode_t tls_auth_mode = CY_SOCKET_TLS_VERIFY_REQUIRED;
    /* Initialize with your TLS certificate. Must include the PEM header and footer*/
    static const char tls_cert[] = "-----REPLACE WITH TLS CERTIFICATE FILE-----\n";
    /* Initialize with private key corresponding to the TLS ceritificate used.
    * Must include the PEM header and footer. */
    static const char private_key[] = "-----REPLACE WITH PRIVATE KEY-----\n";
    /* TLS certificate length and private key length. */
    const size_t cert_len = strlen( tls_cert );
    const size_t pkey_len = strlen( private_key );
    /* Initialize the Secure Sockets library. */
    result = cy_socket_init();
    /* Create a new secure TCP socket. */
    result = cy_socket_create(CY_SOCKET_DOMAIN_AF_INET, CY_SOCKET_TYPE_STREAM, CY_SOCKET_IPPROTO_TLS, &socket_handle);
    /* Create TCP client identity using the SSL certificate and private key. */
    result = cy_tls_create_identity(tls_cert, cert_len, private_key, pkey_len, &tls_identity);
    /* Set the TCP socket to use the TLS identity. */
    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));
    }

    +Code Snippet3: TCP Client Connect

    +

    This code snippet demonstrates how to create a TCP client socket and initiate communication with a TCP server.

    #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 number to match the TCP server address to which
    * client wants to connect to.
    */
    #define TCP_SERVER_IP_ADDRESS MAKE_IPV4_ADDRESS(192, 168, 18, 9)
    #define TCP_SERVER_PORT (50007)
    /* Buffer size to store the incoming messages from server. */
    #define MAX_TCP_RECV_BUFFER_SIZE (20)
    #define RTOS_TASK_TICKS_TO_WAIT (1000)
    /* TCP socket handle */
    cy_socket_t client_handle;
    bool send_msg_to_server;
    /* Function to handle incoming message from TCP server. */
    cy_rslt_t tcp_client_recv_handler(cy_socket_t client_handle, void *arg)
    {
    cy_rslt_t result ;
    /* Variable to store the number of bytes received. */
    uint32_t bytes_received = 0;
    char rx_buffer[MAX_TCP_RECV_BUFFER_SIZE];
    /* Receive incoming message from TCP server. */
    result = cy_socket_recv(client_handle, rx_buffer, MAX_TCP_RECV_BUFFER_SIZE,
    CY_SOCKET_FLAGS_NONE, &bytes_received);
    /* Set the flag to send a message to TCP server*/
    send_msg_to_server = true;
    return result;
    }
    void snippet_tcp_client()
    {
    cy_rslt_t result;
    /* Variable to store the number of bytes sent to the TCP server. */
    uint32_t bytes_sent = 0;
    /* IP address and TCP port number of the TCP server */
    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
    };
    /* Buffer to hold data to be sent to client. */
    char tx_buffer[] = "Message to TCP server";
    /* Initialize the Secure Sockets library. */
    result = cy_socket_init();
    /* Create a TCP socket. If you need a secure connection, create a secure socket
    * as demonstrated by snippet_create_secure_socket function.
    */
    result = cy_socket_create(CY_SOCKET_DOMAIN_AF_INET, CY_SOCKET_TYPE_STREAM, CY_SOCKET_IPPROTO_TCP, &client_handle);
    /* Variable used to set socket options. */
    cy_socket_opt_callback_t tcp_recv_option = {
    .callback = tcp_client_recv_handler,
    .arg = NULL
    };
    /* Register the callback function to handle messages received from TCP server. */
    result = cy_socket_setsockopt(client_handle, CY_SOCKET_SOL_SOCKET,
    CY_SOCKET_SO_RECEIVE_CALLBACK,
    &tcp_recv_option, sizeof(cy_socket_opt_callback_t));
    result = cy_socket_connect(client_handle, &tcp_server_addr, sizeof(cy_socket_sockaddr_t));
    for(;;)
    {
    if(send_msg_to_server)
    {
    /* Send message to TCP server. */
    result = cy_socket_send(client_handle, tx_buffer, strlen(tx_buffer),
    CY_SOCKET_FLAGS_NONE, &bytes_sent);
    /*Close the connection*/
    result = cy_socket_disconnect(client_handle, 0);
    /* Delete the socket and free the resources allocated to the socket. */
    result = cy_socket_delete(client_handle);
    /* Clear the flag to send message to TCP server.*/
    send_msg_to_server = false;
    }
    vTaskDelay(RTOS_TASK_TICKS_TO_WAIT);
    }
    }

    +Code Snippet4: TCP Server - Listening for client connection

    +

    This code snippet demonstrates how to create a TCP server socket and accept a TCP client connection to communicate.

    #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)
    /* Maximum number of incoming connections. */
    #define TCP_SERVER_MAX_PENDING_CONNECTIONS (3)
    /* Buffer size to store the incoming messages from client. */
    #define MAX_TCP_RECV_BUFFER_SIZE (20)
    #define RTOS_TASK_TICKS_TO_WAIT (1000)
    /* TCP socket handles */
    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_rslt_t result;
    /* Client socket address. */
    cy_socket_sockaddr_t client_addr;
    /* Size of the client socket address. */
    uint32_t client_addr_len;
    /* Accept new incoming connection from a TCP client.*/
    result = cy_socket_accept(socket_handle, &client_addr, &client_addr_len,
    &client_handle);
    /* Set the flag to send message to TCP client.*/
    send_msg_to_client = true;
    return result;
    }
    /* Function to handle incoming message from TCP client. */
    cy_rslt_t tcp_server_recv_handler(cy_socket_t socket_handle, void *arg)
    {
    cy_rslt_t result ;
    /* Variable to store the number of bytes received. */
    uint32_t bytes_received = 0;
    char rx_buffer[MAX_TCP_RECV_BUFFER_SIZE];
    /* Receive incoming message from TCP server. */
    result = cy_socket_recv(socket_handle, rx_buffer, MAX_TCP_RECV_BUFFER_SIZE,
    CY_SOCKET_FLAGS_NONE, &bytes_received);
    /*Close the connection*/
    result = cy_socket_disconnect(socket_handle, 0);
    return result;
    }
    void snippet_tcp_server()
    {
    cy_rslt_t result;
    /* Variable to store the number of bytes sent to the TCP client. */
    uint32_t bytes_sent = 0;
    /* Variable to store the number of bytes received from the TCP client. */
    uint32_t bytes_received = 0;
    /* IP address and TCP port number of the TCP server */
    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
    };
    /* Buffer to hold data to be sent to client. */
    char tx_buffer[] = "Message to TCP client";
    char rx_buffer[MAX_TCP_RECV_BUFFER_SIZE];
    /* Initialize the Secure Sockets library. */
    result = cy_socket_init();
    /* Create a TCP socket. If you need a secure connection, create a secure socket
    * as demonstrated by snippet_create_secure_socket function.
    */
    result = cy_socket_create(CY_SOCKET_DOMAIN_AF_INET, CY_SOCKET_TYPE_STREAM, CY_SOCKET_IPPROTO_TCP, &server_handle);
    /* Variable used to set socket options. */
    cy_socket_opt_callback_t tcp_connection_option = {
    .callback = tcp_connection_handler,
    .arg = NULL
    };
    /* Register the callback function to handle connection request from a TCP client. */
    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));
    /* Variable used to set socket options. */
    cy_socket_opt_callback_t tcp_recv_option = {
    .callback = tcp_server_recv_handler,
    .arg = NULL
    };
    /* Register the callback function to handle messages received from TCP client. */
    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 the TCP socket created to Server IP address and to TCP port. */
    result = cy_socket_bind(server_handle, &tcp_server_addr, sizeof(tcp_server_addr));
    /* Start listening on the TCP server socket. */
    result = cy_socket_listen(server_handle, TCP_SERVER_MAX_PENDING_CONNECTIONS);
    for (;;)
    {
    if(send_msg_to_client)
    {
    /* Send message to TCP client. */
    result = cy_socket_send(client_handle, tx_buffer, strlen(tx_buffer),
    CY_SOCKET_FLAGS_NONE, &bytes_sent);
    send_msg_to_client = false;
    }
    vTaskDelay(RTOS_TASK_TICKS_TO_WAIT);
    }
    }