Add bounded v2 drain receipts for Windows helper response transport

This commit is contained in:
2026-11-14 12:40:25 +01:00
parent 4a2fbef9ac
commit e6fe4cd285
4 changed files with 594 additions and 25 deletions
+113 -24
View File
@@ -7,6 +7,7 @@ use rmm_agent_core::{
};
use rmm_domain::jobs::hash;
use serde::{Deserialize, Serialize, de::DeserializeOwned};
use sha2::{Digest, Sha256};
use std::{
ffi::c_void,
fs::File,
@@ -29,7 +30,13 @@ use windows_sys::Win32::{
};
pub const HELPER_SERVICE: &str = "RmmDiscoverySystemHelper";
pub const PIPE_NAME: &str = r"\\.\pipe\RustDiscovery-System-v1";
// Framing v2 is deliberately a separate endpoint. Old peers cannot send a
// v1 call to this server or interpret the drain receipt as another reply.
pub const PIPE_NAME: &str = r"\\.\pipe\RustDiscovery-System-v2";
const FRAME_TAG: [u8; 8] = *b"RDPIPC02";
const DRAIN_TAG: [u8; 8] = *b"RDPACK02";
const FRAME_HEADER_LEN: usize = 12;
const DRAIN_RECEIPT_LEN: usize = 56;
pub const FRAME_LIMIT: usize = 1024 * 1024;
pub const CLIENT_PIPE_RIGHTS: u32 = 0x0012_0083; // data R/W, attributes R, RC, synchronize; no bit4
const READ_MASK: u32 = 0x0012_00a9;
@@ -44,6 +51,7 @@ pub enum Stage {
ClientSendFrame,
ClientReadReply,
ClientReplyBinding,
ClientDrainReceipt,
ClientReport,
ServerConnect,
ServerReadHeader,
@@ -54,6 +62,7 @@ pub enum Stage {
ServerCallBinding,
ServerRecheckPeer,
ServerReply,
ServerDrainReceipt,
Unclassified,
}
impl Stage {
@@ -66,6 +75,7 @@ impl Stage {
Self::ClientSendFrame => "client_send_frame",
Self::ClientReadReply => "client_read_reply",
Self::ClientReplyBinding => "client_reply_binding",
Self::ClientDrainReceipt => "client_drain_receipt",
Self::ClientReport => "client_report",
Self::ServerConnect => "server_connect",
Self::ServerReadHeader => "server_read_header",
@@ -76,6 +86,7 @@ impl Stage {
Self::ServerCallBinding => "server_call_binding",
Self::ServerRecheckPeer => "server_recheck_peer",
Self::ServerReply => "server_reply",
Self::ServerDrainReceipt => "server_drain_receipt",
Self::Unclassified => "unclassified",
}
}
@@ -123,6 +134,8 @@ fn known_code(text: &str) -> Option<&'static str> {
"HELPER_FRAME_CAPACITY",
"HELPER_FRAME_EMPTY",
"HELPER_FRAME_LENGTH",
"HELPER_FRAME_VERSION",
"HELPER_DRAIN_RECEIPT",
"HELPER_HANDLE",
"HELPER_IMAGE_PARENT",
"HELPER_IMAGE_SIZE",
@@ -1189,27 +1202,60 @@ fn encode(value: &impl Serialize) -> Result<Vec<u8>> {
ensure!(!writer.0.is_empty(), "HELPER_FRAME_EMPTY");
Ok(writer.0)
}
fn send(pipe: HANDLE, value: &impl Serialize, deadline: Instant) -> Result<()> {
let mut bytes = encode(value)?;
let mut header = u32::try_from(bytes.len())?.to_be_bytes();
transfer(pipe, &mut header, true, deadline)?;
transfer(pipe, &mut bytes, true, deadline)
fn frame_header(len: usize) -> Result<[u8; FRAME_HEADER_LEN]> {
ensure!((1..=FRAME_LIMIT).contains(&len), "HELPER_FRAME_LENGTH");
let mut header = [0; FRAME_HEADER_LEN];
header[..8].copy_from_slice(&FRAME_TAG);
header[8..].copy_from_slice(&u32::try_from(len)?.to_be_bytes());
Ok(header)
}
fn frame_length(header: [u8; 4]) -> Result<usize> {
let len = u32::from_be_bytes(header) as usize;
fn send_bytes(pipe: HANDLE, bytes: &mut [u8], deadline: Instant) -> Result<()> {
let mut header = frame_header(bytes.len())?;
transfer(pipe, &mut header, true, deadline)?;
transfer(pipe, bytes, true, deadline)
}
fn send(pipe: HANDLE, value: &impl Serialize, deadline: Instant) -> Result<()> {
send_bytes(pipe, &mut encode(value)?, deadline)
}
fn frame_length(header: [u8; FRAME_HEADER_LEN]) -> Result<usize> {
ensure!(header[..8] == FRAME_TAG, "HELPER_FRAME_VERSION");
let len = u32::from_be_bytes(header[8..].try_into()?) as usize;
ensure!((1..=FRAME_LIMIT).contains(&len), "HELPER_FRAME_LENGTH");
Ok(len)
}
fn length(pipe: HANDLE, deadline: Instant) -> Result<usize> {
let mut header = [0u8; 4];
let mut header = [0u8; FRAME_HEADER_LEN];
transfer(pipe, &mut header, false, deadline)?;
frame_length(header)
}
fn body<T: DeserializeOwned>(pipe: HANDLE, len: usize, deadline: Instant) -> Result<T> {
fn body_bytes(pipe: HANDLE, len: usize, deadline: Instant) -> Result<Vec<u8>> {
ensure!((1..=FRAME_LIMIT).contains(&len), "HELPER_FRAME_LENGTH");
let mut bytes = vec![0u8; len];
transfer(pipe, &mut bytes, false, deadline)?;
Ok(serde_json::from_slice(&bytes)?)
Ok(bytes)
}
fn body<T: DeserializeOwned>(pipe: HANDLE, len: usize, deadline: Instant) -> Result<T> {
Ok(serde_json::from_slice(&body_bytes(pipe, len, deadline)?)?)
}
// This fixed-size receipt only acknowledges receipt of these transport bytes.
// It never acknowledges durable evidence, clears state, or permits an effect.
fn drain_receipt(challenge: Uuid, reply_bytes: &[u8]) -> [u8; DRAIN_RECEIPT_LEN] {
let mut receipt = [0; DRAIN_RECEIPT_LEN];
receipt[..8].copy_from_slice(&DRAIN_TAG);
receipt[8..24].copy_from_slice(challenge.as_bytes());
receipt[24..].copy_from_slice(&Sha256::digest(reply_bytes));
receipt
}
fn verify_drain_receipt(
receipt: &[u8; DRAIN_RECEIPT_LEN],
challenge: Uuid,
reply_bytes: &[u8],
) -> Result<()> {
ensure!(
*receipt == drain_receipt(challenge, reply_bytes),
"HELPER_DRAIN_RECEIPT"
);
Ok(())
}
pub struct Server {
@@ -1305,13 +1351,24 @@ impl Server {
peer.check().context(Stage::ServerRecheckPeer)?;
Ok(Some(Received { call, peer }))
}
pub fn reply(&self, value: &Reply) -> Result<()> {
send(
self.pipe.as_raw_handle(),
value,
Instant::now() + Duration::from_secs(5),
)
.context(Stage::ServerReply)
pub fn reply(&self, value: &Reply, peer: &mut PeerProof) -> Result<()> {
// Do not disconnect after WriteFile merely copied bytes into a pipe
// buffer. Wait for a receipt from the same fully pinned peer within
// the original reply deadline, without an unbounded FlushFileBuffers.
let deadline = Instant::now() + Duration::from_secs(5);
peer.check().context(Stage::ServerRecheckPeer)?;
let mut bytes = encode(value).context(Stage::ServerReply)?;
send_bytes(self.pipe.as_raw_handle(), &mut bytes, deadline).context(Stage::ServerReply)?;
let mut receipt = [0; DRAIN_RECEIPT_LEN];
transfer(self.pipe.as_raw_handle(), &mut receipt, false, deadline)
.context(Stage::ServerDrainReceipt)?;
verify_drain_receipt(&receipt, value.challenge, &bytes)
.context(Stage::ServerDrainReceipt)?;
peer.check().context(Stage::ServerRecheckPeer)?;
if Instant::now() >= deadline {
return Err(anyhow::anyhow!("HELPER_PIPE_TIMEOUT")).context(Stage::ServerDrainReceipt);
}
Ok(())
}
pub fn disconnect(&self) {
unsafe {
@@ -1345,7 +1402,9 @@ pub fn exchange(pin: &Pin, call: &Call, timeout: Duration) -> Result<Reply> {
.context(Stage::ClientHelperPeer)?;
send(pipe.as_raw_handle(), call, deadline).context(Stage::ClientSendFrame)?;
let len = length(pipe.as_raw_handle(), deadline).context(Stage::ClientReadReply)?;
let reply: Reply = body(pipe.as_raw_handle(), len, deadline).context(Stage::ClientReadReply)?;
let reply_bytes =
body_bytes(pipe.as_raw_handle(), len, deadline).context(Stage::ClientReadReply)?;
let reply: Reply = serde_json::from_slice(&reply_bytes).context(Stage::ClientReadReply)?;
peer.check().context(Stage::ClientHelperPeer)?;
if !(reply.schema_version == 1
&& reply.challenge == call.challenge
@@ -1366,6 +1425,11 @@ pub fn exchange(pin: &Pin, call: &Call, timeout: Duration) -> Result<Reply> {
) {
return Err(anyhow::anyhow!("HELPER_REPLY_OPERATION")).context(Stage::ClientReplyBinding);
}
// Only a complete, authenticated, bound and operation-checked reply gets
// this receipt. Hash the received bytes, never a JSON re-serialization.
let mut receipt = drain_receipt(call.challenge, &reply_bytes);
transfer(pipe.as_raw_handle(), &mut receipt, true, deadline)
.context(Stage::ClientDrainReceipt)?;
Ok(reply)
}
@@ -1388,12 +1452,21 @@ mod tests {
#[test]
fn untrusted_lengths_are_rejected_before_body_allocation() {
for n in [0, (FRAME_LIMIT + 1) as u32, u32::MAX] {
assert!(frame_length(n.to_be_bytes()).is_err());
let mut header = [0; FRAME_HEADER_LEN];
header[..8].copy_from_slice(&FRAME_TAG);
header[8..].copy_from_slice(&n.to_be_bytes());
assert!(frame_length(header).is_err());
assert!(frame_header(n as usize).is_err());
}
assert_eq!(
frame_length((FRAME_LIMIT as u32).to_be_bytes()).unwrap(),
FRAME_LIMIT
);
let header = frame_header(FRAME_LIMIT).unwrap();
assert_eq!(frame_length(header).unwrap(), FRAME_LIMIT);
// Neither a v1 length prefix nor another framing version is accepted.
let mut old = [0; FRAME_HEADER_LEN];
old[..4].copy_from_slice(&1u32.to_be_bytes());
assert!(frame_length(old).is_err());
let mut foreign = header;
foreign[7] = b'1';
assert!(frame_length(foreign).is_err());
}
#[test]
fn protocol_does_not_accept_a_shell_operation() {
@@ -1417,6 +1490,22 @@ mod tests {
assert_eq!(diagnostic(&caller).code, "UNCLASSIFIED_IO_OR_CODEC");
let remote = remote_denial(Stage::ClientReplyBinding, "caller-payload-private-marker");
assert_eq!(diagnostic(&remote).code, "UNCLASSIFIED_REMOTE_DENIAL");
let challenge = Uuid::from_u128(1);
let raw = br#"{"a":1,"b":2}"#;
let receipt = drain_receipt(challenge, raw);
assert!(verify_drain_receipt(&receipt, challenge, raw).is_ok());
// Same JSON meaning, different exact bytes must not drain this reply.
assert!(verify_drain_receipt(&receipt, challenge, br#"{"b":2,"a":1}"#).is_err());
assert!(verify_drain_receipt(&receipt, Uuid::from_u128(2), raw).is_err());
for offset in [0, 7, 8, 23, 24, DRAIN_RECEIPT_LEN - 1] {
let mut changed = receipt;
changed[offset] ^= 1;
let error = verify_drain_receipt(&changed, challenge, raw)
.unwrap_err()
.context(Stage::ServerDrainReceipt);
assert_eq!(diagnostic(&error).code, "HELPER_DRAIN_RECEIPT");
assert_eq!(diagnostic(&error).stage, "server_drain_receipt");
}
}
#[test]
fn reconfigured_service_cannot_adopt_an_old_running_identity() {
+1 -1
View File
@@ -1179,7 +1179,7 @@ unsafe extern "system" fn service_main(_: u32, _: *mut *mut u16) {
match server.receive() {
Ok(Some(mut incoming)) => {
let reply = helper.handle(&incoming.call, &mut incoming.peer);
if let Err(error) = server.reply(&reply) {
if let Err(error) = server.reply(&reply, &mut incoming.peer) {
if let Some(sync) = &mut helper.sync {
sync.close();
}