stsd - Secure Time Sync Daemon
==============================

Set system date based on HTTP 'date' headers over TLS.
Inspired by Whonix's sdwdate, and Madaidan's secure-time-sync script.


What's wrong with NTP?
----------------------
Standard NTP does not make use any kind of cryptography. No encryption, no
authentication. This means NTP requests can be sniffed and tampered with
to send a system the wrong time [1].
Correct system time is essential for the use of modern public key cryptography
(TLS/SSL for example).

stsd aims to overcome these shortcomings of NTP and provide a secure way of
keeping a system's time accurate.


How it works
------------
At random intervals (between 64 seconds and 1024 seconds) stsd sets the system
time based on the timestamp extracted from HTTP headers (RFC2616) over TLS.
The website it gets this header from is randomly selected from a pool file.

Optionally stsd can do this all over Tor; favouring onion addresses specified
in the pool file.


Caveats
-------
Currently stsd does a few things that are generally not ideal for
security-critical software:

 1. It must be run as root, since on most systems only root can change the
    system's date.
 2. It shells out to date(1) to update the system time.

In regard to the first caveat, stsd aims to follow the principle of least
privilege by only making network requests via an unprivileged child processs.
This unprivilged "network" process makes the necessary network request, then
sends the date information back to the parent process via a socket.
The parent process then sets the system time using its root privilges.


OS support
----------
As mentioned previously stsd works by shelling out to date(1) to set the system
time - as a side-effect of this all systems with a POSIX compliant date(1)
command are supported. This includes: 

 - {Net,Free,DragonFly,Open}BSD
 - MacOS
 - Most Linux distributions


Usage
-----
usage: stsd [--date-cmd=path] [--user=username] [--pool-file=file]
            [--use-proxy=proxy | --use-tor[=proxy]]
where:
  --date-cmd=path    absolute path to date command (default: '/bin/date').
  --user=username    user to run child process as (default: '_stsd').
  --pool-file=file   use the specified pool file (default: '/etc/stsd_pool').
  --use-proxy=proxy  proxy network requests through 'proxy' url.
  --use-tor          use tor for network requests. favours onion addresses
                     from the pool file. tor's proxy url can be configured
                     by passing as an argument flag: '--use-tor=proxy'
                     (default tor proxy url: 'socks5://localhost:9050').


Pool file format
----------------
The pool file contains a newline separated list of HTTPS URLs. Each URL can
optionally have an associated onion address.
The optional onion address will be favoured over the clearnet address when the
--use-tor argument is given.

Each line in the file is of the format:

	<url>[,onion]

Empty lines, and lines starting with a '#' are ignored.
An example pool file (stsd_pool_example) is provided.


See also
--------
If you use OpenBSD's OpenNTPD, it is possible to set 'constraint' URLs.
These tell ntpd to make use of HTTPS date headers to act as an authenticated
constraint - NTP packets falling outside of the range of the constraint are
discarded and NTP servers sending these packets are marked as invalid [2].
This strikes a good balance between the accuracy of NTP and authentication
via TLS.

sdwdate: https://www.whonix.org/wiki/Sdwdate
secure-time-sync: https://gitlab.com/madaidan/secure-time-sync


References
----------
1: https://blog.hboeck.de/archives/863-Dont-update-NTP-stop-using-it.html
2: https://man.openbsd.org/ntpd.conf#CONSTRAINTS (https://openntpd.org/)