Skip to content

Commit aa17d9f

Browse files
Add address-preserving load command injection to Mach-O
There was no way to add a dependency or a runpath to an existing Mach-O image, which is what makes a shipped binary load a library it was not linked against. Adds the operations install_name_tool offers, appending commands into the padding the linker left ahead of the first section so no content moves and every address in the image stays valid. A dependency is appended rather than inserted, because dyld identifies a library by its position among the load commands and the symbol table binds against that number. When the padding runs out the edit throws and names the shortfall, since the alternative is moving content and invalidating the image. Removing a dependency is deliberately not offered for the same numbering reason, matching what install_name_tool exposes. - src/LibObjectFile/MachO/MachOFile.Edit.cs: the add, change and remove operations and the space check - src/LibObjectFile.Tests/MachO/MachOEditingTests.cs: compares against the install_name_tool reference fixture, and asserts no section moves
1 parent f3791e3 commit aa17d9f

2 files changed

Lines changed: 369 additions & 0 deletions

File tree

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
// Copyright (c) Alexandre Mutel. All rights reserved.
2+
// This file is licensed under the BSD-Clause 2 license.
3+
// See the license.txt file in the project root for more information.
4+
5+
using System;
6+
using System.IO;
7+
using System.Linq;
8+
using LibObjectFile.MachO;
9+
10+
namespace LibObjectFile.Tests.MachO;
11+
12+
[TestClass]
13+
public class MachOEditingTests
14+
{
15+
private static string GetFile(string name) => Path.Combine(AppContext.BaseDirectory, "MachO", name);
16+
17+
private static MachOFile Load(string name) => MachOFile.Read(new MemoryStream(File.ReadAllBytes(GetFile(name))));
18+
19+
private static byte[] WriteToArray(MachOFile file)
20+
{
21+
var stream = new MemoryStream();
22+
file.Write(stream);
23+
return stream.ToArray();
24+
}
25+
26+
/// <summary>
27+
/// The reference fixture is the same input run through Apple's <c>install_name_tool</c>, so
28+
/// this pins the encoding against the tool the platform actually ships rather than against
29+
/// this library's own idea of what a runpath command looks like.
30+
/// </summary>
31+
[TestMethod]
32+
public void AddRPathMatchesInstallNameTool()
33+
{
34+
var file = Load("unixthread_i386");
35+
file.AddRPath("@executable_path/../Frameworks");
36+
37+
var expected = File.ReadAllBytes(GetFile("unixthread_i386_rpath"));
38+
ByteArrayAssert.AreEqual(expected, WriteToArray(file), "Adding a runpath does not match install_name_tool");
39+
}
40+
41+
/// <summary>
42+
/// The whole point of editing in place is that nothing moves. A section that shifted would
43+
/// invalidate every address and relocation already baked into the image.
44+
/// </summary>
45+
[TestMethod]
46+
public void AddingCommandsLeavesEverySectionWhereItWas()
47+
{
48+
var before = Load("unixthread_i386");
49+
var originalLength = new FileInfo(GetFile("unixthread_i386")).Length;
50+
var originalOffsets = before.Segments.SelectMany(s => s.Sections).Select(s => (s.Name, s.FileOffset)).ToArray();
51+
52+
var file = Load("unixthread_i386");
53+
file.AddLoadDylib("@executable_path/../Frameworks/injected.dylib");
54+
file.AddRPath("@executable_path/../Frameworks");
55+
var written = WriteToArray(file);
56+
57+
Assert.AreEqual(originalLength, written.Length, "the file changed size");
58+
59+
var reread = MachOFile.Read(new MemoryStream(written));
60+
var newOffsets = reread.Segments.SelectMany(s => s.Sections).Select(s => (s.Name, s.FileOffset)).ToArray();
61+
CollectionAssert.AreEqual(originalOffsets, newOffsets, "a section moved");
62+
63+
foreach (var segment in reread.Segments)
64+
{
65+
var original = before.FindSegment(segment.Name);
66+
Assert.IsNotNull(original);
67+
Assert.AreEqual(original.FileOffset, segment.FileOffset, $"segment {segment.Name} moved");
68+
Assert.AreEqual(original.VmAddress, segment.VmAddress, $"segment {segment.Name} was remapped");
69+
}
70+
}
71+
72+
/// <summary>
73+
/// dyld refers to a library by its position in the command list, so a new dependency has to
74+
/// go last or every existing binding would point at the wrong library.
75+
/// </summary>
76+
[TestMethod]
77+
public void AddLoadDylibAppendsAfterTheExistingLibraries()
78+
{
79+
var file = Load("unixthread_i386");
80+
var before = file.LinkedLibraries.Select(d => d.Name).ToArray();
81+
82+
file.AddLoadDylib("@rpath/injected.dylib");
83+
84+
var after = file.LinkedLibraries.Select(d => d.Name).ToArray();
85+
CollectionAssert.AreEqual(before, after.Take(before.Length).ToArray(), "existing libraries were renumbered");
86+
Assert.AreEqual("@rpath/injected.dylib", after[^1]);
87+
Assert.AreSame(file.LoadCommands[^1], file.LinkedLibraries.Last());
88+
}
89+
90+
[TestMethod]
91+
public void AddedCommandsSurviveARoundTrip()
92+
{
93+
var file = Load("unixthread_i386");
94+
file.AddLoadDylib("@rpath/injected.dylib", MachOLoadCommandType.LoadWeakDylib);
95+
file.AddRPath("@loader_path/../lib");
96+
97+
var reread = MachOFile.Read(new MemoryStream(WriteToArray(file)));
98+
99+
var injected = reread.LinkedLibraries.Single(d => d.Name == "@rpath/injected.dylib");
100+
Assert.IsTrue(injected.IsWeak);
101+
Assert.AreEqual("@loader_path/../lib", reread.RunPaths.Single().Path);
102+
}
103+
104+
/// <summary>
105+
/// Once the padding runs out the only way to continue would be to move content, so the edit
106+
/// has to fail rather than silently invalidate the image.
107+
/// </summary>
108+
[TestMethod]
109+
public void AddingBeyondTheAvailableSpaceThrows()
110+
{
111+
var file = Load("unixthread_i386");
112+
var space = file.AvailableLoadCommandSpace;
113+
114+
// Each of these costs 12 bytes of header plus the padded path.
115+
var path = new string('a', 100);
116+
while (file.AvailableLoadCommandSpace >= 120)
117+
{
118+
file.AddRPath("/" + path + file.LoadCommands.Count);
119+
}
120+
121+
Assert.IsTrue(file.AvailableLoadCommandSpace < space);
122+
var exception = Assert.ThrowsExactly<InvalidOperationException>(() => file.AddRPath("/" + path));
123+
StringAssert.Contains(exception.Message, "free before the first section");
124+
}
125+
126+
[TestMethod]
127+
public void ChangeDylibNameRepointsTheReference()
128+
{
129+
var file = Load("unixthread_i386");
130+
131+
Assert.AreEqual(1, file.ChangeDylibName("/usr/lib/libstdc++.6.dylib", "@rpath/libstdc++.6.dylib"));
132+
Assert.AreEqual(0, file.ChangeDylibName("/nothing/here.dylib", "/other.dylib"));
133+
134+
var reread = MachOFile.Read(new MemoryStream(WriteToArray(file)));
135+
CollectionAssert.Contains(reread.LinkedLibraries.Select(d => d.Name).ToArray(), "@rpath/libstdc++.6.dylib");
136+
CollectionAssert.DoesNotContain(reread.LinkedLibraries.Select(d => d.Name).ToArray(), "/usr/lib/libstdc++.6.dylib");
137+
}
138+
139+
[TestMethod]
140+
public void RemoveRPathDropsOnlyTheMatchingRunPath()
141+
{
142+
var file = Load("unixthread_i386");
143+
file.AddRPath("/one");
144+
file.AddRPath("/two");
145+
146+
Assert.IsTrue(file.RemoveRPath("/one"));
147+
Assert.IsFalse(file.RemoveRPath("/one"));
148+
149+
var reread = MachOFile.Read(new MemoryStream(WriteToArray(file)));
150+
CollectionAssert.AreEqual(new[] { "/two" }, reread.RunPaths.Select(r => r.Path).ToArray());
151+
}
152+
153+
[TestMethod]
154+
public void SetInstallNameRewritesTheIdOfADylib()
155+
{
156+
var file = Load("libhelloworld_x86_64.dylib");
157+
Assert.IsNotNull(file.IdDylib);
158+
Assert.AreEqual("/usr/local/lib/libhelloworld.dylib", file.IdDylib.Name);
159+
160+
file.SetInstallName("@rpath/libhelloworld.dylib");
161+
162+
var reread = MachOFile.Read(new MemoryStream(WriteToArray(file)));
163+
Assert.AreEqual("@rpath/libhelloworld.dylib", reread.IdDylib!.Name);
164+
165+
// An executable has no install name to rewrite.
166+
var executable = Load("unixthread_i386");
167+
Assert.IsNull(executable.IdDylib);
168+
Assert.ThrowsExactly<InvalidOperationException>(() => executable.SetInstallName("@rpath/whatever.dylib"));
169+
}
170+
171+
}
Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
// Copyright (c) Alexandre Mutel. All rights reserved.
2+
// This file is licensed under the BSD-Clause 2 license.
3+
// See the license.txt file in the project root for more information.
4+
5+
using System;
6+
using System.Collections.Generic;
7+
using System.Linq;
8+
9+
namespace LibObjectFile.MachO;
10+
11+
partial class MachOFile
12+
{
13+
/// <summary>
14+
/// Adds a dependency on <paramref name="name"/>, so dyld loads that library at startup.
15+
/// </summary>
16+
/// <param name="name">
17+
/// The install name of the library. It is resolved by dyld rather than opened as a path, so
18+
/// it may start with <c>@rpath</c>, <c>@executable_path</c> or <c>@loader_path</c>.
19+
/// </param>
20+
/// <param name="type">
21+
/// Which dylib command to add. <see cref="MachOLoadCommandType.LoadWeakDylib"/> makes the
22+
/// library optional at runtime.
23+
/// </param>
24+
/// <returns>The command that was added.</returns>
25+
/// <remarks>
26+
/// The command is appended, never inserted, because dyld numbers libraries by their command
27+
/// order and every binding in the symbol table refers to a library by that number. Appending
28+
/// leaves the existing numbering alone.
29+
/// </remarks>
30+
/// <exception cref="ArgumentNullException"><paramref name="name"/> is null.</exception>
31+
/// <exception cref="ArgumentException"><paramref name="name"/> is empty, or <paramref name="type"/> is not a dylib command.</exception>
32+
/// <exception cref="InvalidOperationException">
33+
/// The image has no room left before its first section. The message states the shortfall.
34+
/// </exception>
35+
public MachODylibCommand AddLoadDylib(string name, MachOLoadCommandType type = MachOLoadCommandType.LoadDylib)
36+
{
37+
ArgumentException.ThrowIfNullOrEmpty(name);
38+
39+
if (type is not (MachOLoadCommandType.LoadDylib
40+
or MachOLoadCommandType.LoadWeakDylib
41+
or MachOLoadCommandType.ReexportDylib
42+
or MachOLoadCommandType.LoadUpwardDylib
43+
or MachOLoadCommandType.LazyLoadDylib))
44+
{
45+
throw new ArgumentException($"{type} is not a dylib load command", nameof(type));
46+
}
47+
48+
var command = new MachODylibCommand
49+
{
50+
Type = type,
51+
Is64Bit = Is64Bit,
52+
Name = name,
53+
Timestamp = 0,
54+
// A dependency the loader has no version expectations of. dyld only compares these
55+
// against the target library's own values, and 1.0.0 always satisfies the comparison.
56+
CurrentVersion = 0x10000,
57+
CompatibilityVersion = 0x10000,
58+
};
59+
60+
AppendCommand(command);
61+
return command;
62+
}
63+
64+
/// <summary>
65+
/// Adds a runpath that <c>@rpath</c> expands to when resolving dependencies.
66+
/// </summary>
67+
/// <param name="path">The directory to add, commonly relative to <c>@executable_path</c>.</param>
68+
/// <returns>The command that was added.</returns>
69+
/// <exception cref="ArgumentNullException"><paramref name="path"/> is null.</exception>
70+
/// <exception cref="ArgumentException"><paramref name="path"/> is empty.</exception>
71+
/// <exception cref="InvalidOperationException">
72+
/// The image has no room left before its first section. The message states the shortfall.
73+
/// </exception>
74+
public MachOPathCommand AddRPath(string path)
75+
{
76+
ArgumentException.ThrowIfNullOrEmpty(path);
77+
78+
var command = new MachOPathCommand
79+
{
80+
Type = MachOLoadCommandType.RPath,
81+
Is64Bit = Is64Bit,
82+
Path = path,
83+
};
84+
85+
AppendCommand(command);
86+
return command;
87+
}
88+
89+
/// <summary>
90+
/// Removes a runpath.
91+
/// </summary>
92+
/// <param name="path">The runpath to remove.</param>
93+
/// <returns><c>true</c> if a matching runpath was removed; otherwise <c>false</c>.</returns>
94+
/// <remarks>
95+
/// Unlike the dylib commands, runpaths are unnumbered, so dropping one changes nothing but
96+
/// the search order.
97+
/// </remarks>
98+
/// <exception cref="ArgumentNullException"><paramref name="path"/> is null.</exception>
99+
public bool RemoveRPath(string path)
100+
{
101+
ArgumentNullException.ThrowIfNull(path);
102+
103+
var command = RunPaths.FirstOrDefault(c => c.Path == path);
104+
if (command is null) return false;
105+
106+
LoadCommands.Remove(command);
107+
Reindex();
108+
return true;
109+
}
110+
111+
/// <summary>
112+
/// Repoints every reference to <paramref name="oldName"/> at <paramref name="newName"/>,
113+
/// which is what <c>install_name_tool -change</c> does.
114+
/// </summary>
115+
/// <param name="oldName">The install name currently referenced.</param>
116+
/// <param name="newName">The install name to reference instead.</param>
117+
/// <returns>The number of commands that were repointed.</returns>
118+
/// <exception cref="ArgumentNullException"><paramref name="oldName"/> or <paramref name="newName"/> is null.</exception>
119+
/// <exception cref="ArgumentException"><paramref name="newName"/> is empty.</exception>
120+
/// <exception cref="InvalidOperationException">
121+
/// The longer name does not fit in the room left before the first section.
122+
/// </exception>
123+
public int ChangeDylibName(string oldName, string newName)
124+
{
125+
ArgumentNullException.ThrowIfNull(oldName);
126+
ArgumentException.ThrowIfNullOrEmpty(newName);
127+
128+
var matches = LoadCommands.OfType<MachODylibCommand>().Where(c => c.Name == oldName).ToArray();
129+
if (matches.Length == 0) return 0;
130+
131+
long extra = 0;
132+
foreach (var command in matches)
133+
{
134+
command.Name = newName;
135+
extra += Math.Max(0, (long)command.MinimumSize - (long)command.Size);
136+
}
137+
138+
EnsureLoadCommandSpace(extra);
139+
foreach (var command in matches)
140+
{
141+
command.Size = Math.Max(command.Size, command.MinimumSize);
142+
}
143+
144+
return matches.Length;
145+
}
146+
147+
/// <summary>
148+
/// Sets this image's own install name, which is what <c>install_name_tool -id</c> does.
149+
/// </summary>
150+
/// <param name="name">The install name to record.</param>
151+
/// <exception cref="ArgumentNullException"><paramref name="name"/> is null.</exception>
152+
/// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
153+
/// <exception cref="InvalidOperationException">
154+
/// This image is not a dylib and so has no install name, or the longer name does not fit.
155+
/// </exception>
156+
public void SetInstallName(string name)
157+
{
158+
ArgumentException.ThrowIfNullOrEmpty(name);
159+
160+
var command = IdDylib
161+
?? throw new InvalidOperationException("This image has no LC_ID_DYLIB command, so it is not a dylib and has no install name.");
162+
163+
command.Name = name;
164+
EnsureLoadCommandSpace(Math.Max(0, (long)command.MinimumSize - (long)command.Size));
165+
command.Size = Math.Max(command.Size, command.MinimumSize);
166+
}
167+
168+
private void AppendCommand(MachOLoadCommand command)
169+
{
170+
command.Size = command is MachOPathLoadCommand path ? path.MinimumSize : command.Size;
171+
EnsureLoadCommandSpace((long)command.Size);
172+
173+
command.Parent = this;
174+
LoadCommands.Add(command);
175+
Reindex();
176+
}
177+
178+
/// <summary>
179+
/// Checks that the command table can grow by <paramref name="additionalBytes"/> without
180+
/// pushing into the first section.
181+
/// </summary>
182+
private void EnsureLoadCommandSpace(long additionalBytes)
183+
{
184+
if (additionalBytes <= AvailableLoadCommandSpace) return;
185+
186+
throw new InvalidOperationException(
187+
$"The load commands need {additionalBytes} more bytes but only {AvailableLoadCommandSpace} are free before the first section at 0x{ContentStartOffset:X}. " +
188+
"Making room would mean moving content, which would invalidate the addresses in this image.");
189+
}
190+
191+
private void Reindex()
192+
{
193+
for (int i = 0; i < LoadCommands.Count; i++)
194+
{
195+
LoadCommands[i].Index = i;
196+
}
197+
}
198+
}

0 commit comments

Comments
 (0)