Difference between revisions of "Compel"

From CRIU
Jump to: navigation, search
(Using libcompel.a library: rewording)
(Running parasite code: slight rewording)
Line 54: Line 54:
 
== Running parasite code ==
 
== Running parasite code ==
  
So, in order to infect a task with parasite one must.
+
So, in order to infect a task with parasite one must do the following.
  
* Stop the task with <code>compel_stop_task(int pid)</code> call and keep the return value if it's positive (it contains the task state)
+
* Stop the task. This is done by calling <code>compel_stop_task(int pid)</code>. Its return value should be saved in case it's positive (it contains the task state).
* Prepare the infection handler with <code>compel_prepare(int pid)</code> call. The return value is an opaque pointer to <code>struct parasite_ctl</code>
+
* Prepare the infection handler. This is done by calling <code>compel_prepare(int pid)</code>. The return value is an opaque pointer to <code>struct parasite_ctl</code>.
* Run the remote code
+
* Run the remote code:
** Just execute a system call with <code>compel_syscall(ctl, int syscall_nr, long *ret, int arg ... (6 of them))</code>
+
** Execute a system call with <code>compel_syscall(ctl, int syscall_nr, long *ret, int arg ...)</code> (all 6 parameters)
** Infect victim with parasite blob with <code>compel_infect(ctl, nr_thread, size_of_args_area)</code>
+
** Infect the victim with the parasite blob by calling <code>compel_infect(ctl, nr_thread, size_of_args_area)</code>
* Cure the victim with <code>compel_cure(ctl)</code> and stop using the ctl pointer as it's freed by the call
+
* Cure the victim by calling <code>compel_cure(ctl)</code>. Note that <code>ctl</code> pointer is freed by the call so it should not be used thereafter.
* Resume the task with <code>compel_resume_task(pid, orig_state, state)</code> with the saved state value
+
* Resume the task by calling <code>compel_resume_task(pid, orig_state, state)</code> with the saved state value from the first step.
  
 
=== Infecting ===
 
=== Infecting ===
  
Infecting the victim with parasite blob needs some special treatment.
+
Infecting the victim with a parasite blob needs some special treatment.
  
First, the ctl should be configured with the blob information. Currently there's only one type of blobs, generated by <code>compel hgen</code>. To put this info into ctl one should call <code>compel_parasite_blob_desc(ctl)</code> to get a pointer on <code>struct parasite_blob_desc</code> and fill in the fields of this strucure
+
First, the <code>ctl</code> should be configured with the blob information. Currently there is only one type of blobs, generated by <code>compel hgen</code>. To put this info into ctl, one should call <code>compel_parasite_blob_desc(ctl)</code> to get a pointer on <code>struct parasite_blob_desc</code> and fill in the fields of this strucure:
  
 
* <code>.parasite_type</code> should be set to <code>COMPEL_BLOB_CHEADER</code>
 
* <code>.parasite_type</code> should be set to <code>COMPEL_BLOB_CHEADER</code>
Line 74: Line 74:
 
* <code>.hdr.bsize</code> should be set to the sizeof(this symbol)
 
* <code>.hdr.bsize</code> should be set to the sizeof(this symbol)
 
* <code>.hdr.nr_gotpcrel</code> should be set to the <code>parasite_nr_gotpcrel</code> of hgen
 
* <code>.hdr.nr_gotpcrel</code> should be set to the <code>parasite_nr_gotpcrel</code> of hgen
* Three offsets below should be set to respective offsets generated with the <code>parasite_sym</code> value
+
* The following three offsets should be set to respective offsets generated with the <code>parasite_sym</code> value
 
** <code>.hdr.parasite_ip_off</code> to <code>COMPEL_H_PARASITE_HEAD(parasite_sym)</code>
 
** <code>.hdr.parasite_ip_off</code> to <code>COMPEL_H_PARASITE_HEAD(parasite_sym)</code>
 
** <code>.hdr.addr_cmd_off</code>  to <code>COMPEL_H_PARASITE_CMD(parasite_sym)</code>
 
** <code>.hdr.addr_cmd_off</code>  to <code>COMPEL_H_PARASITE_CMD(parasite_sym)</code>
 
** <code>.hdr.addr_arg_off</code>  to <code>COMPEL_H_PARASITE_ARGS(paraste_sym)</code>
 
** <code>.hdr.addr_arg_off</code>  to <code>COMPEL_H_PARASITE_ARGS(paraste_sym)</code>
 
* <code>.hdr.relocs</code> should be set to <code>parasite_relocs</code> argument (it's an array)
 
* <code>.hdr.relocs</code> should be set to <code>parasite_relocs</code> argument (it's an array)
* <code>.hdr.nr_relocs</code> should be set to the number of elements in this array (<code>sizeof(arr)/sizeof(arr[0])</code>)
+
* <code>.hdr.nr_relocs</code> should be set to a number of elements in this array (<code>sizeof(arr)/sizeof(arr[0])</code>)
  
 
Second, when infecting a parasite one should specify the amount of threads it will mess with (1, if only the thread leader will be accessed) and the maximum size of the memory area shared between infecting task and parasite used for arguments/result passing.
 
Second, when infecting a parasite one should specify the amount of threads it will mess with (1, if only the thread leader will be accessed) and the maximum size of the memory area shared between infecting task and parasite used for arguments/result passing.
Line 85: Line 85:
 
=== Arguments passing ===
 
=== Arguments passing ===
  
To pass arguments between the infecting code and parasite one may call <code>compel_parasite_args(ctl, type)</code> and get the pointer where it can put data. Subsequent calls to <code>compel_rpc_call[_sync]()</code> would result int this data visible in <code>void *arg</code> address of the <code>parasite_daemon_cmd()</code>.
+
To pass arguments between the infecting code and parasite, one may call <code>compel_parasite_args(ctl, type)</code> and get the pointer where it can put data. Subsequent calls to <code>compel_rpc_call[_sync]()</code> will result in this data visible in <code>void *arg</code> address of the <code>parasite_daemon_cmd()</code>.
  
 
== See also ==
 
== See also ==

Revision as of 03:47, 26 November 2016

Compel is a utility to execute arbitrary code in a context of a foreign process. Compel is part of CRIU, and its sources are available from the criu-dev branch of CRIU repo, subdirectory compel.

The code to be executed is called parasite code. Once compiled with compel flags and packed, it can be executed in other task's context. Note the code is run in environment without glibc, thus it can not call the usual stdio/stdlib/etc. functions.

A set of compel plugins are provided for your convenience. Plugins get linked to the parasite binary during the pack stage.

Writing parasite code

Execution of parasite code always starts with a function in compel std plugin that should be linked with parasite binary (see below). From the parasite code these symbols should be available for libcompel to work

parasite_trap_cmd(int cmd, void *arg);
This routine gets called by compel_run_in_thread()
parasite_daemon_cmd(int cmd, void *arg);
This routine gets called by compel_rpc_call() and compel_rpc_call_sync(). The arg points to the memory with arguments, see the #Arguments passing section below.
parasite_cleanup(void);
This gets called on parasite unload by compel_cure()

Compiling and packing

Compile the source of your parasite code with compel flags:

$ gcc -c foo1.c -o foo1.o $(compel cflags)

Don't forget to put compel/include/uapi/ directory into include paths.

Then link the parasite binary. Include all the .o files needed and compel std plugin by using compel linker script.

$ ld foo1.o foo2.o compel/plugins/std.built-in.o -T compel/arch/$ARCH/scripts/compel-pack.lds.S -o parasite.po 

The .po blob can now be loaded as parasite.

Loading blob

Using CLI

This functionality is in plans and not implemented yet.

Using libcompel.a library

Currently there is only one way to load the blob into victim task using libcompel.a, called c-header. First you should make a header out of you .po file:

compel hgen -f parasite.po -v parasite_relocs -p parasite_sym -s parasite_blob -r parasite_nr_gotpcrel -u compel/include/uapi/ -o parasite.h

Here the -f option tells which binary to turn into header, and -o option tells where to put the resulting header. The rest of the arguments are used to fill in the blob descriptor, see the #Infecting section below for details.

Once parasite.h file is ready, it should be included into the infecting program source code to be compiled with it.

Running parasite code

So, in order to infect a task with parasite one must do the following.

  • Stop the task. This is done by calling compel_stop_task(int pid). Its return value should be saved in case it's positive (it contains the task state).
  • Prepare the infection handler. This is done by calling compel_prepare(int pid). The return value is an opaque pointer to struct parasite_ctl.
  • Run the remote code:
    • Execute a system call with compel_syscall(ctl, int syscall_nr, long *ret, int arg ...) (all 6 parameters)
    • Infect the victim with the parasite blob by calling compel_infect(ctl, nr_thread, size_of_args_area)
  • Cure the victim by calling compel_cure(ctl). Note that ctl pointer is freed by the call so it should not be used thereafter.
  • Resume the task by calling compel_resume_task(pid, orig_state, state) with the saved state value from the first step.

Infecting

Infecting the victim with a parasite blob needs some special treatment.

First, the ctl should be configured with the blob information. Currently there is only one type of blobs, generated by compel hgen. To put this info into ctl, one should call compel_parasite_blob_desc(ctl) to get a pointer on struct parasite_blob_desc and fill in the fields of this strucure:

  • .parasite_type should be set to COMPEL_BLOB_CHEADER
  • .hdr.mem should be set to the parasite_blob of hgen
  • .hdr.bsize should be set to the sizeof(this symbol)
  • .hdr.nr_gotpcrel should be set to the parasite_nr_gotpcrel of hgen
  • The following three offsets should be set to respective offsets generated with the parasite_sym value
    • .hdr.parasite_ip_off to COMPEL_H_PARASITE_HEAD(parasite_sym)
    • .hdr.addr_cmd_off to COMPEL_H_PARASITE_CMD(parasite_sym)
    • .hdr.addr_arg_off to COMPEL_H_PARASITE_ARGS(paraste_sym)
  • .hdr.relocs should be set to parasite_relocs argument (it's an array)
  • .hdr.nr_relocs should be set to a number of elements in this array (sizeof(arr)/sizeof(arr[0]))

Second, when infecting a parasite one should specify the amount of threads it will mess with (1, if only the thread leader will be accessed) and the maximum size of the memory area shared between infecting task and parasite used for arguments/result passing.

Arguments passing

To pass arguments between the infecting code and parasite, one may call compel_parasite_args(ctl, type) and get the pointer where it can put data. Subsequent calls to compel_rpc_call[_sync]() will result in this data visible in void *arg address of the parasite_daemon_cmd().

See also