File	Date	Author	Commit
clnt	2019-03-28	Thomas Behn	[053dc3] Initial commit
json	2019-03-28	Thomas Behn	[053dc3] Initial commit
log	2019-03-28	Thomas Behn	[053dc3] Initial commit
ntp	2019-03-28	Thomas Behn	[053dc3] Initial commit
nts	2019-03-28	Thomas Behn	[053dc3] Initial commit
srv	2019-03-28	Thomas Behn	[053dc3] Initial commit
COPYRIGHT	2019-03-28	Thomas Behn	[053dc3] Initial commit
Makefile	2019-03-28	Thomas Behn	[053dc3] Initial commit
README	2019-03-28	Thomas Behn	[b3b30a] Added NTS build instructions
README.pdf	2019-03-28	Thomas Behn	[053dc3] Initial commit
ntsd.c	2019-03-28	Thomas Behn	[053dc3] Initial commit
ntsd.h	2019-03-28	Thomas Behn	[053dc3] Initial commit

Read Me

NTSD (Network Time Security Daemon)
====================================================================================
Purpose:

NTSD connects NTS (Network Time Security) and NTPD (Network Time Protocol Daemon),
so that existing algorithms and mechanisms of NTPD can still be used and only the ethernet packet
exchange and the encryption, decryption and verification needs to get done by NTSD.
Thereby, it is ensured that on the one hand, clock filter, selection, cluster and discipline
algorithms can be used by NTS clients, and on the other hand NTS servers can make use
of NTPD‘s reference clock support to use i.e. a GPS receiver as time source.


====================================================================================
Requirements:

To allow communication between NTPD and NTSD, a tiny patch of NTPD is required in include/ntp_net.h (lines 228-235):


before:

#define  LOOPBACKADR  0x7f000001
#define  LOOPNETMASK  0xff000000

#define  ISBADADR(srcadr)					\
	   (IS_IPV4(srcadr)					\
	   && ((SRCADR(srcadr) & LOOPNETMASK)		\
	   == (LOOPBACKADR & LOOPNETMASK))			\
	   && SRCADR(srcadr) != LOOPBACKADR)



after:

#define  LOOPBACKADR  0x7f000001
#define  LOOPNETMASK  0xff000000
#define  LO_NTS_MIN   0x7f4e4f01  // minimum NTS loopback address 127.78.79.1
#define  LO_NTS_MAX   0x7f4e4fff  // maximum NTS loopback address 127.78.79.255

#define  ISBADADR(srcadr)                    	\
	   (IS_IPV4(srcadr)                    	\
	   && ((SRCADR(srcadr) & LOOPNETMASK)  	\
	   == (LOOPBACKADR & LOOPNETMASK))		\
	   && ((SRCADR(srcadr) < LO_NTS_MIN) ||	\
	   (SRCADR(srcadr) > LO_NTS_MAX))      	\
	   && SRCADR(srcadr) != LOOPBACKADR)



In addition, the NTPD configuration needs to be adapted so that no socket is being bound to the wildcard address and port 123. This can be done with the „interface no wildcard“ option. Afterwards, all addresses that shall be used by NTPD need to be enabled, i.e. „interface listen 127.0.0.1“.

Example ntp.conf:
(including NTS server (127.78.79.1) and standard NTP server (172.16.100.236)


interface ignore wildcard
interface listen 127.0.0.1
interface listen 172.16.100.239

server 127.78.79.1 minpoll 4 maxpoll 4 iburst
server 172.16.100.236 minpoll 4 maxpoll 4 iburst



NTS:

The NTS-API is expected to be built in the nts/build/inst directory in the ntsd project directory.
Therefore, change to the nts folder and clone the NTS project from git@gitlab.com:MLanger/nts.git.

cd nts
git clone git@gitlab.com:MLanger/nts.git

Create a build folder in the nts directory and change into it.

mkdir build
cd build

Prepare the build process with cmake and build the library, afterwards.

cmake -DCMAKE_INSTALL_PREFIX=inst -DCMAKE_BUILD_TYPE=Release ../
make install


Afterwards, you can build NTSd in the root project folder.

cd ../../
make


====================================================================================
Procedure:

NTSD is divided into a client and a server branch.

The basic idea of the client branch is to intercept NTP client packets, encrypt them using the NTS API and to forward them to the configured NTS server, afterwards. Therefore, one localhost server (starting from 127.78.79.1) is added to the ntp.conf for each NTS server that shall be used. NTSD listens on these addresses and forwards the client packets. The packet delay between NTPD and NTSD, as well as the encryption and decryption delay are being compensated later in the T2 and T3 timestamps of the server packet.

The server branch of NTSD sends an NTP client packet to the local NTPD (127.0.0.1) once per second to create a packet template with correct quality and status indicators (i.e. stratum, precision, root delay, ...). In addition, a configurable number of listening threads waits for NTS client packets, decrypts and verifies each packet, fills it with above mentioned quality and status indicators and the appropriate receive, reference and transmit timestamps (compensated by a previously measured encryption duration), encrypts the packet again and sends it back to the NTS client.


Each branch (client and server) can be disabled via the configuration file, so one can either run client-only, server-only or client-server mode.



====================================================================================
Configuration:

The NTSD configuration file is in JSON format. The following example configuration shows all possible parameters:


{
	"client" : {
		"base_internal_address" : "127.78.79.1",
		"base_local_port" : 57879,
		"references" : [
			{
				"internal_address" : "127.78.79.45",
				"local_port" : 60445,
				"remote_address" : "172.16.100.236",
				"remote_port" : 58879	
			},
			{
				"remote_address" : "172.27.38.16",
				"remote_port" : 123
			},
			{
				"remote_address" : "172.27.38.17",
				"remote_port" : 123
			}
		]
	},

	"server" : {
		"listening_port" : 58879,
		"listening_threads" : 8,
		"on_crypt_error" : "ignore"
	}
}



client – configuration of the NTSD client branch
base_internal_address – used by a reference, if no internal_address is specified, incremented by one for each reference, that uses it
base_local_port – used by a reference, if no local_port is specified, incremented by one for each reference, that uses it
references – array of NTS server configurations
(empty array to disable client mode)

internal_address – internal address used for communication with NTPD
local_port – local UDP source port used for communication with NTS server
remote_address – remote destination address of the NTS server
remote_port – remote destination port of the NTS server


server – configuration of the NTSD server branch
listening_port – UDP listening port used for communication with NTS clients
listening_threads – number of listening threads that shall be started
(0 to disable server mode)
on_crypt_error – behaviour on decryption or verification error (i.e. „kod“)



====================================================================================
Copyright:

*****************************************************************************
*                                                                           *
*           XXX   XXX     XXXXXXXXX      XXXXXXX       XXXXXXX              *
*           XXX   XXX     XXXXXXXXX     XXXXXXXXX      XXX  XXX             *
*           XXXX  XXX        XXX        XXX            XXX   XXX            *
*           XXXXX XXX        XXX         XXXXXX        XXX   XXX            *
*           XXX XXXXX        XXX           XXXXXX      XXX   XXX            *
*           XXX  XXXX        XXX        XX    XXX      XXX   XXX            *
*           XXX   XXX        XXX        XXXXXXXXX      XXX  XXX             *
*           XXX   XXX        XXX         XXXXXXX       XXXXXXX              *
*                                                                           *
*          NETWORK TIME SECURITY DAEMON - CONNECTING NTS AND NTPD           *
*                                                                           *
*    ==================================================================     *
*                                                                           *
*    Copyright (c) Meinberg Funkuhren GmbH & Co. KG 2018                    *
*    Author of this software: Thomas Behn <thomas.behn@meinberg.de>         *
*                                                                           *
*    All Rights Reserved                                                    *
*                                                                           *
*    Redistribution and use in source and binary forms, with or without     *
*    modification, are permitted provided that the following conditions     *
*    are met:                                                               *
*    1. Redistributions of source code must retain the above copyright      *
*       notice, this list of conditions and the following disclaimer.       *
*    2. Redistributions in binary form must reproduce the above             *
*       copyright notice, this list of conditions and the following         *
*       disclaimer in the documentation and/or other materials provided     *
*       with the distribution.                                              *
*                                                                           *
*    THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS     *
*    OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED      *
*    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE     *
*    ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE       *
*    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR    *
*    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT      *
*    OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR     *
*    BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF             *
*    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT              *
*    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE      *
*    USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH       *
*    DAMAGE.                                                                *
*                                                                           *
*    ==================================================================     *
*                                                                           *
*****************************************************************************