xref: /FreeRTOS-Plus/Demo/coreSNTP_Windows_Simulator/SNTPClientTask.c

/*
 * FreeRTOS V202212.00
 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * https://www.FreeRTOS.org
 * https://github.com/FreeRTOS
 *
 */

/*
 * This file is part of the demo project that shows use of the coreSNTP library to create
 * an SNTP client (daemon) task for synchronizing system time with internet time and
 * maintaining Coordinated Universal Time (UTC) (or wall-clock time) in the system.
 *
 * This file contains the SNTP client (daemon) task as well as functionality for
 * maintaining wall-clock or UTC time in RAM. The SNTP client periodically synchronizes
 * system clock with SNTP/NTP server(s). Any other task running an application in the
 * system can query the system time. For an example of an application task querying time
 * from the system, refer to the SampleAppTask.c file in this project.
 *
 * This demo shows how the coreSNTP library can be used to communicate with SNTP/NTP
 * servers in a mutually authenticated through the use of symmetric-key based AES-128-CMAC
 * algorithm. To run this demo with an SNTP/NTP server in authenticated mode, the AES-128-CMAC
 * symmetric key needs to be pre-shared between the client (i.e. this demo) and the server.
 *
 * !!!Note!!!:
 * Even though this demo shows the use of AES-128-CMAC, a symmetric-key cryptographic based
 * solution, for authenticating SNTP communication between the demo (SNTP client) and
 * SNTP/NTP server, we instead RECOMMEND that production devices use the most secure authentication
 * mechanism alternative available with the Network Time Security (NTS) protocol, an asymmetric-key
 * cryptographic protocol. For more information, refer to the NTS specification here:
 * https://datatracker.ietf.org/doc/html/rfc8915
 */

/* Standard includes. */
#include <string.h>
#include <stdio.h>
#include <stdint.h>
#include <time.h>
#include <math.h>

/* Kernel includes. */
#include "FreeRTOS.h"
#include "task.h"

/* Demo include. */
#include "common_demo_include.h"

/* SNTP library include. */
#include "core_sntp_client.h"

/* Synchronization primitive include. */
#include "semphr.h"

/* FreeRTOS+TCP includes */
#include "FreeRTOS_IP.h"
#include "FreeRTOS_UDP_IP.h"
#include "FreeRTOS_Sockets.h"

/* PKCS11 includes. */
#include "core_pki_utils.h"
#include "core_pkcs11_config.h"
#include "core_pkcs11.h"

/* Backoff Algorithm include. */
#include "backoff_algorithm.h"

/*-----------------------------------------------------------*/

/* Compile time error for undefined configs. */

#ifndef democonfigLIST_OF_TIME_SERVERS
    #error "Define the democonfigLIST_OF_TIME_SERVERS config by following the instructions in demo_config.h file."
#endif

#ifndef democonfigLIST_OF_AUTHENTICATION_SYMMETRIC_KEYS
    #error "Define the democonfigLIST_OF_AUTHENTICATION_SYMMETRIC_KEYS config by following the instructions in demo_config.h file."
#endif

#ifndef democonfigLIST_OF_AUTHENTICATION_KEY_IDS
    #error "Define the democonfigLIST_OF_AUTHENTICATION_KEY_IDS config by following the instructions in demo_config.h file."
#endif

#ifndef democonfigSNTP_CLIENT_POLLING_INTERVAL_SECONDS
    #error "Define the democonfigSNTP_CLIENT_POLLING_INTERVAL_SECONDS config by following instructions in demo_config.h file."
#endif

#ifndef democonfigSYSTEM_START_YEAR
    #error "Define the democonfigSYSTEM_START_YEAR config by following instructions in demo_config.h file."
#endif

/*-----------------------------------------------------------*/
/* Default values for timeout configurations . */

#ifndef democonfigSERVER_RESPONSE_TIMEOUT_MS
    #define democonfigSERVER_RESPONSE_TIMEOUT_MS    ( 5000 )
#endif

#ifndef democonfigSEND_TIME_REQUEST_TIMEOUT_MS
    #define democonfigSEND_TIME_REQUEST_TIMEOUT_MS    ( 50 )
#endif

#ifndef democonfigRECEIVE_SERVER_RESPONSE_BLOCK_TIME_MS
    #define democonfigRECEIVE_SERVER_RESPONSE_BLOCK_TIME_MS    ( 200 )
#endif

/**
 * @brief The size for network buffer that is allocated for initializing the coreSNTP library in the
 * demo.
 *
 * @note The size of the buffer MUST be large enough to hold an entire SNTP packet, which includes the standard SNTP
 * packet data of 48 bytes and authentication data for security mechanism, if used, in communication with time server.
 */
#define SNTP_CONTEXT_NETWORK_BUFFER_SIZE        ( SNTP_PACKET_BASE_SIZE )

/**
 * @brief The constant for storing the number of milliseconds per FreeRTOS tick in the system.
 * @note This value represents the time duration per tick from the perspective of the
 * of Windows Simulator based FreeRTOS system that carries lagging clock drift in relation to
 * internet time or UTC time. Thus, the actual time duration value per tick of the system will be
 * larger from the perspective of internet time.
 */
#define MILLISECONDS_PER_TICK                   ( 1000 / configTICK_RATE_HZ )

/**
 * @brief The fixed size of the key for the AES-128-CMAC algorithm used for authenticating communication
 * between the time server and the client.
 */
#define AES_CMAC_AUTHENTICATION_KEY_SIZE        ( 16 )

/**
 * @brief The size of the "Key Identifier" field in the SNTP packet when symmetric key authentication mode as
 * security mechanism in communicating with time server.
 *
 * The "Key Identifier" field appears immediately after the 48 bytes of standard SNTP packet created by the coreSNTP
 * library. For more information, refer to the SNTPv4 specification: https://datatracker.ietf.org/doc/html/rfc4330#page-8
 *
 * @note This demo uses the "Key Identifier" field to communicate with time servers that support authentication mechanism.
 * This field is stored with the Key ID of the AES-128-CMAC based authentication key stored in the time server.
 */
#define SNTP_PACKET_SYMMETRIC_KEY_ID_LENGTH     4

/**
 * @brief The offset for the starting byte of the "Key Identifier" field in an SNTPv4/NTPv4 packet.
 * This field is only used when symmetric key authentication mode is used for communicating with time server.
 *
 * For more information of the SNTP packet format, refer to the SNTPv4 specification
 * https://datatracker.ietf.org/doc/html/rfc4330#page-8
 */
#define SNTP_PACKET_SYMMETRIC_KEY_ID_OFFSET     SNTP_PACKET_BASE_SIZE

/**
 * @brief The total size of an SNTP packet (which remains same for both client request and server response in SNTP communication)
 * when using symmetric key based authentication mechanism.
 *
 * This value includes size of the 48 bytes of standard SNTP packet, and the "Key Identifier" and "Message Digest" fields
 * that are used for authentication information in SNTP communication between client and server.
 *
 * For more information of the SNTP packet format, refer to the SNTPv4 specification
 * https://datatracker.ietf.org/doc/html/rfc4330#page-8
 */
#define SNTP_PACKET_AUTHENTICATED_MODE_SIZE     ( SNTP_PACKET_BASE_SIZE + SNTP_PACKET_SYMMETRIC_KEY_ID_LENGTH + pkcs11AES_CMAC_SIGNATURE_LENGTH )

/**
 * @brief The maximum poll period that the SNTP client can use as back-off on receiving a rejection from a time server.
 *
 * @note This demo performs back-off in polling rate from time server ONLY for the case when a single time server being
 * is configured through the democonfigLIST_OF_TIME_SERVERS macro.
 * This is because when more than one time server is configured, the coreSNTP library automatically handles the case
 * of server rejection of time request by rotating to the next configured server for subsequent time polling requests.
 */
#define SNTP_DEMO_POLL_MAX_BACKOFF_DELAY_SEC    UINT16_MAX

/**
 * @brief The maximum number of times of retrying time requests at exponentially backed-off polling frequency
 * from a server that rejects time requests.
 *
 * @note This macro is only relevant for the case when a single time server is configured in
 * the demo through, democonfigLIST_OF_TIME_SERVERS.
 */
#define SNTP_DEMO_MAX_SERVER_BACKOFF_RETRIES    10

/*-----------------------------------------------------------*/

/**
 * @brief The definition of the @ref NetworkContext_t structure for the demo.
 * The structure wraps a FreeRTOS+TCP socket that is used for UDP communication
 * with time servers.
 *
 * @note The context is used in the @ref UdpTransportInterface_t interface required
 * by the coreSNTP library.
 */
struct NetworkContext
{
    Socket_t socket;
};

/**
 * @brief The definition of the @ref SntpAuthContext_t structure for the demo.
 * This structure represents the symmetric key for the AES-128-CMAC algorithm based
 * authentication mechanism shown in the demo for securing SNTP communication
 * between client and time server.
 *
 * @note The context is used in the @ref SntpAuthInterface_t interface required
 * by the coreSNTP library for enabling authentication.
 */
struct SntpAuthContext
{
    const char * pServer;
    int32_t keyId;
    uint8_t pAuthKey[ AES_CMAC_AUTHENTICATION_KEY_SIZE ];
};

/**
 * @brief Structure aggregating state variables for RAM-based wall-clock time
 * in Coordinated Universal Time (UTC) for system.
 *
 * @note This demo uses the following mathematical model to represent current
 * time in RAM.
 *
 *  BaseTime = Time set at boot or the last synchronized time
 *  Slew Rate = Number of milliseconds to adjust per system time second
 *  No. of ticks since last SNTP sync = Current FreeRTOS Tick Count -
 *                                      Tick count at last SNTP sync
 *
 *  Time Elapsed since last SNTP sync = No. of ticks since last SNTP sync
 *                                                    x
 *                                      Number of milliseconds per FreeRTOS tick
 *
 *  Slew Adjustment = Slew Rate x Time Elapsed since last SNTP sync
 *
 *  Current Time = Base Time +
 *                 Time Elapsed since last SNTP sync +
 *                 Slew Adjustment
 */
typedef struct SystemClock
{
    UTCTime_t baseTime;
    TickType_t lastSyncTickCount;
    uint32_t pollPeriod;
    uint64_t slewRate; /* Milliseconds/Seconds */
    bool firstTimeSyncDone;
} SystemClock_t;

/**
 * @brief Shared global system clock object for representing UTC/wall-clock
 * time in system.
 */
static SystemClock_t systemClock;

/**
 * @brief Mutex for protecting access to the shared memory of the
 * system clock parameters.
 */
static SemaphoreHandle_t xMutex = NULL;

/*
 * @brief Stores the configured time servers in an array.
 */
static const char * pTimeServers[] = { democonfigLIST_OF_TIME_SERVERS };
const size_t numOfServers = sizeof( pTimeServers ) / sizeof( char * );

/**
 * @brief Stores the list of configured AES-128-CMAC symmetric keys for authentication
 * mechanism for corresponding time servers in democonfigLIST_OF_TIME_SERVERS.
 */
static const char * pAESCMACAuthKeys[] = { democonfigLIST_OF_AUTHENTICATION_SYMMETRIC_KEYS };

/**
 * @brief Stores list of Key IDs corresponding to the authentication keys configured
 * in democonfigLIST_OF_TIME_SERVERS.
 */
static const int32_t pAuthKeyIds[] = { democonfigLIST_OF_AUTHENTICATION_KEY_IDS };

/*-----------------------------------------------------------*/

/**
 * @brief Utility function to convert the passed year to UNIX time representation
 * of seconds since 1st Jan 1970 00h:00m:00s seconds to 1st Jan 00h:00m:00s of the
 * the passed year.
 *
 * This utility does account for leap years.
 *
 * @param[in] The year to translate.
 */
static uint32_t translateYearToUnixSeconds( uint16_t year );

/**
 * @brief Calculates the current time in the system.
 * It calculates the current time as:
 *
 *   BaseTime = Time set at device boot or the last synchronized time
 *   SlewRate = Number of milliseconds to adjust per system time second
 *
 *   Current Time = Base Time +
 *                  Time since last SNTP Synchronization +
 *                  Slew Adjustment (if slew rate > 0) for time period since
 *                  last SNTP synchronization
 *
 * @param[in] pBaseTime The base time in the system clock parameters.
 * @param[in] lastSyncTickCount The tick count at the last time synchronization
 * with a time server.
 * @param[in] slewRate The slew rate as seconds of clock adjustment per FreeRTOS
 * system time second.
 * @param[out] pCurrentTime This will be populated with the calculated current
 * UTC time in the system.
 */
static void calculateCurrentTime( UTCTime_t * pBaseTime,
                                  TickType_t lastSyncTickCount,
                                  uint64_t slewRate,
                                  UTCTime_t * pCurrentTime );

/**
 * @brief Initializes the SNTP context for the SNTP client task.
 * This function generates an array of the configured time servers, creates a FreeRTOS UDP socket
 * for the UDP transport interface and initializes the passed SNTP context by calling the
 * Sntp_Init() API of the coreSNTP library.
 *
 * @param[in, out] pContext The memory for the SNTP client context that will be initialized with
 * Sntp_Init API.
 * @param[in] pTimeServers The list of time servers configured through the democonfigLIST_OF_TIME_SERVERS
 * macro in demo_config.h.
 * @param[in] numOfServers The number of time servers configured in democonfigLIST_OF_TIME_SERVERS.
 * @param[in] pContextBuffer The allocated network buffer that will be initialized in the SNTP context.
 * @param[in] pUdpContext The memory for the network context for the UDP transport interface that will
 * be passed to the SNTP client context. This will be filled with a UDP context created by this function.
 *
 * @return Returns `true` if initialization of SNTP client context is successful; otherwise `false`.
 */
static bool initializeSntpClient( SntpContext_t * pContext,
                                  const char ** pTimeServers,
                                  size_t numOfServers,
                                  uint8_t * pContextBuffer,
                                  size_t contextBufferSize,
                                  NetworkContext_t * pUdpContext,
                                  SntpAuthContext_t * pAuthContext );

/**
 * @brief The demo implementation of the @ref SntpResolveDns_t interface to
 * allow the coreSNTP library to resolve DNS name of a time server being
 * used for requesting time from.
 *
 * @param[in] pTimeServer The time-server whose IPv4 address is to be resolved.
 * @param[out] pIpV4Addr This is filled with the resolved IPv4 address of
 * @p pTimeServer.
 */
static bool resolveDns( const SntpServerInfo_t * pServerAddr,
                        uint32_t * pIpV4Addr );

/**
 * @brief The demo implementation of the @ref UdpTransportSendTo_t function
 * of the UDP transport interface to allow the coreSNTP library to perform
 * network operation of sending time request over UDP to the provided time server.
 *
 * @param[in] pNetworkContext This will be the NetworkContext_t context object
 * representing the FreeRTOS UDP socket to use for network send operation.
 * @param[in] serverAddr The IPv4 address of the time server.
 * @param[in] serverPort The port of the server to send data to.
 * @param[in] pBuffer The demo-supplied network buffer of size, SNTP_CONTEXT_NETWORK_BUFFER_SIZE,
 * containing the data to send over the network.
 * @param[in] bytesToSend The size of data in @p pBuffer to send.
 *
 * @return Returns the return code of FreeRTOS UDP send API, FreeRTOS_sendto, which returns
 * 0 for error or timeout OR the number of bytes sent over the network.
 */
static int32_t UdpTransport_Send( NetworkContext_t * pNetworkContext,
                                  uint32_t serverAddr,
                                  uint16_t serverPort,
                                  const void * pBuffer,
                                  uint16_t bytesToSend );

/**
 * @brief The demo implementation of the @ref UdpTransportRecvFrom_t function
 * of the UDP transport interface to allow the coreSNTP library to perform
 * network operation of reading expected time response over UDP from
 * provided time server.
 *
 * @param[in] pNetworkContext This will be the NetworkContext_t context object
 * representing the FreeRTOS UDP socket to use for network read operation.
 * @param[in] pTimeServer The IPv4 address of the time server to receive data from.
 * @param[in] serverPort The port of the server to receive data from.
 * @param[out] pBuffer The demo-supplied network buffer of size, SNTP_CONTEXT_NETWORK_BUFFER_SIZE,
 * that will be filled with data received from the network.
 * @param[in] bytesToRecv The expected number of bytes to receive from the network
 * for the server response server.
 *
 * @return Returns one of the following:
 * - 0 for timeout in receiving any data from the network (by translating the
 * -pdFREERTOS_ERRNO_EWOULDBLOCK return code from FreeRTOS_recvfrom API )
 *                         OR
 * - The number of bytes read from the network.
 */
static int32_t UdpTransport_Recv( NetworkContext_t * pNetworkContext,
                                  uint32_t serverAddr,
                                  uint16_t serverPort,
                                  void * pBuffer,
                                  uint16_t bytesToRecv );

/**
 * @brief The demo implementation of the @ref SntpGetTime_t interface
 * for obtaining system clock time for the coreSNTP library.
 *
 * @param[out] pTime This will be populated with the current time from
 * the system.
 */
static void sntpClient_GetTime( SntpTimestamp_t * pCurrentTime );

/**
 * @brief The demo implementation of the @ref SntpSetTime_t interface
 * for correcting the system clock time based on the  time received
 * from the server response and the clock-offset value calculated by
 * the coreSNTP library.
 *
 * @note This demo uses a combination of "step" AND "slew" methodology
 * for system clock correction.
 * 1. "Step" correction is ALWAYS used to immediately correct the system clock
 *    to match server time on every successful time synchronization with a
 *    time server (that occurs periodically on the poll interval gaps).
 *
 * 2. "Slew" correction approach is used for compensating system clock drift
 *    during the poll interval period between time synchronization attempts with
 *    time server(s) when latest time server is not known. The "slew rate" is
 *    calculated ONLY once on the occasion of the second successful time
 *    synchronization with a time server. This is because the demo initializes
 *    system time with (the first second of) the democonfigSYSTEM_START_YEAR
 *    configuration, and thus, the the actual system clock drift over a period
 *    of time can be calculated only AFTER the demo system time has been synchronized
 *    with server time once. Thus, after the first time period of poll interval has
 *    transpired, the system clock drift is calculated correctly on the subsequent
 *    successful time synchronization with a time server.
 *
 * @note The above system clock correction algorithm is just one example of a correction
 * approach. It can be modified to suit your application needs. For example, your
 * application can use ONLY the "step" correction methodology for simplicity of system clock
 * time calculation logic if the application is not sensitive to abrupt time changes
 * (that occur at the instances of periodic time synchronization attempts). In such a case,
 * the Sntp_CalculatePollInterval() API of coreSNTP library can be used to calculate
 * the optimum time polling period for your application based on the factors of your
 * system's clock drift rate and the maximum clock drift tolerable by your application.
 *
 *
 * @param[in] pTimeServer The time server from whom the time has been received.
 * @param[in] pServerTime The most recent time of the server, @p pTimeServer, sent in its
 * time response.
 * @param[in] clockOffsetMs The value, in milliseconds, of system clock offset relative
 * to the server time calculated by the coreSNTP library. If the value is positive, then
 * the system is BEHIND the server time, and a "slew" clock correction approach is used in
 * this demo. If the value is negative, then the system time is AHEAD of the server time,
 * and a "step" clock correction approach is used in this demo.
 * @param[in] leapSecondInfo This indicates whether there is an upcoming leap second insertion
 * or deletion (according to astronomical time) the last minute of the end of the month that the
 * system time needs to adjust for. Leap second adjustment is valuable for applications that
 * require non-abrupt increment of time for use cases like logging. This demo DOES NOT showcase
 * leap second adjustment in system clock.
 */
static void sntpClient_SetTime( const SntpServerInfo_t * pTimeServer,
                                const SntpTimestamp_t * pServerTime,
                                int64_t clockOffsetMs,
                                SntpLeapSecondInfo_t leapSecondInfo );

/**
 * @brief Utility function to create a PKCS11 session and a PKCS11 object, and obtain the PKCS11
 * global function list for performing 128 bit AES-CMAC operations.
 * This function is called by the definitions of both the authentication interface functions,
 * @ref SntpGenerateAuthCode_t and @ref SntpValidateServerAuth_t, in this demo for the
 * AES-CMAC operations.
 *
 * @param[in] pAuthContext The context representing the symmetric key for the AES-CMAC operation.
 * @param[out] pPkcs11Session This is populated with the created PKCS11 session.
 * @param[out] pFunctionList This is populated with the function list obtained from the created
 * PKCS11 session.
 * @param[out] pCmacKey This is populated with the created PKCS11 object handle for AES-CMAC
 * operations.
 *
 * @return The return status code of PKCS11 API calls.
 */
static CK_RV setupPkcs11ObjectForAesCmac( const SntpAuthContext_t * pAuthContext,
                                          CK_SESSION_HANDLE * pPkcs11Session,
                                          CK_FUNCTION_LIST_PTR * pFunctionList,
                                          CK_OBJECT_HANDLE * pCmacKey );

/**
 * @brief Utility function for filling the authentication context with the time server and
 * its associated authentication key information from the democonfigLIST_OF_AUTHENTICATION_SYMMETRIC_KEYS
 * and democonfigLIST_OF_AUTHENTICATION_KEY_IDS configuration lists.
 *
 * The authentication context represents the server and its authentication key information being
 * used by the SNTP client at a time for time query. This function is called to update the context
 * at the time of SNTP client initialization as well as whenever the SNTP client rotates the time
 * server of use.
 *
 * @param[in] pServer The time server whose information is filled in the context.
 * @param[out] pAuthContext The authentication context to update with information about the @p pServer.
 */
static void populateAuthContextForServer( const char * pServer,
                                          SntpAuthContext_t * pAuthContext );

/**
 * @brief The demo implementation of the @ref SntpGenerateClientAuth_t function of the authentication
 * interface required by the coreSNTP library to execute functionality of generating client-side
 * message authentication code and appending it to the time request before sending to a time server.
 *
 * This function first determines whether the passed time server has an authentication key configured
 * in the demo. If the time server supports authentication, the function utilizes the corePKCS11 library
 * to generate the client authentication code as a signature using the AES-128-CMAC algorithm, and append
 * it to the passed SNTP request packet buffer, @p pRequestBuffer.
 *
 * @note If the time server supports authentication, this function writes the "Key Identifier" and "Message
 * Digest" fields of an SNTP packet.
 *
 * @param[in, out] pAuthContext The authentication context representing the time server and its authentication
 * credentials. If the coreSNTP library rotated the time server of use, then this function updates the context
 * to carry authentication information for the new server.
 * @param[in] pTimeServer The current time server being used for sending time queries by the SNTP client.
 * This is used to determine whether the @p pAuthContext carries stale information of a previously used server,
 * and thus, needs to be updated with information of the current server, @p pTimeServer.
 * @param[in, out] pRequestBuffer The buffer representing the SNTP request packet, which is already populated with
 * the standard 48 bytes of packet data. If the time server supports authentication, then the 48 bytes of data
 * and the authentication key are used to generated AES-128-CMAC signature, and the "Key Identifier" and "Message
 * Digest" fields of the packet are filled in the buffer.
 * @param[in] bufferSize The total buffer size of the @p pRequestBuffer for the SNTP request packet.
 * @param[out] pAuthCodeSize This will be populated with the total bytes for authentication data written to the
 * @p pRequestBuffer when
 *
 * @return Returns one of the following:
 * - SntpSuccess if EITHER no authentication key information has been configured for the time
 * server, and thus, no AES-CMAC operation was performed OR the time server supports authentication and
 * the corePKCS11 operations are successful in generating and appending authentication information to the
 * @p pRequestBuffer.
 * - SntpErrorAuthFailure if there is failure in PKCS#11 operations in generating and appending the AES-128-CMAC
 * signature as the authentication code to the @p pRequestBuffer.
 */
static SntpStatus_t addClientAuthCode( SntpAuthContext_t * pAuthContext,
                                       const SntpServerInfo_t * pTimeServer,
                                       void * pRequestBuffer,
                                       size_t bufferSize,
                                       uint16_t * pAuthCodeSize );


/**
 * @brief The demo implementation of the @ref SntpValidateServerAuth_t function of the authentication
 * interface required by the coreSNTP library to execute validation of server as the source of the
 * received SNTP response by verifying the authentication information present in the packet.
 *
 * This function first checks whether the passed time server has authentication key information configured
 * in the demo to determine if the server supports authentication. If the time server supports authentication,
 * the function utilizes the corePKCS11 library to verify the AES-128-CMAC signature in the packet, @p pResponseData
 * that represents the server authentication code.
 *
 * @param[in] pAuthContext The authentication context representing the time server of use and its authentication
 * credentials.
 * @param[in] pTimeServer The current time server of use from which the response data, @p pResponseData has been
 * received by the SNTP client. This SHOULD match the time server information carried by the authentication context.
 * @param[in] pResponseData The buffer representing the SNTP response packet, received from the server, @p pTimeServer,
 * which contains the server authentication code, if the server supports authentication. The authentication code, if present,
 * is verified using corePKCS11 to be the expected AES-128-CMAC signature using the standard 48 bytes of SNTP packet data
 * present in the buffer and the secret symmetric key configured for the server.
 * @param[in] responseSize The total buffer size of the @p pResponseData for the SNTP response packet.
 *
 * @return Returns one of the following:
 * - SntpSuccess if EITHER no authentication key information has been configured for the time server, and thus,
 * no AES-CMAC validation operation is performed OR the time server supports authentication and the authentication
 * code has been successfully validated @p pBuffer.
 * - SntpErrorAuthFailure if there is internal failure in PKCS#11 operations in validating the server authentication code as
 * as the AES-128-CMAC for the information present in the response packet, @p pResponseData.
 * - SntpServerNotAuthenticated if the server is not validated from the response due to the authentication code not matching
 * the expected AES-128-CMAC signature.
 */
static SntpStatus_t validateServerAuth( SntpAuthContext_t * pAuthContext,
                                        const SntpServerInfo_t * pTimeServer,
                                        const void * pResponseData,
                                        uint16_t responseSize );

/**
 * @brief Generates a random number using PKCS#11.
 *
 * @note It is RECOMMENDED to generate a random number for the call to Sntp_SendTimeRequest API
 * of coreSNTP library to protect against server response spoofing attacks from "network off-path"
 * attackers.
 *
 * @return The generated random number.
 */
static uint32_t generateRandomNumber();

/**
 * @brief Utility to create a new FreeRTOS UDP socket and bind a random
 * port to it.
 * A random port is used for the created UDP socket as a protection mechanism
 * against spoofing attacks from malicious actors that are off the network
 * path of the client-server communication.
 *
 * @param[out] This will be populated with a new FreeRTOS UDP socket
 * that is bound to a random port.
 *
 * @return Returns #true for successful creation of UDP socket; #false
 * otherwise for failure.
 */
static bool createUdpSocket( Socket_t * pSocket );

/**
 * @brief Utility to close the passed FreeRTOS UDP socket.
 *
 * @param pSocket The UDP socket to close.
 */
static void closeUdpSocket( Socket_t * pSocket );

/**
 * @brief Utility to calculate new poll period with exponential backoff and jitter
 * algorithm.
 *
 * @note The demo applies time polling frequency backoff only when a single time server
 * is configured, through the democonfigLIST_OF_SERVERS macro, and the single server
 * rejects time requests.
 *
 * @param[in, out] pContext The context representing the back-off parameters. This
 * context is initialized by the function whenever the caller indicates it with the
 * @p shouldInitializeContext flag.
 * @param[in] shouldInitializeContext Flag to indicate if the passed context should be
 * initialized to start a new sequence of backed-off time request retries.
 * @param[in] minPollPeriod The minimum poll period
 * @param[in] pPollPeriod The new calculated poll period.
 *
 * @return Return #true if a new poll interval is calculated to retry time request
 * from the server; #false otherwise to indicate exhaustion of time request retry attempts
 * with the server.
 */
static bool calculateBackoffForNextPoll( BackoffAlgorithmContext_t * pContext,
                                         bool shouldInitializeContext,
                                         uint32_t minPollPeriod,
                                         uint32_t * pPollPeriod );

/*------------------------------------------------------------------------------*/

static uint32_t translateYearToUnixSeconds( uint16_t year )
{
    configASSERT( year >= 1970 );

    uint32_t numOfDaysSince1970 = ( year - 1970 ) * 365;

    /* Calculate the extra days in leap years (for February 29) over the time
    * period from 1st Jan 1970 to 1st Jan of the passed year.
    * By subtracting from the year 1969, the extra day in 1972 is covered. */
    numOfDaysSince1970 += ( ( year - 1969 ) / 4 );

    return( numOfDaysSince1970 * 24 * 3600 );
}

void calculateCurrentTime( UTCTime_t * pBaseTime,
                           TickType_t lastSyncTickCount,
                           uint64_t slewRate,
                           UTCTime_t * pCurrentTime )
{
    uint64_t msElapsedSinceLastSync = 0;
    uint64_t currentTimeSecs;
    TickType_t ticksElapsedSinceLastSync = xTaskGetTickCount() - lastSyncTickCount;

    /* Calculate time elapsed since last synchronization according to the number
     * of system ticks passed. */
    msElapsedSinceLastSync = ticksElapsedSinceLastSync * MILLISECONDS_PER_TICK;

    /* If slew rate is set, then apply the slew-based clock adjustment for the elapsed time. */
    if( slewRate > 0 )
    {
        /* Slew Adjustment = Slew Rate ( Milliseconds/seconds )
         *                                      x
         *                   No. of seconds since last synchronization. */
        msElapsedSinceLastSync += slewRate * ( msElapsedSinceLastSync / 1000 );
    }

    /* Set the current UTC time in the output parameter. */
    if( msElapsedSinceLastSync >= 1000 )
    {
        currentTimeSecs = ( uint64_t ) ( pBaseTime->secs ) + ( msElapsedSinceLastSync / 1000 );

        /* Support case of UTC timestamp rollover on 7 February 2038. */
        if( currentTimeSecs > UINT32_MAX )
        {
            /* Assert when the UTC timestamp rollover. */
            configASSERT( !( currentTimeSecs > UINT32_MAX ) );

            /* Subtract an extra second as timestamp 0 represents the epoch for
             * UTC era 1. */
            LogWarn( ( "UTC timestamp rollover." ) );
            pCurrentTime->secs = ( uint32_t ) ( currentTimeSecs - UINT32_MAX - 1 );
        }
        else
        {
            pCurrentTime->secs = ( uint32_t ) ( currentTimeSecs );
        }

        pCurrentTime->msecs = msElapsedSinceLastSync % 1000;
    }
    else
    {
        pCurrentTime->secs = pBaseTime->secs;
        pCurrentTime->msecs = ( uint32_t ) ( msElapsedSinceLastSync );
    }
}

/********************** DNS Resolution Interface *******************************/
static bool resolveDns( const SntpServerInfo_t * pServerAddr,
                        uint32_t * pIpV4Addr )
{
    uint32_t resolvedAddr = 0;
    bool status = false;

    resolvedAddr = FreeRTOS_gethostbyname( pServerAddr->pServerName );

    /* Set the output parameter if DNS look up succeeded. */
    if( resolvedAddr != 0 )
    {
        /* DNS Look up succeeded. */
        status = true;

        *pIpV4Addr = FreeRTOS_ntohl( resolvedAddr );

        #if defined( LIBRARY_LOG_LEVEL ) && ( LIBRARY_LOG_LEVEL != LOG_NONE )
            uint8_t stringAddr[ 16 ];
            FreeRTOS_inet_ntoa( resolvedAddr, stringAddr );
            LogInfo( ( "Resolved time server as %s", stringAddr ) );
        #endif
    }

    return status;
}

/********************** UDP Interface definition *******************************/
int32_t UdpTransport_Send( NetworkContext_t * pNetworkContext,
                           uint32_t serverAddr,
                           uint16_t serverPort,
                           const void * pBuffer,
                           uint16_t bytesToSend )
{
    struct freertos_sockaddr destinationAddress;
    int32_t bytesSent;

    #if defined( ipconfigIPv4_BACKWARD_COMPATIBLE ) && ( ipconfigIPv4_BACKWARD_COMPATIBLE == 0 )
    {
        destinationAddress.sin_address.ulIP_IPv4 = FreeRTOS_htonl( serverAddr );
    }
    #else
    {
        destinationAddress.sin_addr = FreeRTOS_htonl( serverAddr );
    }
    #endif /* defined( ipconfigIPv4_BACKWARD_COMPATIBLE ) && ( ipconfigIPv4_BACKWARD_COMPATIBLE == 0 ) */

    destinationAddress.sin_port = FreeRTOS_htons( serverPort );
    destinationAddress.sin_family = FREERTOS_AF_INET;

    /* Send the buffer with ulFlags set to 0, so the FREERTOS_ZERO_COPY bit
     * is clear. */
    bytesSent = FreeRTOS_sendto( /* The socket being send to. */
        pNetworkContext->socket,
        /* The data being sent. */
        pBuffer,
        /* The length of the data being sent. */
        bytesToSend,
        /* ulFlags with the FREERTOS_ZERO_COPY bit clear. */
        0,
        /* Where the data is being sent. */
        &destinationAddress,
        /* Not used but should be set as shown. */
        sizeof( destinationAddress )
        );

    return bytesSent;
}

static int32_t UdpTransport_Recv( NetworkContext_t * pNetworkContext,
                                  uint32_t serverAddr,
                                  uint16_t serverPort,
                                  void * pBuffer,
                                  uint16_t bytesToRecv )
{
    struct freertos_sockaddr sourceAddress;
    int32_t bytesReceived;
    socklen_t addressLength = sizeof( struct freertos_sockaddr );

    /* Receive into the buffer with ulFlags set to 0, so the FREERTOS_ZERO_COPY bit
     * is clear. */
    bytesReceived = FreeRTOS_recvfrom( /* The socket data is being received on. */
        pNetworkContext->socket,

        /* The buffer into which received data will be
         * copied. */
        pBuffer,

        /* The length of the buffer into which data will be
         * copied. */
        bytesToRecv,
        /* ulFlags with the FREERTOS_ZERO_COPY bit clear. */
        0,
        /* Will get set to the source of the received data. */
        &sourceAddress,
        /* Not used but should be set as shown. */
        &addressLength
        );

    /* If data is received from the network, discard the data if  received from a different source than
     * the server. */
    #if defined( ipconfigIPv4_BACKWARD_COMPATIBLE ) && ( ipconfigIPv4_BACKWARD_COMPATIBLE == 0 )
        if( ( bytesReceived > 0 ) && ( ( FreeRTOS_ntohl( sourceAddress.sin_address.ulIP_IPv4 ) != serverAddr ) ||
                                       ( FreeRTOS_ntohs( sourceAddress.sin_port ) != serverPort ) ) )
    #else
        if( ( bytesReceived > 0 ) && ( ( FreeRTOS_ntohl( sourceAddress.sin_addr ) != serverAddr ) ||
                                       ( FreeRTOS_ntohs( sourceAddress.sin_port ) != serverPort ) ) )
    #endif /* defined( ipconfigIPv4_BACKWARD_COMPATIBLE ) && ( ipconfigIPv4_BACKWARD_COMPATIBLE == 0 ) */
    {
        bytesReceived = 0;

        #if defined( LIBRARY_LOG_LEVEL ) && ( LIBRARY_LOG_LEVEL != LOG_NONE )
            /* Convert the IP address of the sender's address to string for logging. */
            char stringAddr[ 16 ];

        #if defined( ipconfigIPv4_BACKWARD_COMPATIBLE ) && ( ipconfigIPv4_BACKWARD_COMPATIBLE == 0 )
            {
                FreeRTOS_inet_ntoa( sourceAddress.sin_address.ulIP_IPv4, stringAddr );
            }
        #else
            {
                FreeRTOS_inet_ntoa( sourceAddress.sin_addr, stringAddr );
            }
        #endif /* defined( ipconfigIPv4_BACKWARD_COMPATIBLE ) && ( ipconfigIPv4_BACKWARD_COMPATIBLE == 0 ) */

        /* Log about reception of packet from unexpected sender. */
        LogWarn( ( "Received UDP packet from unexpected source: Addr=%s Port=%u",
                   stringAddr, FreeRTOS_ntohs( sourceAddress.sin_port ) ) );
        #endif /* if defined( LIBRARY_LOG_LEVEL ) && ( LIBRARY_LOG_LEVEL != LOG_NONE ) */
    }

    /* Translate the return code of timeout to the UDP transport interface expected
     * code to indicate read retry. */
    else if( bytesReceived == -pdFREERTOS_ERRNO_EWOULDBLOCK )
    {
        bytesReceived = 0;
    }

    return bytesReceived;
}


/**************************** Time Interfaces ************************************************/
static void sntpClient_GetTime( SntpTimestamp_t * pCurrentTime )
{
    UTCTime_t currentTime;
    uint32_t ntpSecs;

    /* Obtain mutex for accessing system clock variables */
    xSemaphoreTake( xMutex, portMAX_DELAY );

    calculateCurrentTime( &systemClock.baseTime,
                          systemClock.lastSyncTickCount,
                          systemClock.slewRate,
                          &currentTime );

    /* Release mutex. */
    xSemaphoreGive( xMutex );

    /* Convert UTC time from UNIX timescale to SNTP timestamp format. */
    ntpSecs = currentTime.secs + SNTP_TIME_AT_UNIX_EPOCH_SECS;

    /* Support case of SNTP timestamp rollover on 7 February 2036 when
     * converting from UNIX time to SNTP timestamp. */
    if( ntpSecs > UINT32_MAX )
    {
        /* Assert when SNTP time rollover. */
        configASSERT( !( ntpSecs > UINT32_MAX ) );

        /* Subtract an extra second as timestamp 0 represents the epoch for
         * NTP era 1. */
        LogWarn( ( "SNTP timestamp rollover." ) );
        pCurrentTime->seconds = ntpSecs - UINT32_MAX - 1;
    }
    else
    {
        pCurrentTime->seconds = ntpSecs;
    }

    pCurrentTime->fractions = MILLISECONDS_TO_SNTP_FRACTIONS( currentTime.msecs );
}

static void sntpClient_SetTime( const SntpServerInfo_t * pTimeServer,
                                const SntpTimestamp_t * pServerTime,
                                int64_t clockOffsetMs,
                                SntpLeapSecondInfo_t leapSecondInfo )
{
    /* Note: This demo DOES NOT show adjustment of leap second in system time,
     * if an upcoming leap second adjustment is mentioned in server response.
     * Leap second adjustment occurs at low frequency (only for the last minute of June
     * or December) and can be useful for applications that require smooth system
     * time continuum ALWAYS including the time of the leap second adjustment.
     *
     * For more information on leap seconds, refer to
     * https://www.nist.gov/pml/time-and-frequency-division/leap-seconds-faqs.
     */
    ( void ) leapSecondInfo;

    LogInfo( ( "Received time from time server: %s", pTimeServer->pServerName ) );

    /* Obtain the mutext for accessing system clock variables. */
    xSemaphoreTake( xMutex, portMAX_DELAY );

    /* Always correct the system base time on receiving time from server.*/
    SntpStatus_t status;
    uint32_t unixSecs;
    uint32_t unixMicroSecs;

    /* Convert server time from NTP timestamp to UNIX format. */
    status = Sntp_ConvertToUnixTime( pServerTime,
                                     &unixSecs,
                                     &unixMicroSecs );
    configASSERT( status == SntpSuccess );

    /* Always correct the base time of the system clock as the time received from the server. */
    systemClock.baseTime.secs = unixSecs;
    systemClock.baseTime.msecs = unixMicroSecs / 1000;

    /* Set the clock adjustment "slew" rate of system clock if it wasn't set already and this is NOT
     * the first clock synchronization since device boot-up. */
    if( ( systemClock.firstTimeSyncDone == true ) && ( systemClock.slewRate == 0 ) )
    {
        /* We will use a "slew" correction approach to compensate for system clock
         * drift over poll interval period that exists between consecutive time synchronizations
         * with time server. */

        /* Calculate the "slew" rate for system clock as milliseconds of adjustment needed per second. */
        systemClock.slewRate = clockOffsetMs / systemClock.pollPeriod;
    }

    /* Set the system clock flag that indicates completion of the first time synchronization since device boot-up. */
    if( systemClock.firstTimeSyncDone == false )
    {
        systemClock.firstTimeSyncDone = true;
    }

    /* Store the tick count of the current time synchronization in the system clock. */
    systemClock.lastSyncTickCount = xTaskGetTickCount();

    xSemaphoreGive( xMutex );
}

/**************************** Authentication Utilities and Interface Functions ***********************************************/
static void populateAuthContextForServer( const char * pServer,
                                          SntpAuthContext_t * pAuthContext )

{
    size_t index = 0;

    /* Look for the server in the list of configured servers to determine the
     * index position of the server so that the server's corresponding information of credentials
     * can be found from democonfigLIST_OF_AUTHENTICATION_SYMMETRIC_KEYS and democonfigLIST_OF_AUTHENTICATION_KEY_IDS
     * lists. */
    for( index = 0; index < numOfServers; index++ )
    {
        if( ( strlen( pServer ) == strlen( pTimeServers[ index ] ) ) && ( strncmp( pServer, pTimeServers[ index ], strlen( pServer ) ) == 0 ) )
        {
            /* The records for server in the demo configuration lists have been found. */
            break;
        }
    }

    /* Make sure that record for server has been found. */
    configASSERT( index != numOfServers );

    /* Fill the time server in the authentication context. */
    pAuthContext->pServer = pServer;

    /* Determine if the time server has been configured to use authentication mechanism. */
    if( ( pAESCMACAuthKeys[ index ] != NULL ) && ( pAuthKeyIds[ index ] != -1 ) )
    {
        const char * pKeyHexString = pAESCMACAuthKeys[ index ];

        /* Verify that the configured authentication key is 128 bits or 16 bytes in size. As
         * the input format is a hex string, the string length should be 32 bytes. */
        configASSERT( strlen( pKeyHexString ) == 2 * AES_CMAC_AUTHENTICATION_KEY_SIZE );

        /* Set the key ID in the context. */
        pAuthContext->keyId = pAuthKeyIds[ index ];

        /* Store the configured AES-128-CMAC key for authentication in the SntpAuthContext_t context
         * after converting it from hex string to binary. */
        for( index = 0; index < strlen( pKeyHexString ); index += 2 )
        {
            char byteString[ 3 ] = { pKeyHexString[ index ], pKeyHexString[ index + 1 ], '\0' };
            uint8_t byteVal = ( uint8_t ) ( strtoul( byteString, NULL, 16 ) );
            pAuthContext->pAuthKey[ index / 2 ] = byteVal;
        }
    }
    else
    {
        /* No key information has been configured for the time server. Thus, communication with the time
         * server will not use authentication mechanism. */
        memset( pAuthContext->pAuthKey, 0, sizeof( pAuthContext->pAuthKey ) );
        pAuthContext->keyId = -1;
    }
}

static CK_RV setupPkcs11ObjectForAesCmac( const SntpAuthContext_t * pAuthContext,
                                          CK_SESSION_HANDLE * pPkcs11Session,
                                          CK_FUNCTION_LIST_PTR * pFunctionList,
                                          CK_OBJECT_HANDLE * pCmacKey )
{
    CK_RV result;

    static CK_BYTE label[] = pkcs11configLABEL_CMAC_KEY;
    static CK_KEY_TYPE cmacKeyType = CKK_AES;
    static CK_OBJECT_CLASS cmacKeyClass = CKO_SECRET_KEY;
    static CK_BBOOL trueObject = CK_TRUE;

    static CK_ATTRIBUTE aes_cmac_template[] =
    {
        { CKA_CLASS,    &cmacKeyClass, sizeof( CK_OBJECT_CLASS ) },
        { CKA_KEY_TYPE, &cmacKeyType,  sizeof( CK_KEY_TYPE )     },
        { CKA_LABEL,    label,         sizeof( label ) - 1       },
        { CKA_TOKEN,    &trueObject,   sizeof( CK_BBOOL )        },
        { CKA_SIGN,     &trueObject,   sizeof( CK_BBOOL )        },
        { CKA_VERIFY,   &trueObject,   sizeof( CK_BBOOL )        },
        { CKA_VALUE,    NULL,          0                         }
    };

    /* Update the attributes array with the key of AES-CMAC operation. */
    aes_cmac_template[ 6 ].pValue = ( uint8_t * ) ( pAuthContext->pAuthKey );
    aes_cmac_template[ 6 ].ulValueLen = sizeof( pAuthContext->pAuthKey );

    result = xInitializePkcs11Session( pPkcs11Session );

    if( result != CKR_OK )
    {
        LogError( ( "Failed to open PKCS #11 session." ) );
    }

    if( result == CKR_OK )
    {
        result = C_GetFunctionList( pFunctionList );

        if( result != CKR_OK )
        {
            LogError( ( "Failed to get PKCS #11 function list." ) );
        }
    }

    if( result == CKR_OK )
    {
        /* Create the template objects */
        result = ( *pFunctionList )->C_CreateObject( *pPkcs11Session,
                                                     ( CK_ATTRIBUTE_PTR ) &aes_cmac_template,
                                                     sizeof( aes_cmac_template ) / sizeof( CK_ATTRIBUTE ),
                                                     pCmacKey );

        if( result != CKR_OK )
        {
            LogError( ( "Failed to create AES CMAC object." ) );
        }

        configASSERT( *pCmacKey != CK_INVALID_HANDLE );
    }

    return result;
}

SntpStatus_t addClientAuthCode( SntpAuthContext_t * pAuthContext,
                                const SntpServerInfo_t * pTimeServer,
                                void * pRequestBuffer,
                                size_t bufferSize,
                                uint16_t * pAuthCodeSize )
{
    CK_RV result = CKR_OK;
    CK_FUNCTION_LIST_PTR functionList;
    CK_SESSION_HANDLE pkcs11Session = 0;

    CK_OBJECT_HANDLE cMacKey;
    size_t macBytesWritten = pkcs11AES_CMAC_SIGNATURE_LENGTH;

    CK_MECHANISM mechanism =
    {
        CKM_AES_CMAC, NULL_PTR, 0
    };

    /* Determine whether the authentication context information needs to be updated to match
     * the passed time server that is to be used for querying time.
     * Note: The coreSNTP library will rotate the time server of use for communication to the next
     * in the list if either the time server rejects a time request OR times out in its response to the
     * time request. In such a case of rotating time server, the application (or user of the coreSNTP
     * library) is required to necessary updates to the authentication context to reflect the new
     * time server being used for SNTP communication by the SNTP client.*/
    if( ( strlen( pTimeServer->pServerName ) != strlen( pAuthContext->pServer ) ) ||
        ( strncmp( pTimeServer->pServerName, pAuthContext->pServer, strlen( pAuthContext->pServer ) ) != 0 ) )
    {
        /* Update the authentication context to represent the new time server of usage for
         *  time requests. */
        populateAuthContextForServer( pTimeServer->pServerName, pAuthContext );
    }

    /* Check if the time server supports AES-128-CMAC authentication scheme in communication.
     * If the time server supports authentication, then proceed with operation of generating client
     * authentication code from the SNTP request packet and appending it to the request buffer.  */
    if( pAuthContext->keyId != -1 )
    {
        /* Ensure that the buffer is large enough to hold the "Key Identifier" and "Message Digest" fields
         * for authentication information of the SNTP time request packet. */
        configASSERT( bufferSize >= SNTP_PACKET_AUTHENTICATED_MODE_SIZE );

        result = setupPkcs11ObjectForAesCmac( pAuthContext,
                                              &pkcs11Session,
                                              &functionList,
                                              &cMacKey );

        if( result == CKR_OK )
        {
            /* Test SignInit and Sign */
            result = functionList->C_SignInit( pkcs11Session, &mechanism, cMacKey );

            if( result != CKR_OK )
            {
                LogError( ( "Failed to C_SignInit AES CMAC." ) );
            }
        }

        /* Append the Key ID of the signing key before appending the signature to the buffer. */
        *( uint32_t * ) ( ( uint8_t * ) pRequestBuffer + SNTP_PACKET_SYMMETRIC_KEY_ID_OFFSET ) = FreeRTOS_htonl( pAuthContext->keyId );

        /* Generate the authentication code as the signature of the time request packet
         * with the configured key. */
        if( result == CKR_OK )
        {
            result = functionList->C_Sign( pkcs11Session,
                                           ( CK_BYTE_PTR ) pRequestBuffer,
                                           SNTP_PACKET_BASE_SIZE,
                                           ( CK_BYTE_PTR ) pRequestBuffer + SNTP_PACKET_BASE_SIZE + SNTP_PACKET_SYMMETRIC_KEY_ID_LENGTH,
                                           &macBytesWritten );

            if( result != CKR_OK )
            {
                LogError( ( "Failed to generate client auth code: Failed to generate AES-128-CMAC signature of SNTP request packet." ) );
            }
        }

        /* Close the PKCS #11 session as the AES-CMAC operation is completed. */
        if( result == CKR_OK )
        {
            result = functionList->C_CloseSession( pkcs11Session );
            configASSERT( result == CKR_OK );

            result = functionList->C_Finalize( NULL );
            configASSERT( result == CKR_OK );
        }

        if( result == CKR_OK )
        {
            *pAuthCodeSize = SNTP_PACKET_SYMMETRIC_KEY_ID_LENGTH + pkcs11AES_CMAC_SIGNATURE_LENGTH;
        }
    }
    else
    {
        /* Server has not been configured with authentication key information, thus, no data was appended to the
         * request packet buffer. */
        *pAuthCodeSize = 0;
    }

    return ( result == CKR_OK ) ? SntpSuccess : SntpErrorAuthFailure;
}

SntpStatus_t validateServerAuth( SntpAuthContext_t * pAuthContext,
                                 const SntpServerInfo_t * pTimeServer,
                                 const void * pResponseData,
                                 uint16_t responseSize )
{
    CK_RV result = CKR_OK;
    CK_FUNCTION_LIST_PTR functionList;
    CK_SESSION_HANDLE pkcs11Session = 0;
    SntpStatus_t returnStatus = SntpSuccess;

    CK_OBJECT_HANDLE cMacKey;
    size_t macBytesWritten = pkcs11AES_CMAC_SIGNATURE_LENGTH;

    CK_MECHANISM mechanism =
    {
        CKM_AES_CMAC, NULL_PTR, 0
    };

    /* The time server information in the authentication context, managed by this demo application, and the
     * pTimeServer parameter, passed by the coreSNTP library, MUST be the same.
     * Note: The addClientAuthCode() function
     * is responsible for updating the authentication context to represent the time server being currently used
     * by the coreSNTP library for time querying. */
    configASSERT( ( strlen( pTimeServer->pServerName ) == strlen( pAuthContext->pServer ) ) &&
                  ( strncmp( pTimeServer->pServerName, pAuthContext->pServer, strlen( pAuthContext->pServer ) ) == 0 ) );

    /* Check if the time server supports AES-128-CMAC authentication scheme in communication.
     * If the time server supports authentication, then proceed with operation of validating server
     * from the authentication code in the response payload.  */
    if( pAuthContext->keyId != -1 )
    {
        /* As the server supports authentication mode of communication, the server response size
         * SHOULD contain the authentication code. */
        configASSERT( responseSize >= ( SNTP_PACKET_AUTHENTICATED_MODE_SIZE ) );

        result = setupPkcs11ObjectForAesCmac( pAuthContext,
                                              &pkcs11Session,
                                              &functionList,
                                              &cMacKey );

        if( result == CKR_OK )
        {
            /* Test SignInit and Sign */
            result = functionList->C_VerifyInit( pkcs11Session, &mechanism, cMacKey );

            if( result != CKR_OK )
            {
                returnStatus = SntpErrorAuthFailure;
                LogError( ( "Failed to C_VerifyInit AES CMAC." ) );
            }
        }
        else
        {
            returnStatus = SntpErrorAuthFailure;
        }

        /* Generate the authentication code as the signature of the time request packet
         * with the configured key. */
        if( result == CKR_OK )
        {
            result = functionList->C_Verify( pkcs11Session,
                                             ( CK_BYTE_PTR ) pResponseData,
                                             SNTP_PACKET_BASE_SIZE,
                                             ( CK_BYTE_PTR ) pResponseData + SNTP_PACKET_SYMMETRIC_KEY_ID_OFFSET + SNTP_PACKET_SYMMETRIC_KEY_ID_LENGTH,
                                             pkcs11AES_CMAC_SIGNATURE_LENGTH );

            if( result != CKR_OK )
            {
                returnStatus = SntpServerNotAuthenticated;
                LogError( ( "Server cannot be validated from received response: AES-128-CMAC signature in response packet does not match expected." ) );
            }
        }

        /* Close the PKCS #11 session as the AES-CMAC operation is completed. */
        if( result == CKR_OK )
        {
            result = functionList->C_CloseSession( pkcs11Session );
            configASSERT( result == CKR_OK );

            result = functionList->C_Finalize( NULL );
            configASSERT( result == CKR_OK );
        }
    }

    return returnStatus;
}


/*************************************************************************************/

static uint32_t generateRandomNumber()
{
    CK_RV pkcs11Status = CKR_OK;
    CK_FUNCTION_LIST_PTR pFunctionList = NULL;
    CK_SESSION_HANDLE session = CK_INVALID_HANDLE;
    uint32_t randomNum = 0;

    /* Get list of functions supported by the PKCS #11 port. */
    pkcs11Status = C_GetFunctionList( &pFunctionList );

    if( pkcs11Status != CKR_OK )
    {
        configASSERT( pFunctionList != NULL );
        LogError( ( "Failed to generate random number. "
                    "PKCS #11 API, C_GetFunctionList, failed." ) );
    }

    if( pkcs11Status == CKR_OK )
    {
        /* Initialize PKCS #11 module and create a new session. */
        pkcs11Status = xInitializePkcs11Session( &session );

        if( pkcs11Status != CKR_OK )
        {
            configASSERT( session != CK_INVALID_HANDLE );

            LogError( ( "Failed to generate random number. "
                        "Failed to initialize PKCS #11 session." ) );
        }
    }

    if( pkcs11Status == CKR_OK )
    {
        if( pFunctionList->C_GenerateRandom( session,
                                             ( uint8_t * ) ( &randomNum ),
                                             sizeof( randomNum ) ) != CKR_OK )
        {
            LogError( ( "Failed to generate random number. "
                        "PKCS #11 API, C_GenerateRandom, failed to generate random number." ) );
        }
    }

    if( pkcs11Status == CKR_OK )
    {
        if( pFunctionList->C_CloseSession( session ) != CKR_OK )
        {
            LogError( ( " Failed to close PKCS #11 session after generating random number." ) );
        }
    }

    return randomNum;
}


/*************************************************************************************/

void initializeSystemClock( void )
{
    /* On boot-up initialize the system time as the first second in the configured year. */
    uint32_t startupTimeInUnixSecs = translateYearToUnixSeconds( democonfigSYSTEM_START_YEAR );

    systemClock.baseTime.secs = startupTimeInUnixSecs;
    systemClock.baseTime.msecs = 0;

    LogInfo( ( "System time has been initialized to the year %u", democonfigSYSTEM_START_YEAR ) );
    printTime( &systemClock.baseTime );

    /* Initialize semaphore for guarding access to system clock variables. */
    xMutex = xSemaphoreCreateMutex();
    configASSERT( xMutex );

    /* Clear the first time sync completed flag of the system clock object so that a "step" correction
     * of system time is utilized for the first time synchronization from a time server. */
    systemClock.firstTimeSyncDone = false;
}

/*-----------------------------------------------------------*/

static bool initializeSntpClient( SntpContext_t * pContext,
                                  const char ** pTimeServers,
                                  size_t numOfServers,
                                  uint8_t * pContextBuffer,
                                  size_t contextBufferSize,
                                  NetworkContext_t * pUdpContext,
                                  SntpAuthContext_t * pAuthContext )
{
    bool initStatus = false;

    /* Populate the list of time servers. */
    SntpServerInfo_t * pServers = pvPortMalloc( sizeof( SntpServerInfo_t ) * numOfServers );

    if( pServers == NULL )
    {
        LogError( ( "Unable to initialize SNTP client: Malloc failed for memory of configured time servers." ) );
    }
    else
    {
        UdpTransportInterface_t udpTransportIntf;
        SntpAuthenticationInterface_t symmetricKeyAuthIntf;

        for( uint8_t index = 0; index < numOfServers; index++ )
        {
            pServers[ index ].pServerName = pTimeServers[ index ];
            pServers[ index ].port = SNTP_DEFAULT_SERVER_PORT;
        }

        /* Set the UDP transport interface object. */
        udpTransportIntf.pUserContext = pUdpContext;
        udpTransportIntf.sendTo = UdpTransport_Send;
        udpTransportIntf.recvFrom = UdpTransport_Recv;

        /* Set the authentication interface object. */
        symmetricKeyAuthIntf.pAuthContext = pAuthContext;
        symmetricKeyAuthIntf.generateClientAuth = addClientAuthCode;
        symmetricKeyAuthIntf.validateServerAuth = validateServerAuth;

        /* Initialize context. */
        Sntp_Init( pContext,
                   pServers,
                   numOfServers,
                   democonfigSERVER_RESPONSE_TIMEOUT_MS,
                   pContextBuffer,
                   contextBufferSize,
                   resolveDns,
                   sntpClient_GetTime,
                   sntpClient_SetTime,
                   &udpTransportIntf,
                   &symmetricKeyAuthIntf );

        initStatus = true;
    }

    return initStatus;
}

/*-----------------------------------------------------------*/

static bool createUdpSocket( Socket_t * pSocket )
{
    bool status = false;
    struct freertos_sockaddr bindAddress;

    configASSERT( pSocket != NULL );

    /* Call the FreeRTOS+TCP API to create a UDP socket. */
    *pSocket = FreeRTOS_socket( FREERTOS_AF_INET,
                                FREERTOS_SOCK_DGRAM,
                                FREERTOS_IPPROTO_UDP );

    /* Check the socket was created successfully. */
    if( *pSocket == FREERTOS_INVALID_SOCKET )
    {
        /* There was insufficient FreeRTOS heap memory available for the socket
         * to be created. */
        LogError( ( "Failed to create UDP socket for SNTP client due to insufficient memory." ) );
    }
    else
    {
        /* Use a random UDP port for SNTP communication with server for protection against
         * spoofing vulnerability from "network off-path" attackers. */
        uint16_t randomPort = ( generateRandomNumber() % UINT16_MAX );
        bindAddress.sin_port = FreeRTOS_htons( randomPort );
        bindAddress.sin_family = FREERTOS_AF_INET;

        if( FreeRTOS_bind( *pSocket, &bindAddress, sizeof( bindAddress ) ) == 0 )
        {
            /* The bind was successful. */
            LogDebug( ( "UDP socket has been bound to port %u", randomPort ) );
            status = true;
        }
        else
        {
            LogError( ( "Failed to bind UDP socket to port %u", randomPort ) );
        }
    }

    return status;
}

/*-----------------------------------------------------------*/

static void closeUdpSocket( Socket_t * pSocket )
{
    bool status = false;

    configASSERT( pSocket != NULL );

    FreeRTOS_shutdown( *pSocket, FREERTOS_SHUT_RDWR );

    /* Close the socket again. */
    FreeRTOS_closesocket( *pSocket );
}

/*-----------------------------------------------------------*/

static bool calculateBackoffForNextPoll( BackoffAlgorithmContext_t * pBackoffContext,
                                         bool shouldInitializeContext,
                                         uint32_t minPollPeriod,
                                         uint32_t * pPollPeriod )
{
    uint16_t newPollPeriod = 0U;
    BackoffAlgorithmStatus_t status;

    configASSERT( pBackoffContext != NULL );
    configASSERT( pPollPeriod != NULL );

    if( shouldInitializeContext == true )
    {
        /* Initialize reconnect attempts and interval.*/
        BackoffAlgorithm_InitializeParams( pBackoffContext,
                                           minPollPeriod,
                                           SNTP_DEMO_POLL_MAX_BACKOFF_DELAY_SEC,
                                           SNTP_DEMO_MAX_SERVER_BACKOFF_RETRIES );
    }

    /* Generate a random number and calculate the new backoff poll period to wait before the next
     * time poll attempt. */
    status = BackoffAlgorithm_GetNextBackoff( pBackoffContext, generateRandomNumber(), &newPollPeriod );

    if( status == BackoffAlgorithmRetriesExhausted )
    {
        LogError( ( "All backed-off attempts of polling time server have expired: MaxAttempts=%d",
                    SNTP_DEMO_MAX_SERVER_BACKOFF_RETRIES ) );
    }
    else
    {
        /* Store the calculated backoff period as the new poll period. */
        *pPollPeriod = newPollPeriod;
    }

    return( status == BackoffAlgorithmSuccess );
}

/*-----------------------------------------------------------*/

void sntpTask( void * pParameters )
{
    SntpContext_t clientContext;
    bool initStatus = false;
    CK_RV pkcs11Status;

    /* Validate that the configured lists of time servers, authentication keys and key IDs
     * are of the same length. */
    configASSERT( numOfServers == ( sizeof( pAESCMACAuthKeys ) / sizeof( pAESCMACAuthKeys[ 0 ] ) ) );
    configASSERT( numOfServers == sizeof( pAuthKeyIds ) / sizeof( pAuthKeyIds[ 0 ] ) );

    /* Variable representing the SNTP client context. */
    static SntpContext_t context;

    /* Memory for the SNTP packet buffer in the SNTP context. */
    static uint8_t contextBuffer[ SNTP_PACKET_AUTHENTICATED_MODE_SIZE ];

    /* Memory for the network context representing the UDP socket that will be
     * passed to the SNTP client context. */
    static NetworkContext_t udpContext;

    /* Initialize PKCS11 module for cryptographic operations of AES-128-CMAC show
     * shown in this demo for authentication mechanism in SNTP communication with server. */
    pkcs11Status = xInitializePKCS11();
    configASSERT( pkcs11Status == CKR_OK );

    /* Memory for authentication context that will be passed to  the SNTP client context through
     * the authentication interface. This represents a combination of the time server and
     * its authentication key information that will be utilized for authentication communication
     * between client and server, if the server supports authentication. */
    static SntpAuthContext_t authContext;

    /* Context used for calculating backoff that is applied to polling interval when the configured
     * time server rejects time request.
     * Note: Backoff is applied to polling interval ONLY when a single server is configured in the demo
     * because in the case of multiple server configurations, the coreSNTP library handles server
     * rejection by rotating server. */
    static BackoffAlgorithmContext_t backoffContext;

    /* Initialize the authentication context for information for the first time server and its
     * keys configured in the demo. */
    populateAuthContextForServer( pTimeServers[ 0 ], &authContext );

    initStatus = initializeSntpClient( &clientContext,
                                       pTimeServers,
                                       numOfServers,
                                       contextBuffer,
                                       sizeof( contextBuffer ),
                                       &udpContext,
                                       &authContext );

    if( initStatus == true )
    {
        SntpStatus_t status;
        bool backoffModeFlag = false;

        /* Set the polling interval for periodic time synchronization attempts by the SNTP client. */
        systemClock.pollPeriod = democonfigSNTP_CLIENT_POLLING_INTERVAL_SECONDS;

        LogDebug( ( "Minimum SNTP client polling interval calculated as %lus", systemClock.pollPeriod ) );

        LogInfo( ( "Initialized SNTP Client context. Starting SNTP client loop to poll time every %lu seconds",
                   systemClock.pollPeriod ) );

        /* The loop of the SNTP Client task that synchronizes system time with a time server (in the configured list of time servers)
         * periodically at intervals of polling period. Each iteration of time synchronization is performed by calling the coreSNTP
         * APIs for sending time request to the server and receiving time response from the server. */
        while( 1 )
        {
            LogInfo( ( "---------STARTING DEMO---------\r\n" ) );
            bool socketStatus = false;

            /* For security, this demo keeps a UDP socket open only for one iteration of SNTP request-response cycle.
             * There is a security risk of a UDP socket being flooded with invalid or malicious server response packets
             * when a UDP socket is kept open across multiple time polling cycles. In such a scenario where the UDP
             * socket buffer has received multiple server response packets from a single time request, the extraneous
             * server response present in the UDP socket buffer will prevent the SNTP client application from correctly
             * reading network data of server responses that correspond to future time requests.
             * By closing the UDP socket after receiving the first acceptable server response (within the server response
             * timeout window), any extraneous or malicious server response packets for the same time request will be
             * ignored by the demo. */

            /* Wait for Networking */
            if( xPlatformIsNetworkUp() == pdFALSE )
            {
                LogInfo( ( "Waiting for the network link up event..." ) );

                while( xPlatformIsNetworkUp() == pdFALSE )
                {
                    vTaskDelay( pdMS_TO_TICKS( 1000U ) );
                }
            }

            /* Create a UDP socket for the current iteration of time polling. */
            socketStatus = createUdpSocket( &udpContext.socket );
            configASSERT( socketStatus == true );

            status = Sntp_SendTimeRequest( &clientContext, generateRandomNumber(), democonfigSEND_TIME_REQUEST_TIMEOUT_MS );
            configASSERT( status == SntpSuccess );

            /* Wait for server response for a maximum time of server response timeout. */
            do
            {
                /* Attempt to receive server response each time for a smaller block time
                 * than the total duration for the server response to time out. */
                status = Sntp_ReceiveTimeResponse( &clientContext, democonfigRECEIVE_SERVER_RESPONSE_BLOCK_TIME_MS );
            } while( status == SntpNoResponseReceived );

            /* Close the UDP socket irrespective of whether a server response is received. */
            closeUdpSocket( &udpContext.socket );

            /* Apply back-off delay before the next poll iteration if the demo has been configured with only
             * a single time server. */
            if( ( status == SntpRejectedResponse ) && ( numOfServers == 1 ) )
            {
                bool backoffStatus = false;

                /* Determine if this is the first back-off attempt we are making since the most recent server rejection
                 * for time request. */
                bool firstBackoffAttempt = false;

                if( backoffModeFlag == false )
                {
                    firstBackoffAttempt = true;

                    /* Set the flag to indicate we are in back-off retry mode for requesting time from the server. */
                    backoffModeFlag = true;
                }

                LogInfo( ( "The single configured time server, %s, rejected time request. Backing-off before ",
                           "next time poll....", strlen( pTimeServers[ 0 ] ) ) );

                /* Add exponential back-off to polling period. */
                backoffStatus = calculateBackoffForNextPoll( &backoffContext,
                                                             firstBackoffAttempt,
                                                             systemClock.pollPeriod,
                                                             &systemClock.pollPeriod );
                configASSERT( backoffStatus == true );

                /* Wait for the increased poll interval before retrying request for time from server. */
                vTaskDelay( pdMS_TO_TICKS( systemClock.pollPeriod * 1000 ) );
            }
            else
            {
                /* Reset flag to indicate that we are not backing-off for the next time poll. */
                backoffModeFlag = false;

                /* Wait for the poll interval period before the next iteration of time synchronization. */
                vTaskDelay( pdMS_TO_TICKS( systemClock.pollPeriod * 1000 ) );
            }
        }
    }
    else
    {
        configASSERT( false );

        /* Terminate the task as the SNTP client failed to be run. */
        LogError( ( "Failed to initialize SNTP client. Terminating SNTP client task.." ) );

        vTaskDelete( NULL );
    }
}

/*-----------------------------------------------------------*/

void systemGetWallClockTime( UTCTime_t * pTime )
{
    TickType_t xTickCount = 0;
    uint32_t ulTimeMs = 0UL;

    /* Obtain the mutext for accessing system clock variables. */
    xSemaphoreTake( xMutex, portMAX_DELAY );

    /* Calculate the current RAM-based time using a mathematical formula using
     * system clock state parameters and the time transpired since last synchronization. */
    calculateCurrentTime( &systemClock.baseTime,
                          systemClock.lastSyncTickCount,
                          systemClock.slewRate,
                          pTime );

    xSemaphoreGive( xMutex );
}

/*-----------------------------------------------------------*/