//! Stable updater channel, separate from the LocalService agent channel. //! Mutually pinned service identity is checked before decoding a bounded call. //! An Activate is never retried by the transport. A response is not readiness. use crate::helper_ipc::{self as ipc, PeerPin, PeerProof}; use anyhow::{Context, Result, ensure}; use rmm_agent_core::auth::Binding; use rmm_domain::{ agent_update::{ParticipantIdentity, ParticipantRole}, jobs::hash, }; use serde::{Deserialize, Serialize}; use std::{ mem::size_of, os::windows::io::{AsRawHandle, OwnedHandle}, path::Path, ptr, time::{Duration, Instant}, }; use uuid::Uuid; use windows_sys::Win32::{ Foundation::*, Security::*, Storage::FileSystem::*, System::{Pipes::*, Threading::*}, }; pub const SERVICE: &str = "RmmDiscoveryUpdater"; pub const BINARY: &str = r"C:\Program Files\RustDiscovery\rmm-updater-windows.exe"; pub const PIPE: &str = r"\\.\pipe\RustDiscovery-Updater-v1"; const LIMIT: usize = 32768; #[derive(Clone, Debug, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Pin { pub schema_version: u32, pub binding: Binding, pub policy_sha256: String, pub helper: PeerPin, pub updater: PeerPin, } impl Pin { pub fn validate(&self) -> Result<()> { ensure!( self.schema_version == 1 && ipc::digest(&self.policy_sha256), "UPDATE_IPC_PIN" ); self.helper.validate(true)?; ensure!( self.updater.service_name == SERVICE && self.updater.service_sid == ipc::service_sid(SERVICE)? && self.updater.user_sid == "S-1-5-18" && self.updater.binary == Path::new(BINARY) && ipc::digest(&self.updater.binary_sha256), "UPDATE_IPC_UPDATER_PIN" ); ensure!( !self.binding.agent_id.is_nil() && !self.binding.asset_id.is_nil() && !self.binding.tenant_id.is_nil() && self.binding.enrollment_generation > 0 && self.binding.assignment_version > 0, "UPDATE_IPC_BINDING" ); Ok(()) } } #[derive(Clone, Debug, Serialize, Deserialize)] #[serde(tag = "method", rename_all = "snake_case", deny_unknown_fields)] pub enum Request { Describe {}, Activate { grant_id: Uuid, owner_nonce: Uuid, handoff_sha256: String, }, Read { grant_id: Uuid, owner_nonce: Uuid, handoff_sha256: String, }, Health { grant_id: Uuid, owner_nonce: Uuid, handoff_sha256: String, payload_base64url: String, signature_base64url: String, }, } impl Request { pub fn validate(&self) -> Result<()> { match self { Self::Describe {} => {} Self::Activate { grant_id, owner_nonce, handoff_sha256, } | Self::Read { grant_id, owner_nonce, handoff_sha256, } | Self::Health { grant_id, owner_nonce, handoff_sha256, .. } => { ensure!( !grant_id.is_nil() && !owner_nonce.is_nil() && ipc::digest(handoff_sha256), "UPDATE_IPC_ORIGINAL_BINDING" ); if let Self::Health { payload_base64url, signature_base64url, .. } = self { ensure!( !payload_base64url.is_empty() && payload_base64url.len() <= 21846 && signature_base64url.len() == 86 && payload_base64url .bytes() .chain(signature_base64url.bytes()) .all(|b| b.is_ascii_alphanumeric() || b"-_".contains(&b)), "UPDATE_IPC_HEALTH_LIMIT" ); } } } Ok(()) } } #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum State { Described, Inflight, OutcomePersisted, Unknown, NotConfigured, } #[derive(Clone, Debug, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Response { pub schema_version: u32, pub state: State, pub ready: bool, pub updater: ParticipantIdentity, pub head_sha256: Option, } impl Response { fn validate(&self) -> Result<()> { ensure!( self.schema_version == 1 && !self.ready && self.updater.validate() && self.updater.role == ParticipantRole::WindowsUpdater && self.head_sha256.as_ref().is_none_or(|v| ipc::digest(v)), "UPDATE_IPC_RESPONSE" ); Ok(()) } } #[derive(Serialize, Deserialize)] #[serde(deny_unknown_fields)] struct Call { schema_version: u32, challenge: Uuid, binding_sha256: String, policy_sha256: String, request: Request, } #[derive(Serialize, Deserialize)] #[serde(deny_unknown_fields)] struct Reply { schema_version: u32, challenge: Uuid, binding_sha256: String, policy_sha256: String, response: Response, } /// The instance digest covers the pinned SCM command and held live process, /// including image file identity and service SID, rather than PID alone. pub fn participant(peer: &PeerProof, role: ParticipantRole) -> Result { ensure!( matches!( role, ParticipantRole::WindowsHelper | ParticipantRole::WindowsUpdater ), "UPDATE_IPC_PARTICIPANT_ROLE" ); let p = peer.identity(); let expected = if role == ParticipantRole::WindowsHelper { ipc::HELPER_SERVICE } else { SERVICE }; ensure!( p.user_sid == "S-1-5-18" && p.service_sid == ipc::service_sid(expected)?, "UPDATE_IPC_PARTICIPANT_SID" ); let value = ParticipantIdentity { role, pid: p.pid, birth: p.creation_ticks, image_sha256: p.image_sha256.clone(), security_principal: p.user_sid.clone(), service_instance_sha256: hash(&serde_json::to_vec(p)?), }; ensure!(value.validate(), "UPDATE_IPC_PARTICIPANT"); Ok(value) } pub fn observe(pin: &PeerPin, role: ParticipantRole) -> Result<(PeerProof, ParticipantIdentity)> { let mut proof = PeerProof::for_service(pin, ipc::service_status(pin)?)?; proof.check()?; let value = participant(&proof, role)?; Ok((proof, value)) } /// Caller implements all original-ledger, retained-state, clock and one-pass /// checks. This transport has no default handler or automatic startup replay. pub trait Engine { fn handle(&mut self, peer: &ParticipantIdentity, request: Request) -> Result; } pub struct Server { pipe: OwnedHandle, pin: Pin, } impl Server { pub fn bind(pin: Pin) -> Result { pin.validate()?; ipc::require_self(&pin.updater)?; let descriptor = ipc::Descriptor::from(&format!( "O:SYG:SYD:P(D;;GA;;;NU)(A;;GA;;;SY)(A;;GA;;;BA)(A;;GA;;;{})(A;;0x{:08x};;;{})", pin.updater.service_sid, ipc::CLIENT_PIPE_RIGHTS, pin.helper.service_sid ))?; let sa = SECURITY_ATTRIBUTES { nLength: size_of::() as u32, lpSecurityDescriptor: descriptor.0, bInheritHandle: 0, }; let pipe = ipc::owned(unsafe { CreateNamedPipeW( ipc::wide(PIPE).as_ptr(), PIPE_ACCESS_DUPLEX | FILE_FLAG_OVERLAPPED | FILE_FLAG_FIRST_PIPE_INSTANCE, PIPE_TYPE_BYTE | PIPE_READMODE_BYTE | PIPE_WAIT | PIPE_REJECT_REMOTE_CLIENTS, 1, LIMIT as u32, LIMIT as u32, 1000, &sa, ) })?; Ok(Self { pipe, pin }) } pub fn serve_one(&self, engine: &mut impl Engine) -> Result { let result = self.serve_connected(engine); unsafe { DisconnectNamedPipe(self.pipe.as_raw_handle()); } result } fn serve_connected(&self, engine: &mut impl Engine) -> Result { ipc::require_self(&self.pin.updater)?; let pipe = self.pipe.as_raw_handle(); let mut event = ipc::IoEvent::new()?; if unsafe { ConnectNamedPipe(pipe, &mut event.overlapped) } == 0 { let error = unsafe { GetLastError() }; if error == ERROR_IO_PENDING { if let Err(e) = event.wait(pipe, Instant::now() + Duration::from_millis(250)) { if ipc::diagnostic(&e).code == "HELPER_PIPE_TIMEOUT" { return Ok(false); } return Err(e); } } else { ensure!(error == ERROR_PIPE_CONNECTED, "UPDATE_IPC_CONNECT"); } } let deadline = Instant::now() + Duration::from_secs(5); let len = ipc::length(pipe, deadline)?; ensure!(len <= LIMIT, "UPDATE_IPC_FRAME_LIMIT"); let mut peer = PeerProof::capture(pipe, &self.pin.helper, true)?; ensure!( unsafe { ImpersonateNamedPipeClient(pipe) } != 0, "UPDATE_IPC_IMPERSONATE" ); let auth = (|| -> Result<()> { let mut token = ptr::null_mut(); ensure!( unsafe { OpenThreadToken(GetCurrentThread(), TOKEN_QUERY, 1, &mut token) } != 0, "UPDATE_IPC_THREAD_TOKEN" ); let token = ipc::owned(token)?; ipc::verify_token( token.as_raw_handle(), &self.pin.helper.user_sid, &self.pin.helper.service_sid, ) })(); if unsafe { RevertToSelf() } == 0 { std::process::abort(); } auth?; ipc::require_self(&self.pin.updater)?; let call: Call = ipc::body(pipe, len, deadline)?; ensure!( call.schema_version == 1 && !call.challenge.is_nil() && call.binding_sha256 == ipc::binding_hash(&self.pin.binding)? && call.policy_sha256 == self.pin.policy_sha256, "UPDATE_IPC_CALL_BINDING" ); call.request.validate()?; peer.check()?; let response = engine.handle( &participant(&peer, ParticipantRole::WindowsHelper)?, call.request, )?; response.validate()?; let (_own, own) = observe(&self.pin.updater, ParticipantRole::WindowsUpdater)?; ensure!(response.updater == own, "UPDATE_IPC_SELF_RESPONSE"); let reply = Reply { schema_version: 1, challenge: call.challenge, binding_sha256: call.binding_sha256, policy_sha256: call.policy_sha256, response, }; let mut bytes = ipc::encode(&reply)?; ensure!(bytes.len() <= LIMIT, "UPDATE_IPC_REPLY_LIMIT"); peer.check()?; let deadline = Instant::now() + Duration::from_secs(5); ipc::send_bytes(pipe, &mut bytes, deadline)?; let mut receipt = [0; ipc::DRAIN_RECEIPT_LEN]; ipc::transfer(pipe, &mut receipt, false, deadline)?; ipc::verify_drain_receipt(&receipt, reply.challenge, &bytes)?; peer.check()?; Ok(true) } } /// Bounded blocking lane only. Every failure propagates; no Activate retry. pub fn exchange(pin: &Pin, request: &Request, timeout: Duration) -> Result { pin.validate()?; request.validate()?; ipc::require_self(&pin.helper)?; ensure!( (Duration::from_secs(1)..=Duration::from_secs(30)).contains(&timeout), "UPDATE_IPC_TIMEOUT" ); let deadline = Instant::now() + timeout; let pipe = ipc::owned(unsafe { CreateFileW( ipc::wide(PIPE).as_ptr(), ipc::CLIENT_PIPE_RIGHTS, 0, ptr::null(), OPEN_EXISTING, FILE_FLAG_OVERLAPPED | SECURITY_SQOS_PRESENT | SECURITY_IDENTIFICATION, ptr::null_mut(), ) }) .context("UPDATE_IPC_UNAVAILABLE")?; let mut peer = PeerProof::capture(pipe.as_raw_handle(), &pin.updater, false)?; let expected = participant(&peer, ParticipantRole::WindowsUpdater)?; let call = Call { schema_version: 1, challenge: Uuid::new_v4(), binding_sha256: ipc::binding_hash(&pin.binding)?, policy_sha256: pin.policy_sha256.clone(), request: request.clone(), }; let raw = ipc::encode(&call)?; ensure!(raw.len() <= LIMIT, "UPDATE_IPC_FRAME_LIMIT"); ipc::send(pipe.as_raw_handle(), &call, deadline)?; let len = ipc::length(pipe.as_raw_handle(), deadline)?; ensure!(len <= LIMIT, "UPDATE_IPC_FRAME_LIMIT"); let bytes = ipc::body_bytes(pipe.as_raw_handle(), len, deadline)?; let reply: Reply = serde_json::from_slice(&bytes)?; peer.check()?; ensure!( reply.schema_version == 1 && reply.challenge == call.challenge && reply.binding_sha256 == call.binding_sha256 && reply.policy_sha256 == call.policy_sha256 && reply.response.updater == expected, "UPDATE_IPC_REPLY_BINDING" ); reply.response.validate()?; let mut receipt = ipc::drain_receipt(call.challenge, &bytes); ipc::transfer(pipe.as_raw_handle(), &mut receipt, true, deadline)?; Ok(reply.response) } #[cfg(test)] mod tests { use super::*; #[test] fn request_cannot_select_a_path_command_service_or_weak_original_binding() { for raw in [ r#"{"method":"activate","grant_id":"00000000-0000-0000-0000-000000000000","owner_nonce":"00000000-0000-0000-0000-000000000000","handoff_sha256":"00"}"#, r#"{"method":"describe","path":"C:\\Windows\\cmd.exe"}"#, r#"{"method":"prepare"}"#, ] { assert!( serde_json::from_str::(raw) .and_then(|r| r.validate().map_err(serde::de::Error::custom)) .is_err() ); } assert!( serde_json::from_str::(r#"{"method":"describe"}"#) .unwrap() .validate() .is_ok() ); } }