1use goblin::mach::Mach;
15use goblin::mach::load_command::CommandVariant;
16use kh_runtime::GuestMemory;
17
18use crate::bind::{self, BindSite};
19use crate::error::LoadError;
20use crate::image::MachOImage;
21use crate::parse::thin_arm64_bytes;
22use crate::session::{LoadSession, ProcessImage};
23
24const HEADER_SIZE: usize = 28;
26
27pub const DYLD_CHAINED_PTR_START_NONE: u16 = 0xFFFF;
29pub const DYLD_CHAINED_PTR_START_MULTI: u16 = 0x8000;
31
32pub const DYLD_CHAINED_PTR_64: u16 = 2;
34pub const DYLD_CHAINED_PTR_64_OFFSET: u16 = 6;
36
37pub const DYLD_CHAINED_IMPORT: u32 = 1;
39pub const DYLD_CHAINED_IMPORT_ADDEND: u32 = 2;
41pub const DYLD_CHAINED_IMPORT_ADDEND64: u32 = 3;
43
44#[derive(Debug, Clone, PartialEq, Eq)]
46pub struct ChainedImport {
47 pub lib_ordinal: i16,
49 pub weak: bool,
51 pub name: String,
53 pub addend: i64,
55}
56
57#[derive(Debug, Clone, PartialEq, Eq)]
59pub enum ChainDecode {
60 Rebase {
62 value: u64,
64 },
65 Bind {
67 import_ordinal: usize,
69 ptr_addend: i64,
71 },
72}
73
74#[must_use]
76pub fn image_has_chained_fixups(image: &MachOImage) -> bool {
77 image
78 .load_commands
79 .iter()
80 .any(|lc| lc.name == "LC_DYLD_CHAINED_FIXUPS")
81}
82
83pub fn bytes_have_chained_fixups(bytes: &[u8]) -> Result<bool, LoadError> {
85 Ok(chained_linkedit_range(bytes)?.is_some())
86}
87
88pub fn apply_chained_fixups(
95 session: &mut LoadSession,
96 image_idx: usize,
97 bytes: &[u8],
98 cache: &bind::BindResolveCache,
99) -> Result<usize, LoadError> {
100 let thin = thin_arm64_bytes(bytes)?;
102 let preferred_base = session
103 .images
104 .get(image_idx)
105 .map_or(0, ProcessImage::preferred_base);
106 let slide = session.images.get(image_idx).map_or(0, ProcessImage::slide);
107
108 let Some((dataoff, datasize)) = chained_linkedit_range(thin)? else {
109 return Ok(0);
110 };
111 let blob = thin
112 .get(dataoff..dataoff.saturating_add(datasize))
113 .ok_or_else(|| LoadError::Resolve("chained fixups blob OOB".into()))?;
114
115 let header = parse_header(blob)?;
116 let imports = parse_imports(blob, &header)?;
117
118 let pending = {
120 let memory = session
121 .images
122 .get(image_idx)
123 .and_then(|img| img.memory.as_ref())
124 .ok_or(LoadError::NotImplemented(
125 "memory missing for chained fixups",
126 ))?;
127 collect_pending(memory, blob, &header, preferred_base, slide)?
128 };
129
130 let mut writes: Vec<(u64, u64)> = Vec::with_capacity(pending.len());
131 for (slot_va, decoded) in pending {
132 let value = match decoded {
133 ChainDecode::Rebase { value } => value,
134 ChainDecode::Bind {
135 import_ordinal,
136 ptr_addend,
137 } => {
138 let import = imports.get(import_ordinal).ok_or_else(|| {
139 LoadError::Resolve(format!(
140 "chained bind ordinal {import_ordinal} out of range ({})",
141 imports.len()
142 ))
143 })?;
144 let site = BindSite {
145 name: import.name.clone(),
146 preferred_va: 0,
147 addend: import.addend.saturating_add(ptr_addend),
148 weak: import.weak,
149 bind_type: 1,
150 lib_ordinal: import.lib_ordinal,
151 is_lazy: false,
152 };
153 let resolved =
154 bind::resolve_bind_symbol(cache, session.images(), image_idx, &site)?;
155 if site.addend == 0 {
156 resolved
157 } else {
158 resolved.wrapping_add(site.addend.cast_unsigned())
159 }
160 }
161 };
162 tracing::debug!(slot = slot_va, value, "chained fixup");
163 writes.push((slot_va, value));
164 }
165
166 bind::write_pointer_slots(session, image_idx, &writes)?;
167 Ok(writes.len())
168}
169
170struct FixupsHeader {
175 starts_offset: u32,
176 imports_offset: u32,
177 symbols_offset: u32,
178 imports_count: u32,
179 imports_format: u32,
180 symbols_format: u32,
181}
182
183fn chained_linkedit_range(bytes: &[u8]) -> Result<Option<(usize, usize)>, LoadError> {
184 let thin = thin_arm64_bytes(bytes)?;
185 let macho = match Mach::parse(thin) {
186 Ok(Mach::Binary(m)) => m,
187 Ok(Mach::Fat(_)) => {
188 return Err(LoadError::NotMachO(
189 "nested fat image inside arm64 slice".into(),
190 ));
191 }
192 Err(err) => return Err(LoadError::NotMachO(err.to_string())),
193 };
194 for lc in &macho.load_commands {
195 if let CommandVariant::DyldChainedFixups(cmd) = &lc.command {
196 let off = usize::try_from(cmd.dataoff)
197 .map_err(|_| LoadError::Resolve("chained dataoff overflow".into()))?;
198 let size = usize::try_from(cmd.datasize)
199 .map_err(|_| LoadError::Resolve("chained datasize overflow".into()))?;
200 return Ok(Some((off, size)));
201 }
202 }
203 Ok(None)
204}
205
206fn parse_header(blob: &[u8]) -> Result<FixupsHeader, LoadError> {
207 if blob.len() < HEADER_SIZE {
208 return Err(LoadError::Resolve("chained fixups header truncated".into()));
209 }
210 let version = read_u32(blob, 0)?;
211 if version != 0 {
212 return Err(LoadError::Resolve(format!(
213 "unsupported chained fixups_version {version}"
214 )));
215 }
216 Ok(FixupsHeader {
217 starts_offset: read_u32(blob, 4)?,
218 imports_offset: read_u32(blob, 8)?,
219 symbols_offset: read_u32(blob, 12)?,
220 imports_count: read_u32(blob, 16)?,
221 imports_format: read_u32(blob, 20)?,
222 symbols_format: read_u32(blob, 24)?,
223 })
224}
225
226fn parse_imports(blob: &[u8], header: &FixupsHeader) -> Result<Vec<ChainedImport>, LoadError> {
227 if header.symbols_format != 0 {
228 return Err(LoadError::NotImplemented(
229 "zlib-compressed chained symbol strings",
230 ));
231 }
232 let count = usize::try_from(header.imports_count)
233 .map_err(|_| LoadError::Resolve("imports_count overflow".into()))?;
234 let imports_off = usize::try_from(header.imports_offset)
235 .map_err(|_| LoadError::Resolve("imports_offset overflow".into()))?;
236 let symbols_off = usize::try_from(header.symbols_offset)
237 .map_err(|_| LoadError::Resolve("symbols_offset overflow".into()))?;
238
239 let entry_size = match header.imports_format {
240 DYLD_CHAINED_IMPORT => 4_usize,
241 DYLD_CHAINED_IMPORT_ADDEND => 8,
242 DYLD_CHAINED_IMPORT_ADDEND64 => 16,
243 other => {
244 return Err(LoadError::Resolve(format!(
245 "unsupported chained imports_format {other}"
246 )));
247 }
248 };
249
250 let mut out = Vec::with_capacity(count);
251 for i in 0..count {
252 let base = imports_off
253 .checked_add(i.saturating_mul(entry_size))
254 .ok_or_else(|| LoadError::Resolve("import entry OOB".into()))?;
255 let (lib_ordinal, weak, name_offset, addend) = match header.imports_format {
256 DYLD_CHAINED_IMPORT => {
257 let raw = read_u32(blob, base)?;
258 let lib = raw & 0xff;
259 let weak = (raw >> 8) & 1 != 0;
260 let name_off = raw >> 9;
261 (sign_extend_lib_ordinal_8(lib), weak, name_off, 0_i64)
262 }
263 DYLD_CHAINED_IMPORT_ADDEND => {
264 let raw = read_u32(blob, base)?;
265 let add = read_i32(blob, base.saturating_add(4))?;
266 let lib = raw & 0xff;
267 let weak = (raw >> 8) & 1 != 0;
268 let name_off = raw >> 9;
269 (
270 sign_extend_lib_ordinal_8(lib),
271 weak,
272 name_off,
273 i64::from(add),
274 )
275 }
276 DYLD_CHAINED_IMPORT_ADDEND64 => {
277 let raw = read_u64(blob, base)?;
278 let add = read_u64(blob, base.saturating_add(8))?.cast_signed();
279 let lib = u32::try_from(raw & 0xffff).unwrap_or(0);
280 let weak = (raw >> 16) & 1 != 0;
281 let name_off = u32::try_from(raw >> 32).unwrap_or(0);
282 (sign_extend_lib_ordinal_16(lib), weak, name_off, add)
283 }
284 other => {
285 return Err(LoadError::Resolve(format!(
286 "unsupported chained imports_format {other}"
287 )));
288 }
289 };
290 let name = read_symbol_name(blob, symbols_off, name_offset)?;
291 out.push(ChainedImport {
292 lib_ordinal,
293 weak,
294 name,
295 addend,
296 });
297 }
298 Ok(out)
299}
300
301fn sign_extend_lib_ordinal_8(raw: u32) -> i16 {
302 let b = u8::try_from(raw & 0xff).unwrap_or(0);
303 if b > 0xF0 {
304 i16::from(b.cast_signed())
305 } else {
306 i16::from(b)
307 }
308}
309
310fn sign_extend_lib_ordinal_16(raw: u32) -> i16 {
311 let v = u16::try_from(raw & 0xffff).unwrap_or(0);
312 if v > 0xFFF0 {
313 v.cast_signed()
314 } else {
315 i16::try_from(v).unwrap_or(i16::MAX)
316 }
317}
318
319fn read_symbol_name(
320 blob: &[u8],
321 symbols_off: usize,
322 name_offset: u32,
323) -> Result<String, LoadError> {
324 let start = symbols_off
325 .checked_add(usize::try_from(name_offset).unwrap_or(usize::MAX))
326 .ok_or_else(|| LoadError::Resolve("symbol name offset overflow".into()))?;
327 let slice = blob
328 .get(start..)
329 .ok_or_else(|| LoadError::Resolve("symbol name OOB".into()))?;
330 let nul = slice
331 .iter()
332 .position(|&b| b == 0)
333 .ok_or_else(|| LoadError::Resolve("symbol name not NUL-terminated".into()))?;
334 let bytes = slice
335 .get(..nul)
336 .ok_or_else(|| LoadError::Resolve("symbol name slice OOB".into()))?;
337 std::str::from_utf8(bytes)
338 .map(str::to_owned)
339 .map_err(|err| LoadError::Resolve(format!("symbol utf8: {err}")))
340}
341
342fn collect_pending(
347 memory: &GuestMemory,
348 blob: &[u8],
349 header: &FixupsHeader,
350 preferred_base: u64,
351 slide: u64,
352) -> Result<Vec<(u64, ChainDecode)>, LoadError> {
353 let starts_off = usize::try_from(header.starts_offset)
354 .map_err(|_| LoadError::Resolve("starts_offset overflow".into()))?;
355 let starts = blob
356 .get(starts_off..)
357 .ok_or_else(|| LoadError::Resolve("starts_in_image OOB".into()))?;
358 if starts.len() < 4 {
359 return Err(LoadError::Resolve("starts_in_image truncated".into()));
360 }
361 let seg_count = usize::try_from(read_u32(starts, 0)?)
362 .map_err(|_| LoadError::Resolve("seg_count overflow".into()))?;
363 let table_end = 4_usize
364 .checked_add(
365 seg_count
366 .checked_mul(4)
367 .ok_or_else(|| LoadError::Resolve("seg table overflow".into()))?,
368 )
369 .ok_or_else(|| LoadError::Resolve("seg table overflow".into()))?;
370 if starts.len() < table_end {
371 return Err(LoadError::Resolve("seg_info_offset table truncated".into()));
372 }
373
374 let image_load = preferred_base.wrapping_add(slide);
375 let mut out = Vec::new();
376
377 for seg_i in 0..seg_count {
378 let off_pos = 4_usize.saturating_add(seg_i.saturating_mul(4));
379 let seg_info_rel = read_u32(starts, off_pos)?;
380 if seg_info_rel == 0 {
381 continue;
382 }
383 let seg_info_off = usize::try_from(seg_info_rel)
384 .map_err(|_| LoadError::Resolve("seg_info_offset overflow".into()))?;
385 let info = starts
386 .get(seg_info_off..)
387 .ok_or_else(|| LoadError::Resolve("seg starts OOB".into()))?;
388 walk_segment(memory, info, preferred_base, image_load, slide, &mut out)?;
389 }
390 Ok(out)
391}
392
393fn walk_segment(
394 memory: &GuestMemory,
395 info: &[u8],
396 preferred_base: u64,
397 image_load: u64,
398 slide: u64,
399 out: &mut Vec<(u64, ChainDecode)>,
400) -> Result<(), LoadError> {
401 if info.len() < 22 {
402 return Err(LoadError::Resolve(
403 "chained_starts_in_segment truncated".into(),
404 ));
405 }
406 let page_size = read_u16(info, 4)?;
407 let pointer_format = read_u16(info, 6)?;
408 let segment_offset = read_u64(info, 8)?;
409 let page_count = usize::from(read_u16(info, 20)?);
410 let stride = pointer_stride(pointer_format)?;
411 let need = 22_usize.saturating_add(page_count.saturating_mul(2));
412 if info.len() < need {
413 return Err(LoadError::Resolve(
414 "chained page_start array truncated".into(),
415 ));
416 }
417 if page_size == 0 {
418 return Err(LoadError::Resolve("chained page_size is 0".into()));
419 }
420
421 for page_i in 0..page_count {
422 let start = read_u16(info, 22_usize.saturating_add(page_i.saturating_mul(2)))?;
423 if start == DYLD_CHAINED_PTR_START_NONE {
424 continue;
425 }
426 if start & DYLD_CHAINED_PTR_START_MULTI != 0 {
427 return Err(LoadError::NotImplemented(
428 "chained multi-start pages (DYLD_CHAINED_PTR_START_MULTI)",
429 ));
430 }
431 let page_base = image_load.wrapping_add(segment_offset).wrapping_add(
432 u64::try_from(page_i)
433 .unwrap_or(0)
434 .wrapping_mul(u64::from(page_size)),
435 );
436
437 let mut offset_in_page = u64::from(start);
438 let mut hops = 0_u32;
439 loop {
440 if hops > 1_000_000 {
441 return Err(LoadError::Resolve("chained fixup cycle / too long".into()));
442 }
443 hops = hops.saturating_add(1);
444 if offset_in_page >= u64::from(page_size) {
445 return Err(LoadError::Resolve(format!(
446 "chained offset {offset_in_page:#x} past page_size {page_size:#x}"
447 )));
448 }
449 let slot_va = page_base.wrapping_add(offset_in_page);
450 let raw = memory.read_u64_le(slot_va).ok_or_else(|| {
451 LoadError::Resolve(format!("chained slot unreadable at {slot_va:#x}"))
452 })?;
453 let (next, decoded) = decode_ptr_64(raw, pointer_format, preferred_base, slide)?;
454 out.push((slot_va, decoded));
455 if next == 0 {
456 break;
457 }
458 offset_in_page = offset_in_page.wrapping_add(next.wrapping_mul(stride));
459 }
460 }
461 Ok(())
462}
463
464fn pointer_stride(format: u16) -> Result<u64, LoadError> {
465 match format {
466 DYLD_CHAINED_PTR_64 | DYLD_CHAINED_PTR_64_OFFSET => Ok(4),
467 1 => Err(LoadError::NotImplemented("DYLD_CHAINED_PTR_ARM64E")),
468 7 => Err(LoadError::NotImplemented("DYLD_CHAINED_PTR_ARM64E_KERNEL")),
469 9 => Err(LoadError::NotImplemented(
470 "DYLD_CHAINED_PTR_ARM64E_USERLAND",
471 )),
472 12 => Err(LoadError::NotImplemented(
473 "DYLD_CHAINED_PTR_ARM64E_USERLAND24",
474 )),
475 _ => Err(LoadError::NotImplemented(
476 "unsupported chained pointer_format",
477 )),
478 }
479}
480
481pub fn decode_ptr_64(
485 raw: u64,
486 format: u16,
487 preferred_base: u64,
488 slide: u64,
489) -> Result<(u64, ChainDecode), LoadError> {
490 let bind = (raw >> 63) & 1 != 0;
491 let next = (raw >> 51) & 0xfff;
492 if bind {
493 let ordinal = raw & 0xff_ffff;
494 let addend = (raw >> 24) & 0xff;
495 Ok((
496 next,
497 ChainDecode::Bind {
498 import_ordinal: usize::try_from(ordinal).unwrap_or(usize::MAX),
499 ptr_addend: i64::try_from(addend).unwrap_or(0),
500 },
501 ))
502 } else {
503 let target = raw & 0xf_ffff_ffff;
504 let high8 = (raw >> 36) & 0xff;
505 let runtime = (high8 << 56) | target;
506 let value = match format {
507 DYLD_CHAINED_PTR_64 => runtime.wrapping_add(slide),
508 DYLD_CHAINED_PTR_64_OFFSET => preferred_base.wrapping_add(slide).wrapping_add(runtime),
509 _ => {
510 return Err(LoadError::NotImplemented(
511 "decode_ptr_64: unexpected format",
512 ));
513 }
514 };
515 Ok((next, ChainDecode::Rebase { value }))
516 }
517}
518
519#[must_use]
525pub fn encode_ptr_64_bind(import_ordinal: u32, addend: u8, next: u16) -> u64 {
526 let ord = u64::from(import_ordinal) & 0xff_ffff;
527 let add = u64::from(addend);
528 let nxt = u64::from(next) & 0xfff;
529 ord | (add << 24) | (nxt << 51) | (1_u64 << 63)
530}
531
532#[must_use]
534pub fn encode_ptr_64_rebase(target_or_offset: u64, next: u16) -> u64 {
535 let target = target_or_offset & 0xf_ffff_ffff;
536 let high8 = (target_or_offset >> 56) & 0xff;
537 let nxt = u64::from(next) & 0xfff;
538 target | (high8 << 36) | (nxt << 51)
539}
540
541#[must_use]
545#[allow(clippy::too_many_arguments)]
546pub fn encode_chained_fixups_blob(
547 seg_count: u32,
548 data_seg_index: u32,
549 segment_offset: u64,
550 page_size: u16,
551 page_start: u16,
552 pointer_format: u16,
553 import_lib_ordinal: u8,
554 symbol: &str,
555) -> Vec<u8> {
556 let mut starts = Vec::new();
557 starts.extend_from_slice(&seg_count.to_le_bytes());
558 let table_start = starts.len();
559 for _ in 0..seg_count {
560 starts.extend_from_slice(&0_u32.to_le_bytes());
561 }
562
563 let info_rel = u32::try_from(starts.len()).unwrap_or(0);
564 let page_count: u16 = 1;
565 let info_size: u32 = 24; starts.extend_from_slice(&info_size.to_le_bytes());
567 starts.extend_from_slice(&page_size.to_le_bytes());
568 starts.extend_from_slice(&pointer_format.to_le_bytes());
569 starts.extend_from_slice(&segment_offset.to_le_bytes());
570 starts.extend_from_slice(&0_u32.to_le_bytes());
571 starts.extend_from_slice(&page_count.to_le_bytes());
572 starts.extend_from_slice(&page_start.to_le_bytes());
573
574 let idx = usize::try_from(data_seg_index).unwrap_or(0);
575 let patch_at = table_start.saturating_add(idx.saturating_mul(4));
576 if let Some(slot) = starts.get_mut(patch_at..patch_at.saturating_add(4)) {
577 slot.copy_from_slice(&info_rel.to_le_bytes());
578 }
579
580 let starts_offset = HEADER_SIZE;
581 let imports_offset = starts_offset.saturating_add(starts.len());
582 let name_offset = 0_u32;
583 let import_raw: u32 = u32::from(import_lib_ordinal) | (name_offset << 9);
584 let symbols_offset = imports_offset.saturating_add(4);
585 let mut symbols = symbol.as_bytes().to_vec();
586 symbols.push(0);
587
588 let mut blob = Vec::with_capacity(symbols_offset.saturating_add(symbols.len()));
589 blob.extend_from_slice(&0_u32.to_le_bytes());
590 blob.extend_from_slice(&u32::try_from(starts_offset).unwrap_or(0).to_le_bytes());
591 blob.extend_from_slice(&u32::try_from(imports_offset).unwrap_or(0).to_le_bytes());
592 blob.extend_from_slice(&u32::try_from(symbols_offset).unwrap_or(0).to_le_bytes());
593 blob.extend_from_slice(&1_u32.to_le_bytes());
594 blob.extend_from_slice(&DYLD_CHAINED_IMPORT.to_le_bytes());
595 blob.extend_from_slice(&0_u32.to_le_bytes());
596 debug_assert_eq!(blob.len(), HEADER_SIZE);
597 blob.extend_from_slice(&starts);
598 blob.extend_from_slice(&import_raw.to_le_bytes());
599 blob.extend_from_slice(&symbols);
600 blob
601}
602
603fn read_u16(data: &[u8], off: usize) -> Result<u16, LoadError> {
608 let b = data
609 .get(off..off.saturating_add(2))
610 .ok_or_else(|| LoadError::Resolve(format!("u16 OOB at {off}")))?;
611 let mut arr = [0_u8; 2];
612 arr.copy_from_slice(b);
613 Ok(u16::from_le_bytes(arr))
614}
615
616fn read_u32(data: &[u8], off: usize) -> Result<u32, LoadError> {
617 let b = data
618 .get(off..off.saturating_add(4))
619 .ok_or_else(|| LoadError::Resolve(format!("u32 OOB at {off}")))?;
620 let mut arr = [0_u8; 4];
621 arr.copy_from_slice(b);
622 Ok(u32::from_le_bytes(arr))
623}
624
625fn read_i32(data: &[u8], off: usize) -> Result<i32, LoadError> {
626 Ok(read_u32(data, off)?.cast_signed())
627}
628
629fn read_u64(data: &[u8], off: usize) -> Result<u64, LoadError> {
630 let b = data
631 .get(off..off.saturating_add(8))
632 .ok_or_else(|| LoadError::Resolve(format!("u64 OOB at {off}")))?;
633 let mut arr = [0_u8; 8];
634 arr.copy_from_slice(b);
635 Ok(u64::from_le_bytes(arr))
636}
637
638#[cfg(test)]
643#[allow(clippy::expect_used, clippy::unwrap_used)]
644mod tests {
645 use super::*;
646
647 #[test]
648 fn decode_bind_and_rebase_ptr64() {
649 let raw = encode_ptr_64_bind(0, 0, 0);
650 let (next, dec) = decode_ptr_64(raw, DYLD_CHAINED_PTR_64, 0x1000_0000, 0).unwrap();
651 assert_eq!(next, 0);
652 assert_eq!(
653 dec,
654 ChainDecode::Bind {
655 import_ordinal: 0,
656 ptr_addend: 0
657 }
658 );
659
660 let slide = 0x1000_u64;
661 let target = 0x1000_4000_u64;
662 let raw = encode_ptr_64_rebase(target, 2);
663 let (next, dec) = decode_ptr_64(raw, DYLD_CHAINED_PTR_64, 0x1000_0000, slide).unwrap();
664 assert_eq!(next, 2);
665 assert_eq!(
666 dec,
667 ChainDecode::Rebase {
668 value: target + slide
669 }
670 );
671
672 let raw = encode_ptr_64_rebase(0x4000, 0);
673 let (_, dec) = decode_ptr_64(raw, DYLD_CHAINED_PTR_64_OFFSET, 0x1000_0000, slide).unwrap();
674 assert_eq!(
675 dec,
676 ChainDecode::Rebase {
677 value: 0x1000_0000 + slide + 0x4000
678 }
679 );
680 }
681
682 #[test]
683 fn encode_blob_parses_one_import() {
684 let blob =
685 encode_chained_fixups_blob(3, 2, 0x4000, 0x4000, 0, DYLD_CHAINED_PTR_64, 1, "_kh_add");
686 let header = parse_header(&blob).unwrap();
687 let imports = parse_imports(&blob, &header).unwrap();
688 assert_eq!(imports.len(), 1);
689 let imp = imports.first().expect("one import");
690 assert_eq!(imp.name, "_kh_add");
691 assert_eq!(imp.lib_ordinal, 1);
692 assert!(!imp.weak);
693 }
694}