com.pnfsoftware.jeb.core.units.code.android.ir.IDState |
dexdec
IR state (referred as "State"), used to perform IR evaluations, emulation and
sandboxing.
Note: This interface exposes a significant subset of the State functionalities, but not all. In particular, the sandbox itself cannot be manipulated (it can only be enabled or disabled). Future API extensions may allow third-party clients to access those controls.
A State can be created or retrieved via the global IR context (the g
attribute in
optimizers inheriting AbstractDOptimizer
), see methods
createState()
and getThreadSharedState()
.
The emulation of code takes place within a context
. Each context has a stack of
frame
s, holding the emulator state relative to the method being executed (the top frame
for the current method, the second frame for the caller of the current method, etc.).
Note the special role of IDImm
objects: they represent both immediate values, as well as
object references living in a State object.
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | DEFAULT_MAX_DURATION | Default maximum duration, in milliseconds. | |||||||||
int | DEFAULT_MAX_INVOCATION_DEPTH | Default maximum depth for method invocations. | |||||||||
int | DEFAULT_MAX_ITERCOUNT | Default maximum iteration count. | |||||||||
int | SUBEXEC_ALLOW_ALL | Sub-routine execution policy: this special flag allows everything. | |||||||||
int | SUBEXEC_ALLOW_EXTERNAL | Sub-routine execution policy: this flag allows external routines. | |||||||||
int | SUBEXEC_ALLOW_INTERNAL | Sub-routine execution policy: this flag allows internal routines. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
abstract void |
addClassfilesToSandbox(File f)
Convenience method to add class files (single class or Jar) to the sandbox classloader.
| ||||||||||
abstract boolean |
canRun()
Quickly determine whether this State is usable, that is, can code be emulated (e.g.
| ||||||||||
abstract IDImm |
cloneArray(IDImm arrayRef)
Clone an array.
| ||||||||||
abstract IDImm |
createArray(IJavaType arrayType, int len, List<? extends IDImm> initialValues)
Create an array.
| ||||||||||
abstract IDEmuContext |
createContext(String name)
This method is deprecated.
use
pushContext(String)
| ||||||||||
abstract IDEmuFrame |
createFrame(String methodSignature)
This method is deprecated.
use
pushFrame(String)
| ||||||||||
abstract IDImm |
createNewInstance(String constructorSignature, Collection<IDExpression> constructorParameters)
Create a new instance of an object.
| ||||||||||
abstract IDEmuContext |
deleteTopContext()
Delete the most recent (top) execution context.
| ||||||||||
abstract IDEmuFrame |
deleteTopFrame()
Delete the most recent (top) frame of the current execution context.
| ||||||||||
abstract boolean |
deleteVariable(long varid)
Convenience method to remove a defined variable in the current frame (top frame of the top
context).
| ||||||||||
abstract void |
enableEmulator(boolean enabled)
Enable or disable the emulator.
| ||||||||||
abstract void |
enableExceptionHandling(boolean enabled)
Enable or disable the handling of exceptions generated by the emulated code.
| ||||||||||
abstract boolean |
enableSandbox(boolean enabled)
Enable or disable the sandbox.
| ||||||||||
abstract IDImm |
execute(DExecutionParameters info)
Execute some IR.
| ||||||||||
abstract IDImm |
executeDexMethod(IDexMethod m, List<IDExpression> args)
Execute (emulate) an IR method within a new context.
| ||||||||||
abstract IDImm |
executeExternalMethod(String methodSignature, Collection<IDExpression> methodParameters, DInvokeType invokeType)
Execute an external (non dex) non-constructor method.
| ||||||||||
abstract IDImm |
getArrayElement(IDImm arrayRef, int index)
Read an array element.@return
| ||||||||||
abstract Object |
getArrayObject(IDImm ref)
Retrieve an array by reference.@return
| ||||||||||
abstract int |
getArrayObjectLength(IDImm ref)
Get the length of an array.@return
| ||||||||||
abstract IDImm |
getClassReference(String classname)
Retrieve a classref reference by name.@return
| ||||||||||
abstract Collection<IDEmuContext> |
getContexts()
Retrieve a read-only collection of emulation contexts.
| ||||||||||
abstract int |
getCountOfContexts()
A convenience method to get the count of contexts.
| ||||||||||
abstract IDEmuContext |
getCurrentContext()
Convenience method to retrieve the current (newest) context.
| ||||||||||
abstract long |
getCurrentDuration()
Set the emulator timeout value.
| ||||||||||
abstract IDEmuFrame |
getCurrentFrame()
Convenience method to retrieve the top frame of the current (newest) context.
| ||||||||||
abstract int |
getCurrentIterationCount()
Retrieve the current total iteration count, that is, the total number of statements emulated
or executed by this object.
| ||||||||||
abstract Object |
getData(String key)
Get (retrieve) a piece of data attached to this emulator object.
| ||||||||||
abstract Collection<IDMethodExecutionHelper> |
getExecutionHelpers()
Retrieve the collection of all registered method execution helpers.
| ||||||||||
abstract IDGlobalContext |
getGlobalContext()
Retrieve the global IR context that was used to create this State.
| ||||||||||
abstract IDImm |
getInstanceField(String fsig, IDImm instance)
Retrieve the value of an instance field.@return
| ||||||||||
abstract int |
getIterationCountLeft()
Retrieve the number of iterations left.
| ||||||||||
abstract int |
getMaxInvocationDepth()
Get the maximum allowed depth for method invocations.
| ||||||||||
abstract Object |
getObject(IDImm ref)
Retrieve an object value by its reference.
| ||||||||||
abstract Object |
getObject(IDImm ref, boolean provideNativeObject)
Retrieve an object value by its reference.
| ||||||||||
abstract int |
getPC()
Convenience method to read the IR program counter in the current frame (top frame of the top
context).
| ||||||||||
abstract URLClassLoader |
getSandboxClassLoader()
Retrieve the classloader used by the sandbox.
| ||||||||||
abstract File |
getSandboxDropFolder()
Retrieve the sandbox folder containing dropped files.
| ||||||||||
abstract IDImm |
getStaticField(String fsig)
Retrieve the value of a static field.
| ||||||||||
abstract String |
getStringObject(IDImm strOrRef)
Retrieve a string by reference.@return
| ||||||||||
abstract int |
getSubRoutineInvocationPolicy()
Retrieve the emulation policy for invoking sub-routines.
| ||||||||||
abstract long |
getTimeLeft()
Retrieve the amount of emulation time left.
| ||||||||||
abstract IJLSTypeAdapter |
getTypeAdapter()
Provide the type adapter used by the emulator and sandbox.
| ||||||||||
abstract IDImm |
getVariable(long varid, boolean softFail)
Convenience method to read the value of a variable in the current frame (top frame of the top
context).
| ||||||||||
abstract IDImm |
getVariable(long varid)
Convenience method to read the value of a variable in the current frame (top frame of the top
context).
| ||||||||||
abstract boolean |
hasVariable(long varid)
Determine whether a variable is set (has a value).@return
| ||||||||||
abstract boolean |
isEmulatorEnabled()
Determine whether the emulator is enabled.
| ||||||||||
abstract boolean |
isExceptionHandlingEnabled()
Determine whether handling of exceptions generated by the emulated code is enabled.
| ||||||||||
abstract boolean |
isInstanceOf(IDImm obj, IDImm clz)
Determine whether an object is assignment-compatible with a class type.@return
| ||||||||||
abstract boolean |
isPerformDirectUnreflection()
Determine if direct unreflection is enabled.
| ||||||||||
abstract boolean |
isSandboxEnabled()
Determine whether the sandbox is enabled.
| ||||||||||
abstract Class<?> |
loadClass(String csig)
Load a class.
| ||||||||||
abstract IDEmuContext |
pushContext(String name)
Create and push a new execution context.
| ||||||||||
abstract IDEmuFrame |
pushFrame(String methodSignature)
Create and push a frame within the current (top) emulation context.
| ||||||||||
abstract int |
registerEmulatorHooks(IDEmulatorHooks hooks)
Register emulator hooks.
| ||||||||||
abstract void |
registerExecutionHelper(IDMethodExecutionHelper helper)
Register a method execution helper.
| ||||||||||
abstract IDImm |
registerObject(Object o)
Register an object.
| ||||||||||
abstract int |
registerSandboxHooks(IDSandboxHooks hooks)
Register sandbox hooks.
| ||||||||||
abstract Object |
releaseObject(IDImm ref)
Release an object currently living in this State.
| ||||||||||
abstract void |
setArrayElement(IDImm arrayRef, int index, IDImm val)
Write an array element.
| ||||||||||
abstract void |
setData(String key, Object value)
Set (attach) a piece data to this emulator object.
| ||||||||||
abstract void |
setInstanceField(String fsig, IDImm instance, IDImm val)
Update the value of an instance field.
| ||||||||||
abstract void |
setMaxDuration(long maxDuration)
Set the emulator timeout value.
| ||||||||||
abstract void |
setMaxInvocationDepth(int maxInvocationDepth)
Set the maximum depth for method invocations.
| ||||||||||
abstract void |
setMaxIterationCount(int maxInsnCount)
Set or reset the max iteration count.
| ||||||||||
abstract void |
setPC(int pc)
Convenience method to write the IR program counter in the current frame (top frame of the top
context).
| ||||||||||
abstract void |
setPerformDirectUnreflection(boolean performDirectUnreflection)
Enable or disable direct unreflection (disabled by default).
| ||||||||||
abstract File |
setSandboxDroppedFilesCollection(String locationName, boolean allowFileRemoval)
Specify where files written by sandboxed code should be written to.
| ||||||||||
abstract void |
setStaticField(String fsig, IDImm val)
Update the value of a static field.
| ||||||||||
abstract void |
setSubRoutineInvocationPolicy(int subRoutineInvocationPolicy)
Set the emulation policy for invoking sub-routines.
| ||||||||||
abstract void |
setVariable(long varid, IDImm value)
Convenience method to write the value of a variable in the current frame (top frame of the
top context).
| ||||||||||
abstract IDState |
shallowCopy()
Reserved for internal use.
| ||||||||||
abstract boolean |
unregisterEmulatorHooks(int hookId)
Unregister emulator hooks.
| ||||||||||
abstract boolean |
unregisterExecutionHelper(String methodSignature)
Remove a method execution helper.
| ||||||||||
abstract boolean |
unregisterSandboxHooks(int hookId)
Unregister sandbox hooks.
|
Default maximum duration, in milliseconds.
Default maximum depth for method invocations.
Default maximum iteration count.
Sub-routine execution policy: this special flag allows everything.
Sub-routine execution policy: this flag allows external routines.
Sub-routine execution policy: this flag allows internal routines.
Convenience method to add class files (single class or Jar) to the sandbox classloader.
IOException |
---|
Quickly determine whether this State is usable, that is, can code be emulated (e.g. did we reach the max iteration count or timeout?)
Clone an array.
arrayRef | source array reference |
---|
array.clone
protected method)DexDecEvaluationException |
---|
Create an array. The array object will live in this emulator.
len | the length of the first dimension, re-using the examples above, would indicate an array int[N][][], String[N][], X[N] |
---|---|
initialValues | a list of initial values, non-null, whose length must in [0, N] |
DexDecEvaluationException |
---|
Create a new instance of an object. This method is similar to newInstance()
; it
allocates an object and executes a constructor method.
constructorSignature | full signature, e.g. Lcom/abc/Foo-><init>(II)V |
---|---|
constructorParameters | parameters |
DexDecEvaluationException |
---|
Delete the most recent (top) frame of the current execution context.
Convenience method to remove a defined variable in the current frame (top frame of the top context).
varid | variable id |
---|
DexDecEvaluationException |
---|
Enable or disable the emulator. The emulator must be enabled to permit the execution of IDInstruction#evaluate().
Enable or disable the handling of exceptions generated by the emulated code.
Enable or disable the sandbox. The sandbox is used to safely execute external code (not present in the form of dex bytecode in the application).
Execute some IR.
The execution takes place in the current frame (i.e. no new context or frame is created, it
is the responsibility of the caller to do so). That current frame is popped only if the
method execution completes fully. On other cases (e.g., an exception is raised, null
is returned return because pcExpectedTermination
was provided and was reached, etc.),
the current frame is left as-is to allow client code to examine it.
info | execution parameters, including the IR instructions |
---|
DexDecEvaluationException |
---|
Execute (emulate) an IR method within a new context. Upon completion (success or error), the
newly-created context is auto-discarded. The execution result is provided; global objects
created by the execution can be reviewed with methods like getObject(IDImm)
; the
rest (frame variables, etc.) is discarded.
NOTE: This method is currently limited to the execution of dex internal methods (not pure
references, not abstract or native). This method is not meant to execute constructor code
(<init>
methods); to create new objects, use
createNewInstance(String, Collection)
.
m | a dex internal method |
---|---|
args | method arguments |
DexDecEvaluationException | an evaluation exception occurred |
---|
Execute an external (non dex) non-constructor method.
methodSignature | full signature, e.g. Lcom/abc/Foo->bar(I)L |
---|---|
methodParameters | parameters |
invokeType | invocation type (it cannot be NEW ) |
DexDecEvaluationException |
---|
Read an array element.@return
DexDecEvaluationException |
---|
Retrieve an array by reference.@return
DexDecEvaluationException |
---|
Get the length of an array.@return
DexDecEvaluationException |
---|
Retrieve a classref reference by name.@return
classname | fully-qualified name, e.g. Lcom/abc/Foo; |
---|
DexDecEvaluationException |
---|
Retrieve a read-only collection of emulation contexts.
A convenience method to get the count of contexts.
Convenience method to retrieve the current (newest) context.
Set the emulator timeout value.
If a run exceeds the timeout, the emulation fails and a
DexDecEvalTimeoutExceededException
exception is raised.
Convenience method to retrieve the top frame of the current (newest) context.
Retrieve the current total iteration count, that is, the total number of statements emulated or executed by this object.
If the maximum iteration count is reached, a DexDecEvalItercountExceededException
exception is be raised.
Get (retrieve) a piece of data attached to this emulator object.
key | non-null key |
---|
Retrieve the collection of all registered method execution helpers.
Retrieve the global IR context that was used to create this State.
Retrieve the value of an instance field.@return
DexDecEvaluationException |
---|
Retrieve the number of iterations left.
Get the maximum allowed depth for method invocations.
DEFAULT_MAX_INVOCATION_DEPTH
)
Retrieve an object value by its reference.
ref | a wrapped reference or a string immediate |
---|
DexDecEvaluationException |
---|
Retrieve an object value by its reference.
ref | a wrapped reference or a string immediate |
---|
DexDecEvaluationException |
---|
Convenience method to read the IR program counter in the current frame (top frame of the top context).
Retrieve the classloader used by the sandbox.
Retrieve the sandbox folder containing dropped files.
Retrieve the value of a static field.
Note: field resolution is performed, just as the sget
opcode does. Example: if type Y
extends type X, X contains field i, and the caller attempts to read Y.i, this method will
resolve the field to X.i.@return
DexDecEvaluationException |
---|
Retrieve a string by reference.@return
DexDecEvaluationException |
---|
Retrieve the emulation policy for invoking sub-routines.
SUBEXEC_xxx
flags
Retrieve the amount of emulation time left.
Provide the type adapter used by the emulator and sandbox. Only internal, fully-qualified
names are accepted by this adapter, e.g. Lcom/abc/Foo;
Convenience method to read the value of a variable in the current frame (top frame of the top context).
varid | variable id |
---|
DexDecEvaluationException |
---|
Convenience method to read the value of a variable in the current frame (top frame of the top context). The variable must exist.
varid | variable id |
---|
DexDecEvaluationException | thrown if the variable is not set |
---|
Determine whether a variable is set (has a value).@return
varid | variable id |
---|
DexDecEvaluationException |
---|
Determine whether the emulator is enabled. The emulator must be enabled to permit the execution of IDInstruction#evaluate().
Determine whether handling of exceptions generated by the emulated code is enabled. If not,
any exception raised during emulation will bubble up as a DexDecEvaluationException
.
Determine whether an object is assignment-compatible with a class type.@return
DexDecEvaluationException |
---|
Determine if direct unreflection is enabled.
Determine whether the sandbox is enabled.
Load a class. The class may be internal (defined in dex) or external.
csig | fully-qualified signature, e.g. Lcom/abc/Foo; |
---|
Class
objectDexDecEvaluationException |
---|
Create and push a new execution context. IR emulation takes place within the top emulation context.
Create and push a frame within the current (top) emulation context. A frame (method frame) contains the current PC, variables, etc.
Register emulator hooks. Refer to IDEmulatorHooks
for details.
hooks | an emulator sandbox hooks object |
---|
Register a method execution helper. A helper is preferred over bytecode emulation or sandbox execution.
Example: if a helper is provided for Ljava/lang/String;->indexOf(I)I
, any attempt to
emulate indexOf()
will result in the helper being called. The helper is responsible
for providing the result of execution.
Register sandbox hooks. Refer to IDSandboxHooks
for details.
hooks | an emulator sandbox hooks object |
---|
Release an object currently living in this State. Watch out! References are not checked. Other objects may use the deleted object.@return
DexDecEvaluationException |
---|
Write an array element.
DexDecEvaluationException |
---|
Set (attach) a piece data to this emulator object.
key | non-null key |
---|---|
value | non-null value |
Update the value of an instance field.
DexDecEvaluationException |
---|
Set the emulator timeout value.
If a run exceeds the timeout, the emulation fails and a
DexDecEvalTimeoutExceededException
exception is raised.
maxDuration | in ms |
---|
Set the maximum depth for method invocations.
This attribute is also used as a safety mechanism to prevent stack overflows during emulation.
maxInvocationDepth | a positive value |
---|
Set or reset the max iteration count.
If the maximum iteration count is reached, a DexDecEvalItercountExceededException
exception is be raised.
Convenience method to write the IR program counter in the current frame (top frame of the top context).
Enable or disable direct unreflection (disabled by default). When enabled, a non-constructor method invocation or field access (read, write) done by reflection, which execution would normally go through the sandbox, will be attempted to be resolved. If the resolution is successful, direct execution may be attempted, thereby saving a potentially costly context-switch to the sandbox.
Specify where files written by sandboxed code should be written to. All files written during emulation will be dropped to this folder.
locationName | a simple name (the folder path will be derived from this name) |
---|---|
allowFileRemoval | if true, files dropped by the sandboxed code cannot be removed |
Update the value of a static field.
Note: field resolution is performed, just as the sput
opcode does. Example: if type Y
extends type X, X contains field i, and the caller attempts to write Y.i, this method will
resolve the field to X.i.
DexDecEvaluationException |
---|
Set the emulation policy for invoking sub-routines.
subRoutineInvocationPolicy | a combination of SUBEXEC_xxx flags
|
---|
Convenience method to write the value of a variable in the current frame (top frame of the top context).
varid | variable id |
---|---|
value | the value to be written |
DexDecEvaluationException |
---|
Reserved for internal use.
Generate a partial copy of this state.
Unregister emulator hooks.
hookId | hooks object id, returned by registerEmulatorHooks |
---|
Remove a method execution helper.
Unregister sandbox hooks.
hookId | hooks object id, returned by registerSandboxUserHooks |
---|