Sign Through a Bursa KES Agent
Este contenido aún no está disponible en español.
A block producer normally keeps its KES signing key in its own keys Secret. With a KES agent, the key stays in a Bursa KES agent instead. Dingo sends each block header to the agent over TLS, and the agent signs it. The keys Secret carries only the VRF key and the operational certificate.
This page covers dingo-operator v0.2.0, Dingo v0.94.0, and Bursa v0.25.0.
How the parts connect
Section titled “How the parts connect”| Part | Role | Configured with |
|---|---|---|
| Bursa KES agent | Holds the KES key for each pool and signs headers in sign mode. It serves remote producers on its attested listener, and runs one profile per pool. | The kes_agent YAML block. See the Bursa configuration reference. |
| Dingo | Connects to the agent, admits it, and asks it to sign each header it forges. | The remote KES agent settings. See the Dingo configuration reference. |
| dingo-operator | Renders Dingo’s agent settings from the DingoNode, mounts the client certificate, and validates the keys Secret. | spec.blockProducer.signingAgent |
Requirements
Section titled “Requirements”- Dingo v0.94.0 or later. dingo-operator v0.2.0 refuses Dingo images older
than v0.93.0 when
signingAgentis set. Agent profiles, which let one agent serve several pools, need v0.94.0. Setspec.image.tagexplicitly. - Rotation mode
AssistedorMonitorOnly. dingo-operator v0.2.0 refusessigningAgenttogether withrotation.mode: Auto. Its Auto mode generates the KES key inside the operator, and that key would never reach the agent. Rotate the key by hand as described below. - A TLS link to the agent. Pin the agent’s server key, and give the node a client certificate when the agent requires one. A plain TCP link is available for setups where something else secures the connection, such as a service mesh.
Configure the agent
Section titled “Configure the agent”Add the remote listener and one profile per pool to the agent’s kes_agent
configuration. The listener requires TLS 1.3. It asks producers for a client
certificate only when attested_client_ca_file is set.
kes_agent: mode: sign attested_listen_address: ":7000" attested_tls_cert_file: /etc/bursa/kes-agent/tls/tls.crt attested_tls_key_file: /etc/bursa/kes-agent/tls/tls.key attested_client_ca_file: /etc/bursa/kes-agent/client-ca/ca.crt attestation_provider: none profiles: - name: pool-a cold_vkey_hex: "<the pool's 32-byte cold verification key in hex>" system_start: "2022-10-25T00:00:00Z" slots_per_kes_period: 129600 guard_file: /var/lib/bursa/pool-a.guardWith profiles set, leave the single-pool fields (cold_vkey_file,
cold_vkey_hex, system_start, shelley_start_slot, shelley_start_time,
slots_per_kes_period, max_clock_skew, guard_file) unset at the top level,
and leave slot_length and max_kes_evolutions at their defaults. Set them in
each profile instead. See Profiles.
With guard files, the agent keeps each KES key in memory only. A guard file
keeps the profile’s KES period floor across a restart, not its key. After the
agent restarts, no profile has an active key, and the node cannot sign until
you install a new key and certificate as described in
Rotate the KES key. To keep keys across restarts,
replace the guard files with a PostgreSQL store under kes_agent.store and set
its age_recipients and age_identity_file. The agent then seals each
profile’s key in the database and loads it again at startup. This works with
one replica, and it is also how several replicas share a key.
The agent logs its server key fingerprint at startup as server_spki_sha256.
That value is the pin the node uses. You can also compute it from the server
certificate:
openssl x509 -in tls.crt -pubkey -noout \ | openssl pkey -pubin -outform der \ | sha256sumConfigure the DingoNode
Section titled “Configure the DingoNode”Create two Secrets in the same namespace as the DingoNode resource. The
examples use the cardano namespace from the operator’s quick start; use
whichever namespace your DingoNode runs in.
- The keys Secret holds
vrf.skeyand the operational certificate asopcert.cert. The operator also accepts the namenode.cert, which the Dingo Helm chart uses. Leavekes.skeyout: a node that signs through an agent does not use a local KES key, and the operator reports one as ignored. - The client certificate Secret holds
tls.crtandtls.key, issued by the CA in the agent’sattested_client_ca_file.
kubectl -n cardano create secret generic producer-pool-keys \ --from-file=vrf.skey --from-file=opcert.certkubectl -n cardano create secret tls kes-agent-client \ --cert=client.crt --key=client.keyThen point the block producer at the agent:
apiVersion: dingo.blinklabs.io/v1alpha1kind: DingoNodemetadata: name: producer namespace: cardanospec: role: blockProducer network: preview image: tag: "0.94.0" environment: # The agent profile this pool signs under. CARDANO_SHELLEY_KES_AGENT_PROFILE: pool-a topology: relayRefs: [relay] blockProducer: poolId: <pool id, bech32 or hex> keys: secretRef: producer-pool-keys rotation: mode: Assisted signingAgent: address: kes-agent.signing.svc:7000 serverSpkiSha256: <64 hex characters> clientCertSecretRef: kes-agent-clientThe operator sets Dingo’s agent address, pin, and client certificate paths
from signingAgent, and refuses spec.environment overrides of those
settings. The profile is set through spec.environment, as above. Dingo reads
the client certificate at startup, so the operator restarts the pod when the
client certificate Secret changes.
The operational certificate must match the agent
Section titled “The operational certificate must match the agent”When Dingo connects to the agent, it compares the agent’s operational
certificate with the one in its own key file, byte for byte. It admits the
agent when the two are identical. When they differ, Dingo takes the agent’s
certificate only if it is for the same cold key with a higher counter, and
reloads its credentials with it once the certificate validates. Any other difference refuses the agent, and
Dingo logs agent's operational certificate is not the local one.
A running node keeps forging with the credentials it has loaded. A reload also refuses a changed certificate that does not raise the counter. A wrong certificate in the keys Secret can therefore go unnoticed until the pod restarts, and the restarted node cannot sign. Always deliver the exact file that was installed in the agent.
Rotate the KES key
Section titled “Rotate the KES key”Rotate before the current key runs out of KES periods. Run the agent commands
inside the agent’s container: the control socket is local to the agent. Pass
--profile to select the pool. Work in a new, empty directory for each
rotation: --out refuses to overwrite an existing file, and it does so only
after the agent has staged the key.
-
Generate a staged key in the agent and save its verification key:
Terminal window bursa kes-agent control --config /etc/bursa/kes-agent/config.yaml \--profile pool-a gen-staged-key --out kes.vkey -
Issue an operational certificate for
kes.vkeywith the pool’s cold key, offline. Start it at the current KES period, which is the current slot divided by the slots per KES period. The ledger accepts a counter equal to the pool’s on-chain counter or one above it. Use one above. When the pool has not forged a block since its current certificate was issued, that is the current certificate’s counter again:Terminal window bursa cert op-cert --kes-vkey kes.vkey --cold-skey cold.skey \--counter <on-chain counter + 1> --kes-period <current period> \--out node.cert -
Install the certificate in the agent, then check the result:
Terminal window bursa kes-agent control --config /etc/bursa/kes-agent/config.yaml \--profile pool-a install-key --opcert node.certbursa kes-agent control --config /etc/bursa/kes-agent/config.yaml \--profile pool-a infoinfoshould reporthas_active_key: trueand the newactive_issue_number. -
Confirm the agent serves exactly this file. The two values must be equal:
Terminal window bursa kes-agent control --config /etc/bursa/kes-agent/config.yaml \--profile pool-a info | jq -r .info.active_opcertjq -r .cborHex node.cert -
Put the same
node.certinto the keys Secret asopcert.cert. The operator validates the bundle and delivers it to the pod.
Install first, then update the Secret, and do both in one sitting. From
install-key on, the agent signs only headers that carry the new
certificate, so the node cannot sign until it has switched over:
- The new counter is higher than the node’s. The running node picks up
the agent’s certificate at its next connection to the agent, and logs
block producer credentials reloadedwithsourceset tokes agent. The Secret update then makes a restart load the same certificate. - The counter is unchanged, because the pool has not forged since the previous rotation. Dingo does not take a same-counter certificate from the agent, and does not reload one in place. The operator restarts the pod when the Secret changes, and the restarted node loads the new certificate.
In the reverse order, the Secret would hold a certificate the agent does not serve yet, and a restart in between would leave the node unable to sign.