HORIZON HASKELLDocslts/ghc-9.14.xd82dee82026-10-12Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · d82dee8 · 2026-10-12

Modulekes-agent-1.3.0.0Haskell2010

Cardano.KESAgent.Processes.Agent

The main Agent program. The KES Agent opens two sockets:

  • A "control" socket, to which a control server can connect in order to push new keys into the agent.

  • A "service" socket, to which a Node can connect in order to receive the current KES key and future key updates.

The KES Agent has two slots, each of which can hold up to one KES key: - The "staged key" slot can hold just a raw KES signing key; this key is not shared with service clients, and there is no operational certificate linked to it. This slot is used to hold a key while an operational certificate for it is generated. Staged keys are not shared with other agents, and are always lost when the KES agent restarts. Staged keys do not have any validity attached to them; they become valid when an operational certificate is attached and they are moved to the active slot. Because of this, staged keys will never be evolved by the KES agent, and when a staged key is installed into the active slot, it will always be at evolution 0. - The "active" or "current" slot may hold a TaggedBundle. A tagged bundle is always tagged with a timestamp for synchronization purposes, and may hold a Bundle. A Bundle, then, consists of a signing key and a matching operational certificate. The active key is sent out to service clients in two situations: - When a service client first connects, the current key bundle is sent - When a new key bundle is installed into the active slot, it is sent out to all connected clients.

The KES Agent also takes care of evolving active keys to the current KES period, based on genesis parameters (EvolutionConfig) passed at agent creation and the host's RTC. While active keys are evolved inside the agent, these evolved keys will *not* be sent out to connected clients, because those clients will already have an earlier evolution of the key, and must evolve those themselves. The evolved key will, however, be served once to any service client connecting at a later time.

  • 5 types
  • 2 classes
  • 6 values
datadata AgentOptions (m :: Type -> Type) addr c
#

Configuration options for creating a new KES agent process.

Constructors

  • AgentOptions
    • agentTracer :: Tracer m AgentTrace
    • agentControlAddr :: Maybe addr

      Socket on which the agent will be listening for control messages, i.e., KES keys being pushed from a control server. For "relay" agents that don't need to receive any control connections, this can be Nothing.

    • agentServiceAddr :: addr

      Socket on which the agent will send KES keys to any connected nodes.

    • agentBootstrapAddr :: [addr]

      Sockets that the agent will use for bootstrapping from other agents.

    • agentEvolutionConfig :: EvolutionConfig

      Evolution configuration: genesis, slot duration, slots per KES period

    • agentGetCurrentTime :: m UTCTime

      Return the current time. Should normally be set to getPOSIXTime, but overriding this may be desirable for testing purposes.

    • agentColdVerKey :: VerKeyDSIGN (DSIGN c)

      Cold verification key, used for verifying operational certificates. The KES agent will only accept operational certificates signed using the corresponding cold signing key.

    • agentGenSeed :: m (MLockedSeed (SeedSizeKES (KES c)))

      Seed generator for generating KES signing keys. This is configurable for testing purposes. *It is vitally important for the security of generated keys that a cryptographically sound seed generator is used here. Production code should always use mlockedSeedNewRandom from cardano-crypto-class here.*

datadata EvolutionConfig
#

Evolution parameters used to determine which evolution of a given key is current, and when a key should evolve. Fields are named after the matching fields of the genesis JSON file.

Constructors

Instances5Eq, Ord, Show, FromJSON, ToJSON
classclass ControlCrypto c where
#

Crypto types for which control drivers are available.

Methods

Instances3ControlCrypto
classclass ServiceCrypto c where
#

Crypto types for which service drivers are available.

Methods

Instances3ServiceCrypto
datadata AgentTrace
#

Trace messages emitted from a KES agent process.

Constructors

Instances2Show, Pretty
  • Show AgentTraceDefined in kes-agent-1.3.0.0 · Cardano.KESAgent.Processes.Agent.Type
  • Pretty AgentTraceDefined in kes-agent-1.3.0.0 · Cardano.KESAgent.Processes.Agent.Type
datadata ServiceClientTrace
#

Trace logging messages a service client can generate.

Constructors

Instances2Show, Pretty
valuerunAgent
  1. :: (AgentContext m c, ControlCrypto c, ServiceCrypto c, ServiceClientDrivers c, Show addr, Show fd)
  2. => Agent c m fd addr
  3. -> m ()
#

Run an agent. This will spawn the following threads: - An evolution thread, which regularly checks whether the active key should be evolved, and if so, evolves it. - A service listener, listening on the configured service socket, spawning a service handler for each accepted service connection - A control listener, listening on the configured control socket, spawning a control handler for each accepted control connection - One bootstrap client thread for each configured bootstrapping address. Each bootstrap client acts as a service client to another agent, taking care of receiving incoming key updates, comparing them against the current active key, and installing them if they are valid and newer.