coreSNTP v1.1.0
Client library for synchronizing device time with internet time using Simple Network Time Protocol (SNTP)
core_sntp_client.h
Go to the documentation of this file.
1/*
2 * coreSNTP v1.1.0
3 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
6 * this software and associated documentation files (the "Software"), to deal in
7 * the Software without restriction, including without limitation the rights to
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 * the Software, and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in all
13 * copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 */
22
32#ifndef CORE_SNTP_CLIENT_H_
33#define CORE_SNTP_CLIENT_H_
34
35/* Standard include. */
36#include <stdint.h>
37#include <stddef.h>
38#include <stdbool.h>
39
40/* Include coreSNTP Serializer header. */
42
43/* SNTP_DO_NOT_USE_CUSTOM_CONFIG allows building the SNTP library
44 * without a custom config. If a custom config is provided, the
45 * SNTP_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
46#ifndef SNTP_DO_NOT_USE_CUSTOM_CONFIG
47 /* Include custom config file before other headers. */
48 #include "core_sntp_config.h"
49#endif
50
51/* Include config defaults header to get default values of configs not
52 * defined in core_sntp_config.h file. */
54
55/* *INDENT-OFF* */
56#ifdef __cplusplus
57 extern "C" {
58#endif
59/* *INDENT-ON* */
60
71#define SNTP_DEFAULT_SERVER_PORT ( 123U )
72
77typedef struct SntpServerInfo
78{
79 const char * pServerName;
81 uint16_t port;
84
99typedef bool ( * SntpResolveDns_t )( const SntpServerInfo_t * pServerAddr,
100 uint32_t * pIpV4Addr );
101
117typedef void ( * SntpGetTime_t )( SntpTimestamp_t * pCurrentTime );
118
147typedef void ( * SntpSetTime_t )( const SntpServerInfo_t * pTimeServer,
148 const SntpTimestamp_t * pServerTime,
149 int64_t clockOffsetMs,
150 SntpLeapSecondInfo_t leapSecondInfo );
151
160struct NetworkContext;
161typedef struct NetworkContext NetworkContext_t;
162
194typedef int32_t ( * UdpTransportSendTo_t )( NetworkContext_t * pNetworkContext,
195 uint32_t serverAddr,
196 uint16_t serverPort,
197 const void * pBuffer,
198 uint16_t bytesToSend );
199
234typedef int32_t ( * UdpTransportRecvFrom_t )( NetworkContext_t * pNetworkContext,
235 uint32_t serverAddr,
236 uint16_t serverPort,
237 void * pBuffer,
238 uint16_t bytesToRecv );
239
245typedef struct UdpTransportIntf
246{
252
261struct SntpAuthContext;
262typedef struct SntpAuthContext SntpAuthContext_t;
263
303 const SntpServerInfo_t * pTimeServer,
304 void * pBuffer,
305 size_t bufferSize,
306 uint16_t * pAuthCodeSize );
307
342 const SntpServerInfo_t * pTimeServer,
343 const void * pResponseData,
344 uint16_t responseSize );
345
355typedef struct SntpAuthenticationIntf
356{
363
368
375
381typedef struct SntpContext
382{
392
397
403
408 uint8_t * pNetworkBuffer;
409
414
419
424
430
436
446
454
461
470
478
521/* @[define_sntp_init] */
523 const SntpServerInfo_t * pTimeServers,
524 size_t numOfServers,
525 uint32_t serverResponseTimeoutMs,
526 uint8_t * pNetworkBuffer,
527 size_t bufferSize,
528 SntpResolveDns_t resolveDnsFunc,
529 SntpGetTime_t getSystemTimeFunc,
530 SntpSetTime_t setSystemTimeFunc,
531 const UdpTransportInterface_t * pTransportIntf,
532 const SntpAuthenticationInterface_t * pAuthIntf );
533/* @[define_sntp_init] */
534
535
578/* @[define_sntp_sendtimerequest] */
580 uint32_t randomNumber,
581 uint32_t blockTimeMs );
582/* @[define_sntp_sendtimerequest] */
583
584
639/* @[define_sntp_receivetimeresponse] */
641 uint32_t blockTimeMs );
642/* @[define_sntp_receivetimeresponse] */
643
655/* @[define_sntp_statustostr] */
656const char * Sntp_StatusToStr( SntpStatus_t status );
657/* @[define_sntp_statustostr] */
658
659/* *INDENT-OFF* */
660#ifdef __cplusplus
661 }
662#endif
663/* *INDENT-ON* */
664
665#endif /* ifndef CORE_SNTP_CLIENT_H_ */
const char * Sntp_StatusToStr(SntpStatus_t status)
Converts SntpStatus_t to its equivalent string.
Definition: core_sntp_client.c:891
SntpStatus_t Sntp_ReceiveTimeResponse(SntpContext_t *pContext, uint32_t blockTimeMs)
Receives a time response from the server that has been requested for time with the Sntp_SendTimeReque...
Definition: core_sntp_client.c:815
SntpStatus_t Sntp_SendTimeRequest(SntpContext_t *pContext, uint32_t randomNumber, uint32_t blockTimeMs)
Sends a request for time from the currently configured server (in the context). If the user has provi...
Definition: core_sntp_client.c:427
SntpStatus_t Sntp_Init(SntpContext_t *pContext, const SntpServerInfo_t *pTimeServers, size_t numOfServers, uint32_t serverResponseTimeoutMs, uint8_t *pNetworkBuffer, size_t bufferSize, SntpResolveDns_t resolveDnsFunc, SntpGetTime_t getSystemTimeFunc, SntpSetTime_t setSystemTimeFunc, const UdpTransportInterface_t *pTransportIntf, const SntpAuthenticationInterface_t *pAuthIntf)
Initializes a context for SNTP client communication with SNTP/NTP servers.
Definition: core_sntp_client.c:43
This file represents the default values for the configuration macros of the coreSNTP library.
API for serializing SNTP request packets and, and de-serializing SNTP response packets....
int32_t(* UdpTransportRecvFrom_t)(NetworkContext_t *pNetworkContext, uint32_t serverAddr, uint16_t serverPort, void *pBuffer, uint16_t bytesToRecv)
Interface for user-defined function to receive the server response, to a time request (sent through t...
Definition: core_sntp_client.h:234
void(* SntpGetTime_t)(SntpTimestamp_t *pCurrentTime)
Interface for user-defined function to obtain the current system time in SNTP timestamp format.
Definition: core_sntp_client.h:117
SntpStatus_t(* SntpGenerateAuthCode_t)(SntpAuthContext_t *pContext, const SntpServerInfo_t *pTimeServer, void *pBuffer, size_t bufferSize, uint16_t *pAuthCodeSize)
Interface for user-defined function to generate and append authentication code in an SNTP request buf...
Definition: core_sntp_client.h:302
int32_t(* UdpTransportSendTo_t)(NetworkContext_t *pNetworkContext, uint32_t serverAddr, uint16_t serverPort, const void *pBuffer, uint16_t bytesToSend)
Interface for user-defined function to send time request as a single datagram to server on the networ...
Definition: core_sntp_client.h:194
void(* SntpSetTime_t)(const SntpServerInfo_t *pTimeServer, const SntpTimestamp_t *pServerTime, int64_t clockOffsetMs, SntpLeapSecondInfo_t leapSecondInfo)
Interface for user-defined function to update the system clock time so that it is synchronized the ti...
Definition: core_sntp_client.h:147
SntpStatus_t(* SntpValidateServerAuth_t)(SntpAuthContext_t *pContext, const SntpServerInfo_t *pTimeServer, const void *pResponseData, uint16_t responseSize)
Interface for user-defined function to authenticate server by validating the authentication code pres...
Definition: core_sntp_client.h:341
bool(* SntpResolveDns_t)(const SntpServerInfo_t *pServerAddr, uint32_t *pIpV4Addr)
Interface for user-defined function to resolve time server domain-name to an IPv4 address....
Definition: core_sntp_client.h:99
SntpLeapSecondInfo_t
Enumeration for leap second information that an SNTP server can send its response to a time request....
Definition: core_sntp_serializer.h:263
SntpStatus_t
Enumeration of status codes that can be returned by the coreSNTP Library API.
Definition: core_sntp_serializer.h:138
struct NetworkContext NetworkContext_t
A user-defined type for context that is passed to the transport interface functions....
Definition: core_sntp_client.h:161
struct SntpAuthContext SntpAuthContext_t
A user-defined type for context that is passed to the authentication interface functions....
Definition: core_sntp_client.h:262
Struct representing the authentication interface for securely communicating with time servers.
Definition: core_sntp_client.h:356
SntpGenerateAuthCode_t generateClientAuth
The user-defined function for appending client authentication data.
Definition: core_sntp_client.h:367
SntpAuthContext_t * pAuthContext
The user-defined context for storing information like key credentials required for cryptographic oper...
Definition: core_sntp_client.h:362
SntpValidateServerAuth_t validateServerAuth
The user-defined function for authenticating server from its SNTP response.
Definition: core_sntp_client.h:373
Structure for a context that stores state for managing a long-running SNTP client that periodically p...
Definition: core_sntp_client.h:382
UdpTransportInterface_t networkIntf
The user-defined interface for performing User Datagram Protocol (UDP) send and receive network opera...
Definition: core_sntp_client.h:435
SntpTimestamp_t lastRequestTime
Cache of the timestamp of sending the last time request to a server for replay attack protection by c...
Definition: core_sntp_client.h:460
uint32_t responseTimeoutMs
The timeout duration (in milliseconds) for receiving a response, through Sntp_ReceiveTimeResponse API...
Definition: core_sntp_client.h:476
SntpResolveDns_t resolveDnsFunc
The user-supplied function for resolving DNS name of time servers.
Definition: core_sntp_client.h:418
uint8_t * pNetworkBuffer
The user-supplied buffer for storing network data of both SNTP requests and SNTP response.
Definition: core_sntp_client.h:408
SntpSetTime_t setTimeFunc
The user-supplied function for correcting system time after receiving time from a server.
Definition: core_sntp_client.h:429
size_t numOfServers
Number of servers configured for use.
Definition: core_sntp_client.h:396
uint32_t currentServerAddr
Cache of the resolved Ipv4 address of the current server being used for time synchronization....
Definition: core_sntp_client.h:453
const SntpServerInfo_t * pTimeServers
List of time servers in decreasing priority order configured for the SNTP client. Only a single serve...
Definition: core_sntp_client.h:391
SntpGetTime_t getTimeFunc
The user-supplied function for obtaining the current system time.
Definition: core_sntp_client.h:423
uint16_t sntpPacketSize
State member for storing the size of the SNTP packet that includes both SNTP_PACKET_BASE_SIZE bytes p...
Definition: core_sntp_client.h:469
SntpAuthenticationInterface_t authIntf
The user-defined interface for incorporating security mechanism of adding client authentication in SN...
Definition: core_sntp_client.h:445
size_t currentServerIndex
The index for the currently configured time server for time querying from the list of time servers in...
Definition: core_sntp_client.h:402
size_t bufferSize
The size of the network buffer.
Definition: core_sntp_client.h:413
Structure representing information for a time server.
Definition: core_sntp_client.h:78
size_t serverNameLen
The length of the server name.
Definition: core_sntp_client.h:80
uint16_t port
The UDP port supported by the server for SNTP/NTP communication.
Definition: core_sntp_client.h:81
const char * pServerName
The time server name.
Definition: core_sntp_client.h:79
Structure representing an SNTP timestamp.
Definition: core_sntp_serializer.h:282
Struct representing the UDP transport interface for user-defined functions that coreSNTP library depe...
Definition: core_sntp_client.h:246
UdpTransportRecvFrom_t recvFrom
The user-defined UDP receive function.
Definition: core_sntp_client.h:250
UdpTransportSendTo_t sendTo
The user-defined UDP send function.
Definition: core_sntp_client.h:249
NetworkContext_t * pUserContext
The user-defined context for storing network socket information.
Definition: core_sntp_client.h:247