Improve KES interface

[edsko]

The KES interface (https://github.com/input-output-hk/cardano-base/blob/master/cardano-crypto-class/src/Cardano/Crypto/KES/Class.hs) should be improved:

• It needs documentation
• The two different use cases of Natural in the mock implementation should be newtyped
• Most importantly, updateKES should get an argument: the KES period to evolve to.

We might after all have to skip some periods. For the mock, I can implement this as

-- | Update key to specified period
--
-- Throws an error if the key is already /past/ the period
updateKESTo :: forall m v. (MonadRandom m, HasCallStack, KESAlgorithm v)
            => ContextKES v
            -> Natural -- ^ KES period to evolve to
            -> SignKeyKES v
            -> m (Maybe (SignKeyKES v))
updateKESTo ctxt evolveTo = go
  where
    go :: SignKeyKES v -> m (Maybe (SignKeyKES v))
    go key
      | iterationCountKES ctxt key < evolveTo = do
          mKey' <- updateKES ctxt key
          case mKey' of
            Nothing   -> return Nothing
            Just key' -> go key'
      | iterationCountKES ctxt key == evolveTo =
          return (Just key)
      | otherwise =
          error "updateKESTo: key already past period"

But I don't know if this is correct in the general case: does iterationCountKES return the period or the iteration count? If the former, this is correct generally, though we still might want to make this part of the main API; in that case, this function should also be renamed, as it's not the iteration count. If the iteration count is something separate from the rest, this function is wrong, but in that case documentation should be improved to document what this is.

[tdammers]

Is this still relevant? The current API has this signature:

updateKES
    :: HasCallStack
    => ContextKES v
    -> SignKeyKES v
    -> Period -- ^ The /current/ period for the key, not the target period
    -> Maybe (SignKeyKES v)

(We will however change the return type to IO (Maybe (SignKeyKES)) when implementing secure forgetting).

This still only forwards the key by one evolution (which is equivalent to one KES period), but it makes the current period explicit, so we can still tell which period we're evolving to. updateKESTo can easily be implemented in terms of this, if so desired.

In practical KES implementations, fast-forwarding isn't really feasible anyway; in order to forward the key n evolutions, we have to perform the single evolution calculation n times.

iterationCountKES has since been renamed to totalPeriodsKES; it indicates the number of evolutions a KES key can undergo before it becomes invalid.

What isn't explicitly documented yet is the relationship between KES periods and "iterations" or "evolutions" - but for practical intents and purposes, they are equivalent. More precisely:

• "KES periods" are 36-hour time slots, counting from Genesis. KES keys evolve once per KES period.
• Whenever we generate a fresh KES key and corresponding opcert, the opcert includes the KES period that maps to the KES key's 0th evolution (ocertKESPeriod).
• A KES key is associated with a "current evolution" (usually named t), so the key's current KES period is ocertKESPeriod + t