[Swan-dev] time representation in Pluto

[D. Hugh Redelmeier]

Generally speaking, time should not be represented within Pluto with a
uint64_t.

Most (not all!) times in system and library calls are time_t, which
may or may not be uint64_t (system dependent).

There are three kinds of time_t that are not the same.
So Pluto has three distinct types for these distinct purposes.  The
advantages are:

- the compiler can detect when you are mixing up kinds of time values:
  you will violate C's type system.

- the programmer has to clearly think out what kind of type is being
  used.

This is documented in linux/include/libreswan.h.  Here's a comment
from there:
 * realtime_t: absolute UTC time.  Might be discontinuous due to clock adjustment.
 * monotime_t: absolute monotonic time.	 No discontinuities (except for machine sleep?)
 * deltatime_t: relative time between events.  Presumed continuous.

I introduced these types because the uses were being mixed up and
this created at least one long-standing subtle bug.

The commit 1913dd115696793d8dc5d6b6fd3f8238408fc1d1 message says:

    - Add PLUTO_ADDTIME= for use in updown script. This is an epoch time
      stamp, since the IPsec SA was added to the kernel (NETKEY only)

I don't know what this means. Perhaps

    - ... This is the time_t representation of the UTC time when 
      the IPsec SA was added ...

Wall-clock time is "the time since the Epoch (00:00:00 UTC, January 1,
1970), measured in seconds." (see time(2)).

In Pluto, the type for wall-clock time is realtime_t.