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.17.0
 
 * Fix typos in TLS version comments by @Kielek in https://github.com/open-telemetry/opamp-spec/pull/316

proto/opamp.proto

@@ -243,6 +243,15 @@ 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. The field
+    // numbers are reserved here to prevent accidental reuse.
+    reserved 12, 13;
+    reserved "trust_chain_response", "signature";
 }
 
 enum ServerToAgentFlags {
@@ -289,10 +298,75 @@ 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 {
+    message Certificate {
+        // The certificate in DER format.
+        bytes der_data = 1;
+    }
+
+    // The 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.
+    repeated Certificate 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;
+}
+
+// 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 = 1;
+
+    // Detached signature over the bytes of the payload field. MAY be empty
+    // on the first SignedServerToAgent of a connection: trust on the first
+    // message is established by validating the certificate chain carried in
+    // trust_chain_response against the Agent's pre-configured payload trust
+    // anchor. MUST be present and verifiable on every subsequent
+    // SignedServerToAgent.
+    bytes signature = 2;
+
+    // Sent only in the first SignedServerToAgent on a connection. Carries
+    // the signing certificate chain the Agent will use to verify signatures
+    // on subsequent messages. 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 = 3;
+}
+
 // 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.
@@ -781,6 +855,12 @@ 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;
     // Add new capabilities here, continuing with the least significant unused bit.
 }