How do you implement relocations for a native (C/C++) architecture plugin?

[nshp]

In binaryninjacore.h there is a struct clearly intended for this, but its members are undocumented:

struct BNCustomRelocationHandler
{
        void* context;
        void (*freeObject)(void* ctxt);

        bool (*getRelocationInfo)(void* ctxt, BNBinaryView* view, BNArchitecture* arch, BNRelocationInfo* result,
                size_t resultCount);
        bool (*applyRelocation)(void* ctxt, BNBinaryView* view, BNArchitecture* arch, BNRelocation* reloc, uint8_t* dest,
                size_t len);
        size_t (*getOperandForExternalRelocation)(void* ctxt, const uint8_t* data, uint64_t addr, size_t length,
                BNLowLevelILFunction* il, BNRelocation* relocation);
};

• I see that getRelocationInfo takes a "result" array and size. I'm guessing it is supposed to fill that out? With what?
• applyRelocation takes a dest pointer and len. What is this for? Do we apply relocations directly to the backing BinaryDataView for the BV? Or do we write them to the dest pointer ... somewhere?
• What is the "Operand" in getOperandForExternalRelocation and what is this function supposed to do?
• Do I actually want a full-on CustomRelocationHandler to just implement JUMP_SLOT and GLOB_DAT relocations which are basically the same functions as some built-in architectures? Would it be more reasonable to wrap e.g. the x86_64 ELF RelocationHandler from the core and just pass through those two relocation types? If so, how much of this API is just a pass-through, or how much do I need to implement?

[plafosse]

Maybe the best answer is... just show me the code.

class x86ElfRelocationHandler: public RelocationHandler
{
public:
	virtual bool GetRelocationInfo(Ref<BinaryView> view, Ref<Architecture> arch, vector<BNRelocationInfo>& result) override
	{
		(void)view; (void)arch;
		set<uint32_t> relocTypes;
		for (auto& reloc : result)
		{
			reloc.type = StandardRelocationType;
			switch (reloc.nativeType)
			{
			case R_386_NONE:
				reloc.type = IgnoredRelocation;
				break;
			case R_386_32:
				reloc.pcRelative = false;
				reloc.baseRelative = false;
				reloc.hasSign = false;
				reloc.size = 4;
				reloc.truncateSize = 4;
				break;
			case R_386_PC32:
			case R_386_GOT32:
			case R_386_PLT32:
				reloc.pcRelative = true;
				reloc.baseRelative = false;
				reloc.hasSign = false;
				reloc.size = 4;
				reloc.truncateSize = 4;
				break;
			case R_386_RELATIVE:
				reloc.pcRelative = false;
				reloc.baseRelative = true;
				reloc.hasSign = false;
				reloc.size = 4;
				reloc.truncateSize = 4;
				reloc.implicitAddend = true;
				reloc.addend = 0;
				break;
			case R_386_COPY:
				reloc.type = ELFCopyRelocationType;
				reloc.pcRelative = false;
				reloc.baseRelative = false;
				reloc.size = 4;
				reloc.truncateSize = 4;
				break;
			case R_386_GLOB_DAT:
				reloc.type = ELFGlobalRelocationType;
				reloc.pcRelative = false;
				reloc.baseRelative = false;
				reloc.size = 4;
				reloc.truncateSize = 4;
				break;
			case R_386_JUMP_SLOT:
				reloc.type = ELFJumpSlotRelocationType;
				reloc.pcRelative = false;
				reloc.baseRelative = false;
				reloc.size = 4;
				reloc.truncateSize = 4;
				break;
			default:
				reloc.type = UnhandledRelocation;
				relocTypes.insert(reloc.nativeType);
			}
		}
		for (auto& reloc : relocTypes)
			LogWarn("Unsupported ELF relocation type: %s", GetRelocationString((Elfx86RelocationType)reloc));
		return true;
	}
};

While the above ELF x86 relocation handler is one of the most simple ones the MIPS relocation handler is rather complicated:

class MipsElfRelocationHandler: public RelocationHandler
{
public:

	bool GetGpAddr(Ref<BinaryView> view, int32_t& gpAddr)
	{
		auto sym = view->GetSymbolByRawName("_gp");
		if (!sym)
			sym = view->GetSymbolByRawName("__gnu_local_gp");
		if (!sym)
			return false;
		gpAddr = sym->GetAddress();
		return true;
	}


	virtual bool ApplyRelocation(Ref<BinaryView> view, Ref<Architecture> arch, Ref<Relocation> reloc, uint8_t* dest, size_t len) override
	{
		if (len < 4)
			return false;
		// All ELF MIPS relocations are implicitAddend
		auto info = reloc->GetInfo();
		auto addr = reloc->GetAddress();
		uint32_t* dest32 = (uint32_t*)dest;
		auto swap = [&arch](uint32_t x) { return (arch->GetEndianness() == LittleEndian)? x : bswap32(x); };
		uint64_t target = reloc->GetTarget();
		uint32_t inst = swap(dest32[0]);
		switch (info.nativeType)
		{
		case R_MIPS_JUMP_SLOT:
		case R_MIPS_COPY:
			dest32[0] = swap(target);
			break;
		case R_MIPS_32:
			dest32[0] = swap(inst + target);
			break;
		case R_MIPS_HI16:
		{
			// Find the first _LO16 in the list of relocations
			BNRelocationInfo* cur = info.next;
			while (cur && (cur->nativeType != R_MIPS_LO16))
			{
				cur = cur->next;
			}

			if (cur)
			{
				uint32_t inst2 = *(uint32_t*)(cur->relocationDataCache);
				Instruction instruction;
				memset(&instruction, 0, sizeof(instruction));
				if (mips_decompose(&inst2, sizeof(uint32_t), &instruction, MIPS_32, cur->address, arch->GetEndianness()))
					break;

				int32_t immediate = swap(inst2) & 0xffff;
				// ADDIU and LW has a signed immediate we have to subtract
				if (instruction.operation == MIPS_ADDIU)
				{
					immediate = instruction.operands[2].immediate;
				}
				else if (instruction.operation == MIPS_LW)
				{
					immediate = instruction.operands[1].immediate;
				}
				uint32_t ahl = ((inst & 0xffff) << 16) + immediate;

				// ((AHL + S) – (short)(AHL + S)) >> 16
				dest32[0] = swap(
					(inst & ~0xffff) |
					(((ahl + target) - (short)(ahl + target)) >> 16)
				);
			}
			else
			{
				LogError("No corresponding R_MIPS_LO16 relocation for R_MIPS_HI16 relocation");
			}
			break;
		}
		case R_MIPS_LO16:
		{
			uint32_t ahl = ((inst & 0xffff) + target) & 0xffff;
			dest32[0] = swap((inst & ~0xffff) | (ahl & 0xffff));
			break;
		}
		case R_MIPS_26:
		{
			// ((A << 2) | (P & 0xf0000000) + S) >> 2
			uint32_t A = (inst & ~0xfc000000) << 2;
			uint32_t P = addr;
			uint32_t S = target;
			uint32_t realTarget = (A | (P & 0xf0000000)) + S;
			dest32[0] = swap(((realTarget >> 2) & ~0xfc000000) | (inst & 0xfc000000));
			break;
		}
		case R_MIPS_GOT16:
		case R_MIPS_CALL16:
		{
			int32_t gpAddr;
			if (!GetGpAddr(view, gpAddr))
				break;
			int32_t vRel16 = (target - gpAddr);
			dest32[0] = swap((inst & ~0xffff) | (vRel16 & 0xffff));
			break;
		}
		default:
			break;
		}
		return true;
	}

	virtual bool GetRelocationInfo(Ref<BinaryView> view, Ref<Architecture> arch, vector<BNRelocationInfo>& result) override
	{
		(void)view; (void)arch;
		for (size_t i = 0; i < result.size(); i++)
		{
			result[i].type = StandardRelocationType;
			result[i].size = 4;
			result[i].pcRelative = false;
			result[i].dataRelocation = true;
			switch (result[i].nativeType)
			{
			case R_MIPS_NONE:
			case R_MIPS_JALR: // Note: optimization hint that can safely be ignored TODO: link-time mutable opcode bytes
				result[i].type = IgnoredRelocation;
				break;
			case R_MIPS_COPY:
				result[i].type = ELFCopyRelocationType;
				break;
			case R_MIPS_JUMP_SLOT:
				result[i].type = ELFJumpSlotRelocationType;
				break;
			case R_MIPS_HI16:
			{
				result[i].dataRelocation = false;
				result[i].pcRelative = false;
				// MIPS_HI16 relocations can have multiple MIPS_LO16 relocations following them
				for (size_t j = i + 1; j < result.size(); j++)
				{
					if (result[j].nativeType == R_MIPS_LO16 && result[j].symbolIndex == result[i].symbolIndex)
					{
						result[j].type = StandardRelocationType;
						result[j].size = 4;
						result[j].pcRelative = false;
						result[j].dataRelocation = false;
						result[i].next = new BNRelocationInfo(result[j]);
						break;
					}
				}
				break;
			}
			case R_MIPS_LO16:
				result[i].pcRelative = false;
				result[i].dataRelocation = false;
				break;
			case R_MIPS_26:
				result[i].pcRelative = true;
				result[i].dataRelocation = false;
				break;
			case R_MIPS_GOT16:
			case R_MIPS_CALL16:
			{
				// Note: GP addr not avaiable pre-view-finalization, however symbol may exist
				int32_t gpAddr;
				if (!GetGpAddr(view, gpAddr))
				{
					result[i].type = UnhandledRelocation;
					LogWarn("Unsupported relocation type: %s : Unable to locate _gp symbol.", GetRelocationString((ElfMipsRelocationType)result[i].nativeType));
				}
				break;
			}
			case R_MIPS_32:
				break;
			default:
				result[i].type = UnhandledRelocation;
				LogWarn("Unsupported relocation type: %s", GetRelocationString((ElfMipsRelocationType)result[i].nativeType));
			}
		}
		return true;
	}

	virtual size_t GetOperandForExternalRelocation(const uint8_t* data, uint64_t addr, size_t length,
		Ref<LowLevelILFunction> il, Ref<Relocation> relocation) override
	{
		(void)data;
		(void)addr;
		(void)length;
		(void)il;
		auto info = relocation->GetInfo();
		size_t result;

		switch (info.nativeType)
		{
			case R_MIPS_HI16:
			case R_MIPS_LO16:
			case R_MIPS_CALL16:
			case R_MIPS_GOT16:
				result = BN_NOCOERCE_EXTERN_PTR;
				break;
			default:
				result = BN_AUTOCOERCE_EXTERN_PTR;
				break;
		}

		return result;
	}
};

Generally speaking, relocations are used for modifying bytes at a given address to point to some symbol. These symbols usually don't exist in the binary and rather exist in some other module, which Binary Ninja doesn't know about. To solve this issue we first record all the symbols referenced by this binary and at the point of BinaryView finalization we assign these symbols addresses in a fake segment which we create at the end of the binary.

The relocation information is used for three distinct purposes:

In ELFBinaryView::Parse

• ELFBinaryView collects all relocation info*
  passes to -> ElfRelocationHandler::GetRelocationInfo
• ELFBinaryView defines the given relocation*
• ELFBinaryView Finalizes
  - During finalization create "externs" segment & section
  - ExternalSymbols are assigned addresses in this segment
  - DataVariables are created for Relocation records which are pointers and in data segments

BinaryView::Read()

• Relocations are applied lazily
• ApplyRelocation is called for each relocation which is being read (actually this is done a page at a time for speed reasons)

Function::GenerateLiftedIL()

• GetOperandForExternalRelocation is called to attempt to determine which LLIL operand contains the pointer. It helps our analysis to know which constants are in fact pointers.

Of the 3 methods a relocation handler specifies only GetRelocationInfo is required.

GetRelocationInfo

The BinaryView needs to query the architecture for how different relocation types should be handled. For ELF files in particular is really important to know which relocations are: JumpSlot, Global, and Copy. This mainly involves filling out the list of structures passed in from the BinaryView. The list of structures is an in/out parameter. The structure is initially filled out with the information from the BinaryView for ELF files this the following information is valid:

relocInfo.symbolIndex = reloc.sym;  // Index of the symbol being relocated
relocInfo.address = reloc.offset;  // the virtual offset of the data in the binary to be relocated
relocInfo.nativeType = reloc.relocType; // the type of relocation
relocInfo.addend = reloc.addend; // a number to be added to the address to get a result
relocInfo.implicitAddend = reloc.implicit; // boolean is the addend implicit in the data being relocated
relocInfo.base = baseAddress; // base address of the binary
virtualReader.Seek(relocInfo.address);
memset(relocInfo.relocationDataCache, 0, sizeof(relocInfo.relocationDataCache));
virtualReader.TryRead(relocInfo.relocationDataCache, MAX_RELOCATION_SIZE /*8*/); // a cache of the bytes stored at that address 

The important fields for defining symbols:

The if the following conditions evaluate to true we will create a pointer data variable

• address != CodeSemantics
• size == architecture address size
• pcRelative == false

If the implementer doesn't specify a relocation handler the DefaultRelocation handler will be used:

bool RelocationHandler::DefaultApplyRelocation(Ref<BinaryView> view, Architecture* arch, Ref<Relocation> reloc, uint8_t* dest, size_t len)
{
	(void)arch;
	BNRelocationInfo info = reloc->GetInfo();
	if (len < info.size)
	{
		return false;
	}
	uint64_t target = reloc->GetTarget();
	uint64_t pc = info.pcRelative ? reloc->GetAddress() : 0;
	uint64_t base = (info.baseRelative && !target) ? view->GetStart() : 0;
	uint64_t addend = 0;
	if (info.implicitAddend && info.size < sizeof(addend))
		memcpy(&addend, dest, reloc->GetInfo().size);
	else
		addend = info.addend;

	if (info.size == 4)
	{
		uint32_t write = target + addend - pc + base;
		memcpy(dest, (uint8_t*)&write, sizeof(uint32_t));
	}
	else if (info.size == 8)
	{
		uint64_t write = target + addend - pc + base;
		if (info.truncateSize == 4)
			memcpy(dest, (uint8_t*)&write, sizeof(uint32_t));
		else
			memcpy(dest, (uint8_t*)&write, sizeof(uint64_t));
	}
	return true;
}

If implementing your own ApplyRelocation method most of the fields can just be used for whatever purposes are desired. Honestly I should have just add some slack space to the end of the structure for user-defined structures.

ApplyRelocation

This part is done lazily for speed reasons. Instead of applying all relocations at once, relocations are applied on-demand as each page of memory is read using BinaryView::Read. The purpose of the method is to actually do the relocation. The implementer writes to the dest pointer the data that it wants the BinaryView to actually read.