Add Message Attestation for ServerToAgent messages

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## Unreleased
+
+* Add `Message Attestation` section to specification.md describing an
+  optional, end-to-end integrity mechanism for `ServerToAgent` messages
+  based on X.509 certificate chains and a per-connection trust handshake.
+  Strict opt-in at the wire level: existing OpAMP deployments are
+  unaffected until both Server and Agent opt in.
+* Add `AgentCapabilities.RequiresPayloadTrustVerification = 0x00010000`.
+* Add `ServerCapabilities.OffersPayloadTrustVerification = 0x00000080`.
+* Add new top-level `SignedServerToAgent` envelope message containing
+  the marshalled `ServerToAgent` `payload`, a detached `signature` over
+  the payload bytes, and (on the first message of a connection) the
+  `trust_chain_response` carrying the signing certificate chain. The
+  envelope is used only when payload trust verification has been
+  negotiated; otherwise the Server keeps sending plain `ServerToAgent`
+  messages on the wire, byte-identical to upstream OpAMP.
+* Add new top-level `TrustChainResponse` message containing the
+  certificate chain and an optional error message.
+* Reserve field numbers 12 and 13 on `ServerToAgent` (briefly used by
+  an earlier draft for inline trust-chain and signature fields; that
+  draft was superseded by the `SignedServerToAgent` envelope so the
+  numbers can never be reused).
+
 ## v0.18.0
 
 * Fix OpAMP port in example by @tigrannajaryan in https://github.com/open-telemetry/opamp-spec/pull/331

proto/opamp.proto

@@ -244,6 +244,19 @@ message ServerToAgent {
     // A custom message sent from the Server to an Agent.
     // Status: [Development]
     CustomMessage custom_message = 11;
+
+    // Field numbers 12 and 13 were briefly assigned to inline payload
+    // trust verification metadata (trust_chain_response and signature)
+    // in an earlier draft of the Message Attestation spec. The design
+    // moved that metadata onto a separate envelope message
+    // (SignedServerToAgent) to enable detached signing. Field numbers
+    // 14–16 are assigned to SignedServerToAgent.payload, .signature,
+    // and .trust_chain_response respectively, so that the two messages
+    // have non-overlapping field numbers and cannot be accidentally
+    // misinterpreted by a parser expecting the other type. All six
+    // field numbers are reserved here to prevent reuse on ServerToAgent.
+    reserved 12, 13, 14, 15, 16;
+    reserved "trust_chain_response", "signature", "payload";
 }
 
 enum ServerToAgentFlags {
@@ -290,10 +303,82 @@ enum ServerCapabilities {
     // The Server can accept ConnectionSettingsRequest and respond with an offer.
     // Status: [Development]
     ServerCapabilities_AcceptsConnectionSettingsRequest = 0x00000040;
+    // The Server can respond to the payload trust verification handshake and
+    // sign every ServerToAgent message it sends after the handshake. See the
+    // Message Attestation section of the specification.
+    // Status: [Development]
+    ServerCapabilities_OffersPayloadTrustVerification = 0x00000080;
 
     // Add new capabilities here, continuing with the least significant unused bit.
 }
 
+// TrustChainResponse carries the signing certificate chain used by the Server
+// to sign subsequent ServerToAgent messages, as part of the payload trust
+// verification handshake. See the Message Attestation section of the
+// specification.
+// Status: [Development]
+message TrustChainResponse {
+    // PEM-encoded certificate chain, ordered from the first intermediate
+    // certificate down to the signing leaf certificate. The root certificate
+    // is excluded; the Agent already possesses the root as its pre-configured
+    // payload trust anchor. Multiple certificates are concatenated in a single
+    // PEM blob, consistent with the encoding used by TLSCertificate.
+    bytes certificate_chain = 1;
+
+    // Human-readable error message indicating why the Server could not
+    // satisfy the trust chain request. If error_message is set, the Agent
+    // MUST terminate the connection.
+    string error_message = 2;
+
+    // PEM-encoded root CA certificate used as the payload trust anchor.
+    // Set only during Trust On First Use (TOFU) enrollment: the Server
+    // includes this when the Agent has advertised
+    // AgentCapabilities_AcceptsPayloadTrustAnchorTOFU and the Agent has no
+    // pre-configured trust anchor. The Agent MUST persist this certificate
+    // and use it as the payload trust anchor for all subsequent connections.
+    // The Agent MUST NOT update a previously persisted or operator-configured
+    // trust anchor — if the Agent already has a trust anchor this field MUST
+    // be ignored. To rotate a TOFU-enrolled anchor the operator deletes the
+    // persisted anchor file and restarts the Agent (out-of-band rotation).
+    // See the Trust On First Use (TOFU) section of the specification.
+    bytes tofu_trust_anchor = 3;
+}
+
+// SignedServerToAgent wraps a ServerToAgent message when the payload trust
+// verification handshake has been negotiated between Server and Agent. When
+// both AgentCapabilities_RequiresPayloadTrustVerification (set by the Agent)
+// and ServerCapabilities_OffersPayloadTrustVerification (set by the Server)
+// are advertised, every Server-to-Agent message on the connection is wrapped
+// in SignedServerToAgent.
+//
+// The signature is computed and verified over the bytes of the payload field
+// exactly as they appear on the wire (a "detached" signature). This avoids
+// any dependency on canonical protobuf encoding, which is not guaranteed
+// across protobuf library versions, schema changes, or build flags.
+//
+// See the Message Attestation section of the specification.
+// Status: [Development]
+message SignedServerToAgent {
+    // Serialised bytes of a ServerToAgent message. The Agent verifies the
+    // detached signature over these exact bytes, without re-marshalling,
+    // and then unmarshals them into a ServerToAgent for normal processing.
+    bytes payload = 14;
+
+    // Detached signature over the bytes of the payload field. MUST be
+    // present and verifiable on every SignedServerToAgent, including the
+    // first. There is no exception for the first message.
+    bytes signature = 15;
+
+    // Sent only in the first SignedServerToAgent on a connection. Carries
+    // the signing certificate chain the Agent uses to validate the leaf
+    // certificate and verify signatures on all messages including this one.
+    // If the Agent set
+    // RequiresPayloadTrustVerification but the first SignedServerToAgent
+    // does not include a usable trust_chain_response, the Agent MUST
+    // terminate the connection.
+    TrustChainResponse trust_chain_response = 16;
+}
+
 // The OpAMPConnectionSettings message is a collection of fields which comprise an
 // offer from the Server to the Agent to use the specified settings for OpAMP
 // connection.
@@ -782,6 +867,21 @@ enum AgentCapabilities {
     // The agent will report ConnectionSettingsOffers status via AgentToServer.connection_settings_status field.
     // Status: [Development]
     AgentCapabilities_ReportsConnectionSettingsStatus = 0x00008000;
+    // The Agent requires the payload trust verification handshake on connection
+    // and signature verification on every subsequent ServerToAgent message.
+    // If the Server does not offer this capability, the Agent MUST terminate
+    // the connection. See the Message Attestation section of the specification.
+    // Status: [Development]
+    AgentCapabilities_RequiresPayloadTrustVerification = 0x00010000;
+    // The Agent supports Trust On First Use (TOFU) enrollment for the payload
+    // trust anchor. When set alongside
+    // AgentCapabilities_RequiresPayloadTrustVerification it signals that the
+    // Agent has no pre-configured trust anchor and asks the Server to include
+    // the root CA in trust_chain_response.tofu_trust_anchor so the Agent can
+    // bootstrap and persist it. MUST NOT be set if the Agent already has a
+    // persisted or operator-configured trust anchor.
+    // Status: [Development]
+    AgentCapabilities_AcceptsPayloadTrustAnchorTOFU = 0x00020000;
     // Add new capabilities here, continuing with the least significant unused bit.
 }