Package ghidra.pcode.emu.taint

# Enum Class TaintPartsFactory

java.lang.Object
java.lang.Enum<TaintPartsFactory>
ghidra.pcode.emu.taint.TaintPartsFactory

All Implemented Interfaces:
  `AuxEmulatorPartsFactory<TaintVec>`, `Serializable`, `Comparable<TaintPartsFactory>`, `Constable`

public enum TaintPartsFactory extends Enum<TaintPartsFactory> implements AuxEmulatorPartsFactory<TaintVec>
The parts factory for creating emulators with taint analysis

This is probably the most straightforward means of implementing a concrete-plus-auxiliary emulator in Ghidra. For our case, the auxiliary piece is the `TaintVec`. Ideally, the auxiliary piece implements the analog of a byte array, so that each byte in the concrete piece corresponds to an element in the abstract piece. We've done that here by letting each taint set in the vector be the taint on the corresponding byte. Each part we implement must adhere to that rule. For an overview of the parts of a p-code emulator, see `PcodeEmulator`.

As recommended by the documentation, we've implemented the factory as a singleton. As presented in the source, we'll visit each component in this order:

- P-code Arithmetic: `TaintPcodeArithmetic`
- Userop Library: `TaintPcodeUseropLibrary`
- P-code Executor: `TaintPcodeThreadExecutor`
- Machine State: `TaintPcodeExecutorState`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.lang.Enum

  `Enum.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `INSTANCE`
  This singleton factory instance

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DefaultPcodeThread.PcodeThreadExecutor<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>>`
  `createExecutor(AuxPcodeEmulator<TaintVec> emulator, DefaultPcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread)`
  Create an executor for the given thread
  `PcodeExecutorState<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>>`
  `createLocalState(AuxPcodeEmulator<TaintVec> emulator, PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread, BytesPcodeExecutorStatePiece concrete, PcodeStateCallbacks cb)`
  Create the local (register) state of a new emulator
  `PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>>`
  `createLocalUseropLibrary(AuxPcodeEmulator<TaintVec> emulator, PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread)`
  Create a userop library for a given thread
  `PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>>`
  `createLocalUseropStub(AuxPcodeEmulator<TaintVec> emulator)`
  Create a stub userop library for the emulator's threads
  `PcodeExecutorState<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>>`
  `createSharedState(AuxPcodeEmulator<TaintVec> emulator, BytesPcodeExecutorStatePiece concrete, PcodeStateCallbacks cb)`
  Create the shared (memory) state of a new emulator
  `PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>>`
  `createSharedUseropLibrary(AuxPcodeEmulator<TaintVec> emulator)`
  Create the userop library for the emulator (used by all threads)
  `PcodeArithmetic<TaintVec>`
  `getArithmetic(Language language)`
  Get the arithmetic for the emulator given a target language
  `static TaintPartsFactory`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static TaintPartsFactory[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

  ### Methods inherited from class java.lang.Enum

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

  ### Methods inherited from class java.lang.Object

  `getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface ghidra.pcode.emu.auxiliary.AuxEmulatorPartsFactory

  `createThread`

- ## Enum Constant Details

  - ### INSTANCE

    public static final TaintPartsFactory INSTANCE
    This singleton factory instance

- ## Method Details

  - ### values

    public static TaintPartsFactory[] values()
    Returns an array containing the constants of this enum class, in the order they are declared.
    Returns:
      an array containing the constants of this enum class, in the order they are declared

  - ### valueOf

    public static TaintPartsFactory valueOf(String name)
    Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum class has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### getArithmetic

    public PcodeArithmetic<TaintVec> getArithmetic(Language language)
    Get the arithmetic for the emulator given a target language

    Here we simply return the arithmetic for taint vectors for the emulator's language.

    Specified by:
      `getArithmetic` in interface `AuxEmulatorPartsFactory<TaintVec>`
    Parameters:
      `language` - the language
    Returns:
      the arithmetic

  - ### createSharedUseropLibrary

    public PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createSharedUseropLibrary(AuxPcodeEmulator<TaintVec> emulator)
    Create the userop library for the emulator (used by all threads)

    We introduce two userops for tainting variables. Aside from initializing a trace (assuming a trace-integrated emulator), or writing directly to the state in the script, this library will allow clients to quickly initialize taints in the machine. Furthermore, this can permit the placement of taints in intermediate states of the machine during its execution. We construct and return the library here.

    Specified by:
      `createSharedUseropLibrary` in interface `AuxEmulatorPartsFactory<TaintVec>`
    Parameters:
      `emulator` - the emulator
    Returns:
      the userop library

  - ### createLocalUseropStub

    public PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createLocalUseropStub(AuxPcodeEmulator<TaintVec> emulator)
    Create a stub userop library for the emulator's threads

    We have no thread-specific userops to add, which means we also have no need for stubs, so here we just return the empty library.

    Specified by:
      `createLocalUseropStub` in interface `AuxEmulatorPartsFactory<TaintVec>`
    Parameters:
      `emulator` - the emulator
    Returns:
      the library of stubs

  - ### createLocalUseropLibrary

    public PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createLocalUseropLibrary(AuxPcodeEmulator<TaintVec> emulator, PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread)
    Create a userop library for a given thread

    We have no thread-specific userops to add, so here we just return the empty library.

    Specified by:
      `createLocalUseropLibrary` in interface `AuxEmulatorPartsFactory<TaintVec>`
    Parameters:
      `emulator` - the emulator
      `thread` - the thread
    Returns:
      the userop library

  - ### createExecutor

    public DefaultPcodeThread.PcodeThreadExecutor<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createExecutor(AuxPcodeEmulator<TaintVec> emulator, DefaultPcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread)
    Create an executor for the given thread

    This allows the implementor to override or intercept the logic for individual p-code operations that would not otherwise be possible in the arithmetic, e.g., to print diagnostics on a conditional branch.

    We'd like to instrument conditional branches to check for taint, so we'll need a custom executor. We construct it here.

    Specified by:
      `createExecutor` in interface `AuxEmulatorPartsFactory<TaintVec>`
    Parameters:
      `emulator` - the emulator
      `thread` - the thread
    Returns:
      the executor

  - ### createSharedState

    public PcodeExecutorState<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createSharedState(AuxPcodeEmulator<TaintVec> emulator, BytesPcodeExecutorStatePiece concrete, PcodeStateCallbacks cb)
    Create the shared (memory) state of a new emulator

    This is usually composed of pieces using `PairedPcodeExecutorStatePiece`, but it does not have to be. It must incorporate the concrete piece provided. It should be self contained and relatively fast.

    To track what variables in the machine state are tainted, we need a taint state. We construct the part for the machine's memory here.

    Specified by:
      `createSharedState` in interface `AuxEmulatorPartsFactory<TaintVec>`
    Parameters:
      `emulator` - the emulator
      `concrete` - the concrete piece
      `cb` - callbacks to receive emulation events
    Returns:
      the composed state

  - ### createLocalState

    public PcodeExecutorState<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> createLocalState(AuxPcodeEmulator<TaintVec> emulator, PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],TaintVec>> thread, BytesPcodeExecutorStatePiece concrete, PcodeStateCallbacks cb)
    Create the local (register) state of a new emulator

    This is usually composed of pieces using `PairedPcodeExecutorStatePiece`, but it does not have to be. It must incorporate the concrete piece provided. It should be self contained and relatively fast.

    To track what variables in the machine state are tainted, we need a taint state. We construct the part for a thread's registers and temporary (unique) variables here.

    Specified by:
      `createLocalState` in interface `AuxEmulatorPartsFactory<TaintVec>`
    Parameters:
      `emulator` - the emulator
      `thread` - the thread
      `concrete` - the concrete piece
      `cb` - callbacks to receive emulation events
    Returns:
      the composed state