Skip to main content

kh_loader/
chained.rs

1//! Dyld chained fixups (`LC_DYLD_CHAINED_FIXUPS`).
2//!
3//! Modern Mach-O arm64 images encode rebases and binds as compressed pointer
4//! chains in DATA. Applying chains replaces classic section-array rebase and
5//! classic bind opcodes for those slots.
6//!
7//! Phase 11 supports userspace formats:
8//! - [`DYLD_CHAINED_PTR_64`] — rebase target is preferred VA
9//! - [`DYLD_CHAINED_PTR_64_OFFSET`] — rebase target is offset from preferred base
10//!
11//! Import tables: `DYLD_CHAINED_IMPORT`, `IMPORT_ADDEND`, `IMPORT_ADDEND64`.
12//! Arm64e authenticated formats and multi-start pages are rejected clearly.
13
14use 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
24/// `dyld_chained_fixups_header` size in bytes.
25const HEADER_SIZE: usize = 28;
26
27/// Page has no fixups.
28pub const DYLD_CHAINED_PTR_START_NONE: u16 = 0xFFFF;
29/// Page uses multiple starts (not implemented in Phase 11).
30pub const DYLD_CHAINED_PTR_START_MULTI: u16 = 0x8000;
31
32/// Pointer format: 64-bit, target is preferred VA (pre-slide).
33pub const DYLD_CHAINED_PTR_64: u16 = 2;
34/// Pointer format: 64-bit, target is offset from preferred image base.
35pub const DYLD_CHAINED_PTR_64_OFFSET: u16 = 6;
36
37/// Imports without addend (4 bytes each).
38pub const DYLD_CHAINED_IMPORT: u32 = 1;
39/// Imports with 32-bit addend (8 bytes each).
40pub const DYLD_CHAINED_IMPORT_ADDEND: u32 = 2;
41/// Imports with 64-bit addend (16 bytes each).
42pub const DYLD_CHAINED_IMPORT_ADDEND64: u32 = 3;
43
44/// One import from the chained imports table.
45#[derive(Debug, Clone, PartialEq, Eq)]
46pub struct ChainedImport {
47    /// Library ordinal (0 self, −1 main, −2 flat, or 1-based dylib index).
48    pub lib_ordinal: i16,
49    /// Weak import → resolve to 0 when missing.
50    pub weak: bool,
51    /// Symbol name.
52    pub name: String,
53    /// Addend from the import table (before per-pointer addend).
54    pub addend: i64,
55}
56
57/// Result of decoding one chain pointer word.
58#[derive(Debug, Clone, PartialEq, Eq)]
59pub enum ChainDecode {
60    /// Absolute pointer after slide.
61    Rebase {
62        /// Final absolute VA.
63        value: u64,
64    },
65    /// Import table bind.
66    Bind {
67        /// Index into imports table.
68        import_ordinal: usize,
69        /// 0..255 addend from the pointer word (`PTR_64`).
70        ptr_addend: i64,
71    },
72}
73
74/// True when the parsed image lists `LC_DYLD_CHAINED_FIXUPS`.
75#[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
83/// True when file bytes contain `LC_DYLD_CHAINED_FIXUPS`.
84pub fn bytes_have_chained_fixups(bytes: &[u8]) -> Result<bool, LoadError> {
85    Ok(chained_linkedit_range(bytes)?.is_some())
86}
87
88/// Apply chained fixups for one mapped image (rebase + bind into guest memory).
89///
90/// Returns the number of pointer slots rewritten.
91pub fn apply_chained_fixups(
92    session: &mut LoadSession,
93    image_idx: usize,
94    bytes: &[u8],
95) -> Result<usize, LoadError> {
96    // Offsets in LC_DYLD_CHAINED_FIXUPS are thin-relative.
97    let thin = thin_arm64_bytes(bytes)?;
98    let preferred_base = session
99        .images
100        .get(image_idx)
101        .map_or(0, ProcessImage::preferred_base);
102    let slide = session.images.get(image_idx).map_or(0, ProcessImage::slide);
103
104    let Some((dataoff, datasize)) = chained_linkedit_range(thin)? else {
105        return Ok(0);
106    };
107    let blob = thin
108        .get(dataoff..dataoff.saturating_add(datasize))
109        .ok_or_else(|| LoadError::Resolve("chained fixups blob OOB".into()))?;
110
111    let header = parse_header(blob)?;
112    let imports = parse_imports(blob, &header)?;
113
114    // Collect (slot, kind) while we have immutable guest memory.
115    let pending = {
116        let memory = session
117            .images
118            .get(image_idx)
119            .and_then(|img| img.memory.as_ref())
120            .ok_or(LoadError::NotImplemented(
121                "memory missing for chained fixups",
122            ))?;
123        collect_pending(memory, blob, &header, preferred_base, slide)?
124    };
125
126    let mut writes: Vec<(u64, u64)> = Vec::with_capacity(pending.len());
127    for (slot_va, decoded) in pending {
128        let value = match decoded {
129            ChainDecode::Rebase { value } => value,
130            ChainDecode::Bind {
131                import_ordinal,
132                ptr_addend,
133            } => {
134                let import = imports.get(import_ordinal).ok_or_else(|| {
135                    LoadError::Resolve(format!(
136                        "chained bind ordinal {import_ordinal} out of range ({})",
137                        imports.len()
138                    ))
139                })?;
140                let site = BindSite {
141                    name: import.name.clone(),
142                    preferred_va: 0,
143                    addend: import.addend.saturating_add(ptr_addend),
144                    weak: import.weak,
145                    bind_type: 1,
146                    lib_ordinal: import.lib_ordinal,
147                    is_lazy: false,
148                };
149                let resolved = bind::resolve_bind_symbol(session.images(), image_idx, &site)?;
150                if site.addend == 0 {
151                    resolved
152                } else {
153                    resolved.wrapping_add(site.addend.cast_unsigned())
154                }
155            }
156        };
157        tracing::debug!(slot = slot_va, value, "chained fixup");
158        writes.push((slot_va, value));
159    }
160
161    bind::write_pointer_slots(session, image_idx, &writes)?;
162    Ok(writes.len())
163}
164
165// ---------------------------------------------------------------------------
166// Parsing
167// ---------------------------------------------------------------------------
168
169struct FixupsHeader {
170    starts_offset: u32,
171    imports_offset: u32,
172    symbols_offset: u32,
173    imports_count: u32,
174    imports_format: u32,
175    symbols_format: u32,
176}
177
178fn chained_linkedit_range(bytes: &[u8]) -> Result<Option<(usize, usize)>, LoadError> {
179    let thin = thin_arm64_bytes(bytes)?;
180    let macho = match Mach::parse(thin) {
181        Ok(Mach::Binary(m)) => m,
182        Ok(Mach::Fat(_)) => {
183            return Err(LoadError::NotMachO(
184                "nested fat image inside arm64 slice".into(),
185            ));
186        }
187        Err(err) => return Err(LoadError::NotMachO(err.to_string())),
188    };
189    for lc in &macho.load_commands {
190        if let CommandVariant::DyldChainedFixups(cmd) = &lc.command {
191            let off = usize::try_from(cmd.dataoff)
192                .map_err(|_| LoadError::Resolve("chained dataoff overflow".into()))?;
193            let size = usize::try_from(cmd.datasize)
194                .map_err(|_| LoadError::Resolve("chained datasize overflow".into()))?;
195            return Ok(Some((off, size)));
196        }
197    }
198    Ok(None)
199}
200
201fn parse_header(blob: &[u8]) -> Result<FixupsHeader, LoadError> {
202    if blob.len() < HEADER_SIZE {
203        return Err(LoadError::Resolve("chained fixups header truncated".into()));
204    }
205    let version = read_u32(blob, 0)?;
206    if version != 0 {
207        return Err(LoadError::Resolve(format!(
208            "unsupported chained fixups_version {version}"
209        )));
210    }
211    Ok(FixupsHeader {
212        starts_offset: read_u32(blob, 4)?,
213        imports_offset: read_u32(blob, 8)?,
214        symbols_offset: read_u32(blob, 12)?,
215        imports_count: read_u32(blob, 16)?,
216        imports_format: read_u32(blob, 20)?,
217        symbols_format: read_u32(blob, 24)?,
218    })
219}
220
221fn parse_imports(blob: &[u8], header: &FixupsHeader) -> Result<Vec<ChainedImport>, LoadError> {
222    if header.symbols_format != 0 {
223        return Err(LoadError::NotImplemented(
224            "zlib-compressed chained symbol strings",
225        ));
226    }
227    let count = usize::try_from(header.imports_count)
228        .map_err(|_| LoadError::Resolve("imports_count overflow".into()))?;
229    let imports_off = usize::try_from(header.imports_offset)
230        .map_err(|_| LoadError::Resolve("imports_offset overflow".into()))?;
231    let symbols_off = usize::try_from(header.symbols_offset)
232        .map_err(|_| LoadError::Resolve("symbols_offset overflow".into()))?;
233
234    let entry_size = match header.imports_format {
235        DYLD_CHAINED_IMPORT => 4_usize,
236        DYLD_CHAINED_IMPORT_ADDEND => 8,
237        DYLD_CHAINED_IMPORT_ADDEND64 => 16,
238        other => {
239            return Err(LoadError::Resolve(format!(
240                "unsupported chained imports_format {other}"
241            )));
242        }
243    };
244
245    let mut out = Vec::with_capacity(count);
246    for i in 0..count {
247        let base = imports_off
248            .checked_add(i.saturating_mul(entry_size))
249            .ok_or_else(|| LoadError::Resolve("import entry OOB".into()))?;
250        let (lib_ordinal, weak, name_offset, addend) = match header.imports_format {
251            DYLD_CHAINED_IMPORT => {
252                let raw = read_u32(blob, base)?;
253                let lib = raw & 0xff;
254                let weak = (raw >> 8) & 1 != 0;
255                let name_off = raw >> 9;
256                (sign_extend_lib_ordinal_8(lib), weak, name_off, 0_i64)
257            }
258            DYLD_CHAINED_IMPORT_ADDEND => {
259                let raw = read_u32(blob, base)?;
260                let add = read_i32(blob, base.saturating_add(4))?;
261                let lib = raw & 0xff;
262                let weak = (raw >> 8) & 1 != 0;
263                let name_off = raw >> 9;
264                (
265                    sign_extend_lib_ordinal_8(lib),
266                    weak,
267                    name_off,
268                    i64::from(add),
269                )
270            }
271            DYLD_CHAINED_IMPORT_ADDEND64 => {
272                let raw = read_u64(blob, base)?;
273                let add = read_u64(blob, base.saturating_add(8))?.cast_signed();
274                let lib = u32::try_from(raw & 0xffff).unwrap_or(0);
275                let weak = (raw >> 16) & 1 != 0;
276                let name_off = u32::try_from(raw >> 32).unwrap_or(0);
277                (sign_extend_lib_ordinal_16(lib), weak, name_off, add)
278            }
279            other => {
280                return Err(LoadError::Resolve(format!(
281                    "unsupported chained imports_format {other}"
282                )));
283            }
284        };
285        let name = read_symbol_name(blob, symbols_off, name_offset)?;
286        out.push(ChainedImport {
287            lib_ordinal,
288            weak,
289            name,
290            addend,
291        });
292    }
293    Ok(out)
294}
295
296fn sign_extend_lib_ordinal_8(raw: u32) -> i16 {
297    let b = u8::try_from(raw & 0xff).unwrap_or(0);
298    if b > 0xF0 {
299        i16::from(b.cast_signed())
300    } else {
301        i16::from(b)
302    }
303}
304
305fn sign_extend_lib_ordinal_16(raw: u32) -> i16 {
306    let v = u16::try_from(raw & 0xffff).unwrap_or(0);
307    if v > 0xFFF0 {
308        v.cast_signed()
309    } else {
310        i16::try_from(v).unwrap_or(i16::MAX)
311    }
312}
313
314fn read_symbol_name(
315    blob: &[u8],
316    symbols_off: usize,
317    name_offset: u32,
318) -> Result<String, LoadError> {
319    let start = symbols_off
320        .checked_add(usize::try_from(name_offset).unwrap_or(usize::MAX))
321        .ok_or_else(|| LoadError::Resolve("symbol name offset overflow".into()))?;
322    let slice = blob
323        .get(start..)
324        .ok_or_else(|| LoadError::Resolve("symbol name OOB".into()))?;
325    let nul = slice
326        .iter()
327        .position(|&b| b == 0)
328        .ok_or_else(|| LoadError::Resolve("symbol name not NUL-terminated".into()))?;
329    let bytes = slice
330        .get(..nul)
331        .ok_or_else(|| LoadError::Resolve("symbol name slice OOB".into()))?;
332    std::str::from_utf8(bytes)
333        .map(str::to_owned)
334        .map_err(|err| LoadError::Resolve(format!("symbol utf8: {err}")))
335}
336
337// ---------------------------------------------------------------------------
338// Chain walk
339// ---------------------------------------------------------------------------
340
341fn collect_pending(
342    memory: &GuestMemory,
343    blob: &[u8],
344    header: &FixupsHeader,
345    preferred_base: u64,
346    slide: u64,
347) -> Result<Vec<(u64, ChainDecode)>, LoadError> {
348    let starts_off = usize::try_from(header.starts_offset)
349        .map_err(|_| LoadError::Resolve("starts_offset overflow".into()))?;
350    let starts = blob
351        .get(starts_off..)
352        .ok_or_else(|| LoadError::Resolve("starts_in_image OOB".into()))?;
353    if starts.len() < 4 {
354        return Err(LoadError::Resolve("starts_in_image truncated".into()));
355    }
356    let seg_count = usize::try_from(read_u32(starts, 0)?)
357        .map_err(|_| LoadError::Resolve("seg_count overflow".into()))?;
358    let table_end = 4_usize
359        .checked_add(
360            seg_count
361                .checked_mul(4)
362                .ok_or_else(|| LoadError::Resolve("seg table overflow".into()))?,
363        )
364        .ok_or_else(|| LoadError::Resolve("seg table overflow".into()))?;
365    if starts.len() < table_end {
366        return Err(LoadError::Resolve("seg_info_offset table truncated".into()));
367    }
368
369    let image_load = preferred_base.wrapping_add(slide);
370    let mut out = Vec::new();
371
372    for seg_i in 0..seg_count {
373        let off_pos = 4_usize.saturating_add(seg_i.saturating_mul(4));
374        let seg_info_rel = read_u32(starts, off_pos)?;
375        if seg_info_rel == 0 {
376            continue;
377        }
378        let seg_info_off = usize::try_from(seg_info_rel)
379            .map_err(|_| LoadError::Resolve("seg_info_offset overflow".into()))?;
380        let info = starts
381            .get(seg_info_off..)
382            .ok_or_else(|| LoadError::Resolve("seg starts OOB".into()))?;
383        walk_segment(memory, info, preferred_base, image_load, slide, &mut out)?;
384    }
385    Ok(out)
386}
387
388fn walk_segment(
389    memory: &GuestMemory,
390    info: &[u8],
391    preferred_base: u64,
392    image_load: u64,
393    slide: u64,
394    out: &mut Vec<(u64, ChainDecode)>,
395) -> Result<(), LoadError> {
396    if info.len() < 22 {
397        return Err(LoadError::Resolve(
398            "chained_starts_in_segment truncated".into(),
399        ));
400    }
401    let page_size = read_u16(info, 4)?;
402    let pointer_format = read_u16(info, 6)?;
403    let segment_offset = read_u64(info, 8)?;
404    let page_count = usize::from(read_u16(info, 20)?);
405    let stride = pointer_stride(pointer_format)?;
406    let need = 22_usize.saturating_add(page_count.saturating_mul(2));
407    if info.len() < need {
408        return Err(LoadError::Resolve(
409            "chained page_start array truncated".into(),
410        ));
411    }
412    if page_size == 0 {
413        return Err(LoadError::Resolve("chained page_size is 0".into()));
414    }
415
416    for page_i in 0..page_count {
417        let start = read_u16(info, 22_usize.saturating_add(page_i.saturating_mul(2)))?;
418        if start == DYLD_CHAINED_PTR_START_NONE {
419            continue;
420        }
421        if start & DYLD_CHAINED_PTR_START_MULTI != 0 {
422            return Err(LoadError::NotImplemented(
423                "chained multi-start pages (DYLD_CHAINED_PTR_START_MULTI)",
424            ));
425        }
426        let page_base = image_load.wrapping_add(segment_offset).wrapping_add(
427            u64::try_from(page_i)
428                .unwrap_or(0)
429                .wrapping_mul(u64::from(page_size)),
430        );
431
432        let mut offset_in_page = u64::from(start);
433        let mut hops = 0_u32;
434        loop {
435            if hops > 1_000_000 {
436                return Err(LoadError::Resolve("chained fixup cycle / too long".into()));
437            }
438            hops = hops.saturating_add(1);
439            if offset_in_page >= u64::from(page_size) {
440                return Err(LoadError::Resolve(format!(
441                    "chained offset {offset_in_page:#x} past page_size {page_size:#x}"
442                )));
443            }
444            let slot_va = page_base.wrapping_add(offset_in_page);
445            let raw = memory.read_u64_le(slot_va).ok_or_else(|| {
446                LoadError::Resolve(format!("chained slot unreadable at {slot_va:#x}"))
447            })?;
448            let (next, decoded) = decode_ptr_64(raw, pointer_format, preferred_base, slide)?;
449            out.push((slot_va, decoded));
450            if next == 0 {
451                break;
452            }
453            offset_in_page = offset_in_page.wrapping_add(next.wrapping_mul(stride));
454        }
455    }
456    Ok(())
457}
458
459fn pointer_stride(format: u16) -> Result<u64, LoadError> {
460    match format {
461        DYLD_CHAINED_PTR_64 | DYLD_CHAINED_PTR_64_OFFSET => Ok(4),
462        1 => Err(LoadError::NotImplemented("DYLD_CHAINED_PTR_ARM64E")),
463        7 => Err(LoadError::NotImplemented("DYLD_CHAINED_PTR_ARM64E_KERNEL")),
464        9 => Err(LoadError::NotImplemented(
465            "DYLD_CHAINED_PTR_ARM64E_USERLAND",
466        )),
467        12 => Err(LoadError::NotImplemented(
468            "DYLD_CHAINED_PTR_ARM64E_USERLAND24",
469        )),
470        _ => Err(LoadError::NotImplemented(
471            "unsupported chained pointer_format",
472        )),
473    }
474}
475
476/// Decode a `DYLD_CHAINED_PTR_64` / `_64_OFFSET` raw word.
477///
478/// Returns `(next_count, decode)` where `next_count` is in stride units.
479pub fn decode_ptr_64(
480    raw: u64,
481    format: u16,
482    preferred_base: u64,
483    slide: u64,
484) -> Result<(u64, ChainDecode), LoadError> {
485    let bind = (raw >> 63) & 1 != 0;
486    let next = (raw >> 51) & 0xfff;
487    if bind {
488        let ordinal = raw & 0xff_ffff;
489        let addend = (raw >> 24) & 0xff;
490        Ok((
491            next,
492            ChainDecode::Bind {
493                import_ordinal: usize::try_from(ordinal).unwrap_or(usize::MAX),
494                ptr_addend: i64::try_from(addend).unwrap_or(0),
495            },
496        ))
497    } else {
498        let target = raw & 0xf_ffff_ffff;
499        let high8 = (raw >> 36) & 0xff;
500        let runtime = (high8 << 56) | target;
501        let value = match format {
502            DYLD_CHAINED_PTR_64 => runtime.wrapping_add(slide),
503            DYLD_CHAINED_PTR_64_OFFSET => preferred_base.wrapping_add(slide).wrapping_add(runtime),
504            _ => {
505                return Err(LoadError::NotImplemented(
506                    "decode_ptr_64: unexpected format",
507                ));
508            }
509        };
510        Ok((next, ChainDecode::Rebase { value }))
511    }
512}
513
514// ---------------------------------------------------------------------------
515// Encoders (fixtures / unit tests)
516// ---------------------------------------------------------------------------
517
518/// Encode a `DYLD_CHAINED_PTR_64` bind word.
519#[must_use]
520pub fn encode_ptr_64_bind(import_ordinal: u32, addend: u8, next: u16) -> u64 {
521    let ord = u64::from(import_ordinal) & 0xff_ffff;
522    let add = u64::from(addend);
523    let nxt = u64::from(next) & 0xfff;
524    ord | (add << 24) | (nxt << 51) | (1_u64 << 63)
525}
526
527/// Encode a `DYLD_CHAINED_PTR_64` / `_OFFSET` rebase word (same bit layout).
528#[must_use]
529pub fn encode_ptr_64_rebase(target_or_offset: u64, next: u16) -> u64 {
530    let target = target_or_offset & 0xf_ffff_ffff;
531    let high8 = (target_or_offset >> 56) & 0xff;
532    let nxt = u64::from(next) & 0xfff;
533    target | (high8 << 36) | (nxt << 51)
534}
535
536/// Build a minimal `LC_DYLD_CHAINED_FIXUPS` payload for fixtures.
537///
538/// One segment with starts (at `data_seg_index`), one page, one import.
539#[must_use]
540#[allow(clippy::too_many_arguments)]
541pub fn encode_chained_fixups_blob(
542    seg_count: u32,
543    data_seg_index: u32,
544    segment_offset: u64,
545    page_size: u16,
546    page_start: u16,
547    pointer_format: u16,
548    import_lib_ordinal: u8,
549    symbol: &str,
550) -> Vec<u8> {
551    let mut starts = Vec::new();
552    starts.extend_from_slice(&seg_count.to_le_bytes());
553    let table_start = starts.len();
554    for _ in 0..seg_count {
555        starts.extend_from_slice(&0_u32.to_le_bytes());
556    }
557
558    let info_rel = u32::try_from(starts.len()).unwrap_or(0);
559    let page_count: u16 = 1;
560    let info_size: u32 = 24; // 22 + 2
561    starts.extend_from_slice(&info_size.to_le_bytes());
562    starts.extend_from_slice(&page_size.to_le_bytes());
563    starts.extend_from_slice(&pointer_format.to_le_bytes());
564    starts.extend_from_slice(&segment_offset.to_le_bytes());
565    starts.extend_from_slice(&0_u32.to_le_bytes());
566    starts.extend_from_slice(&page_count.to_le_bytes());
567    starts.extend_from_slice(&page_start.to_le_bytes());
568
569    let idx = usize::try_from(data_seg_index).unwrap_or(0);
570    let patch_at = table_start.saturating_add(idx.saturating_mul(4));
571    if let Some(slot) = starts.get_mut(patch_at..patch_at.saturating_add(4)) {
572        slot.copy_from_slice(&info_rel.to_le_bytes());
573    }
574
575    let starts_offset = HEADER_SIZE;
576    let imports_offset = starts_offset.saturating_add(starts.len());
577    let name_offset = 0_u32;
578    let import_raw: u32 = u32::from(import_lib_ordinal) | (name_offset << 9);
579    let symbols_offset = imports_offset.saturating_add(4);
580    let mut symbols = symbol.as_bytes().to_vec();
581    symbols.push(0);
582
583    let mut blob = Vec::with_capacity(symbols_offset.saturating_add(symbols.len()));
584    blob.extend_from_slice(&0_u32.to_le_bytes());
585    blob.extend_from_slice(&u32::try_from(starts_offset).unwrap_or(0).to_le_bytes());
586    blob.extend_from_slice(&u32::try_from(imports_offset).unwrap_or(0).to_le_bytes());
587    blob.extend_from_slice(&u32::try_from(symbols_offset).unwrap_or(0).to_le_bytes());
588    blob.extend_from_slice(&1_u32.to_le_bytes());
589    blob.extend_from_slice(&DYLD_CHAINED_IMPORT.to_le_bytes());
590    blob.extend_from_slice(&0_u32.to_le_bytes());
591    debug_assert_eq!(blob.len(), HEADER_SIZE);
592    blob.extend_from_slice(&starts);
593    blob.extend_from_slice(&import_raw.to_le_bytes());
594    blob.extend_from_slice(&symbols);
595    blob
596}
597
598// ---------------------------------------------------------------------------
599// LE readers
600// ---------------------------------------------------------------------------
601
602fn read_u16(data: &[u8], off: usize) -> Result<u16, LoadError> {
603    let b = data
604        .get(off..off.saturating_add(2))
605        .ok_or_else(|| LoadError::Resolve(format!("u16 OOB at {off}")))?;
606    let mut arr = [0_u8; 2];
607    arr.copy_from_slice(b);
608    Ok(u16::from_le_bytes(arr))
609}
610
611fn read_u32(data: &[u8], off: usize) -> Result<u32, LoadError> {
612    let b = data
613        .get(off..off.saturating_add(4))
614        .ok_or_else(|| LoadError::Resolve(format!("u32 OOB at {off}")))?;
615    let mut arr = [0_u8; 4];
616    arr.copy_from_slice(b);
617    Ok(u32::from_le_bytes(arr))
618}
619
620fn read_i32(data: &[u8], off: usize) -> Result<i32, LoadError> {
621    Ok(read_u32(data, off)?.cast_signed())
622}
623
624fn read_u64(data: &[u8], off: usize) -> Result<u64, LoadError> {
625    let b = data
626        .get(off..off.saturating_add(8))
627        .ok_or_else(|| LoadError::Resolve(format!("u64 OOB at {off}")))?;
628    let mut arr = [0_u8; 8];
629    arr.copy_from_slice(b);
630    Ok(u64::from_le_bytes(arr))
631}
632
633// ---------------------------------------------------------------------------
634// Tests
635// ---------------------------------------------------------------------------
636
637#[cfg(test)]
638#[allow(clippy::expect_used, clippy::unwrap_used)]
639mod tests {
640    use super::*;
641    use crate::fixture::{
642        CALL_DYLIB_GOT_VA, KH_ADD_SYMBOL, arm64_dylib_add, call_dylib_chained_exit,
643    };
644    use crate::session::{ImageLoadStatus, ImageRole, LoadSession};
645    use crate::test_util::map_test_lock;
646    use std::io::Write;
647    use std::sync::atomic::{AtomicU64, Ordering};
648
649    #[test]
650    fn decode_bind_and_rebase_ptr64() {
651        let raw = encode_ptr_64_bind(0, 0, 0);
652        let (next, dec) = decode_ptr_64(raw, DYLD_CHAINED_PTR_64, 0x1000_0000, 0).unwrap();
653        assert_eq!(next, 0);
654        assert_eq!(
655            dec,
656            ChainDecode::Bind {
657                import_ordinal: 0,
658                ptr_addend: 0
659            }
660        );
661
662        let slide = 0x1000_u64;
663        let target = 0x1000_4000_u64;
664        let raw = encode_ptr_64_rebase(target, 2);
665        let (next, dec) = decode_ptr_64(raw, DYLD_CHAINED_PTR_64, 0x1000_0000, slide).unwrap();
666        assert_eq!(next, 2);
667        assert_eq!(
668            dec,
669            ChainDecode::Rebase {
670                value: target + slide
671            }
672        );
673
674        let raw = encode_ptr_64_rebase(0x4000, 0);
675        let (_, dec) = decode_ptr_64(raw, DYLD_CHAINED_PTR_64_OFFSET, 0x1000_0000, slide).unwrap();
676        assert_eq!(
677            dec,
678            ChainDecode::Rebase {
679                value: 0x1000_0000 + slide + 0x4000
680            }
681        );
682    }
683
684    #[test]
685    fn encode_blob_parses_one_import() {
686        let blob = encode_chained_fixups_blob(
687            3,
688            2,
689            0x4000,
690            0x4000,
691            0,
692            DYLD_CHAINED_PTR_64,
693            1,
694            KH_ADD_SYMBOL,
695        );
696        let header = parse_header(&blob).unwrap();
697        let imports = parse_imports(&blob, &header).unwrap();
698        assert_eq!(imports.len(), 1);
699        let imp = imports.first().expect("one import");
700        assert_eq!(imp.name, KH_ADD_SYMBOL);
701        assert_eq!(imp.lib_ordinal, 1);
702        assert!(!imp.weak);
703    }
704
705    #[test]
706    fn call_dylib_chained_fixture_has_lc() {
707        let bytes = call_dylib_chained_exit();
708        assert!(bytes_have_chained_fixups(&bytes).unwrap());
709        // classic bind sites empty when only chained
710        assert!(crate::bind::collect_bind_sites(&bytes).unwrap().is_empty());
711    }
712
713    #[test]
714    fn chained_bind_writes_got() {
715        static N: AtomicU64 = AtomicU64::new(0);
716        let _guard = map_test_lock();
717        let n = N.fetch_add(1, Ordering::Relaxed);
718        let dir = std::env::temp_dir().join(format!("kh-chain-{}-{n}", std::process::id()));
719        std::fs::create_dir_all(&dir).unwrap();
720        let main_path = dir.join("call_chained.macho");
721        let dylib_path = dir.join("libkh_add.dylib");
722        std::fs::File::create(&main_path)
723            .unwrap()
724            .write_all(&call_dylib_chained_exit())
725            .unwrap();
726        std::fs::File::create(&dylib_path)
727            .unwrap()
728            .write_all(&arm64_dylib_add())
729            .unwrap();
730
731        let mut session = LoadSession::open(&main_path, None).unwrap();
732        let _ = session.map_process().unwrap();
733        let main = session.images().first().unwrap();
734        assert_eq!(main.role, ImageRole::Main);
735        assert!(image_has_chained_fixups(main.image.as_ref().unwrap()));
736        let main_slide = main.slide();
737
738        let export_va = session
739            .images()
740            .iter()
741            .find(|i| i.role == ImageRole::Dylib && matches!(i.status, ImageLoadStatus::Mapped))
742            .and_then(|dylib| {
743                dylib
744                    .exports
745                    .iter()
746                    .find(|e| e.name == KH_ADD_SYMBOL)
747                    .map(|e| e.value.wrapping_add(dylib.slide()))
748            })
749            .expect("dylib export");
750
751        let got_va = CALL_DYLIB_GOT_VA.wrapping_add(main_slide);
752        let main_mem = session
753            .images()
754            .first()
755            .and_then(|i| i.memory.as_ref())
756            .unwrap();
757        let region = main_mem
758            .regions()
759            .iter()
760            .find(|r| got_va >= r.guest_addr && got_va < r.guest_addr.saturating_add(r.vmsize))
761            .expect("DATA");
762        let off = usize::try_from(got_va.saturating_sub(region.guest_addr)).unwrap();
763        let bytes = region.host_bytes().get(off..off + 8).unwrap();
764        let mut le = [0_u8; 8];
765        le.copy_from_slice(bytes);
766        assert_eq!(u64::from_le_bytes(le), export_va);
767
768        drop(session);
769        drop(std::fs::remove_dir_all(dir));
770    }
771}