cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

module-elf-format.rst (13933B)


      1===========================
      2Livepatch module Elf format
      3===========================
      4
      5This document outlines the Elf format requirements that livepatch modules must follow.
      6
      7
      8.. Table of Contents
      9
     10.. contents:: :local:
     11
     12
     131. Background and motivation
     14============================
     15
     16Formerly, livepatch required separate architecture-specific code to write
     17relocations. However, arch-specific code to write relocations already
     18exists in the module loader, so this former approach produced redundant
     19code. So, instead of duplicating code and re-implementing what the module
     20loader can already do, livepatch leverages existing code in the module
     21loader to perform the all the arch-specific relocation work. Specifically,
     22livepatch reuses the apply_relocate_add() function in the module loader to
     23write relocations. The patch module Elf format described in this document
     24enables livepatch to be able to do this. The hope is that this will make
     25livepatch more easily portable to other architectures and reduce the amount
     26of arch-specific code required to port livepatch to a particular
     27architecture.
     28
     29Since apply_relocate_add() requires access to a module's section header
     30table, symbol table, and relocation section indices, Elf information is
     31preserved for livepatch modules (see section 5). Livepatch manages its own
     32relocation sections and symbols, which are described in this document. The
     33Elf constants used to mark livepatch symbols and relocation sections were
     34selected from OS-specific ranges according to the definitions from glibc.
     35
     36Why does livepatch need to write its own relocations?
     37-----------------------------------------------------
     38A typical livepatch module contains patched versions of functions that can
     39reference non-exported global symbols and non-included local symbols.
     40Relocations referencing these types of symbols cannot be left in as-is
     41since the kernel module loader cannot resolve them and will therefore
     42reject the livepatch module. Furthermore, we cannot apply relocations that
     43affect modules not yet loaded at patch module load time (e.g. a patch to a
     44driver that is not loaded). Formerly, livepatch solved this problem by
     45embedding special "dynrela" (dynamic rela) sections in the resulting patch
     46module Elf output. Using these dynrela sections, livepatch could resolve
     47symbols while taking into account its scope and what module the symbol
     48belongs to, and then manually apply the dynamic relocations. However this
     49approach required livepatch to supply arch-specific code in order to write
     50these relocations. In the new format, livepatch manages its own SHT_RELA
     51relocation sections in place of dynrela sections, and the symbols that the
     52relas reference are special livepatch symbols (see section 2 and 3). The
     53arch-specific livepatch relocation code is replaced by a call to
     54apply_relocate_add().
     55
     562. Livepatch modinfo field
     57==========================
     58
     59Livepatch modules are required to have the "livepatch" modinfo attribute.
     60See the sample livepatch module in samples/livepatch/ for how this is done.
     61
     62Livepatch modules can be identified by users by using the 'modinfo' command
     63and looking for the presence of the "livepatch" field. This field is also
     64used by the kernel module loader to identify livepatch modules.
     65
     66Example:
     67--------
     68
     69**Modinfo output:**
     70
     71::
     72
     73	% modinfo livepatch-meminfo.ko
     74	filename:		livepatch-meminfo.ko
     75	livepatch:		Y
     76	license:		GPL
     77	depends:
     78	vermagic:		4.3.0+ SMP mod_unload
     79
     803. Livepatch relocation sections
     81================================
     82
     83A livepatch module manages its own Elf relocation sections to apply
     84relocations to modules as well as to the kernel (vmlinux) at the
     85appropriate time. For example, if a patch module patches a driver that is
     86not currently loaded, livepatch will apply the corresponding livepatch
     87relocation section(s) to the driver once it loads.
     88
     89Each "object" (e.g. vmlinux, or a module) within a patch module may have
     90multiple livepatch relocation sections associated with it (e.g. patches to
     91multiple functions within the same object). There is a 1-1 correspondence
     92between a livepatch relocation section and the target section (usually the
     93text section of a function) to which the relocation(s) apply. It is
     94also possible for a livepatch module to have no livepatch relocation
     95sections, as in the case of the sample livepatch module (see
     96samples/livepatch).
     97
     98Since Elf information is preserved for livepatch modules (see Section 5), a
     99livepatch relocation section can be applied simply by passing in the
    100appropriate section index to apply_relocate_add(), which then uses it to
    101access the relocation section and apply the relocations.
    102
    103Every symbol referenced by a rela in a livepatch relocation section is a
    104livepatch symbol. These must be resolved before livepatch can call
    105apply_relocate_add(). See Section 3 for more information.
    106
    1073.1 Livepatch relocation section format
    108=======================================
    109
    110Livepatch relocation sections must be marked with the SHF_RELA_LIVEPATCH
    111section flag. See include/uapi/linux/elf.h for the definition. The module
    112loader recognizes this flag and will avoid applying those relocation sections
    113at patch module load time. These sections must also be marked with SHF_ALLOC,
    114so that the module loader doesn't discard them on module load (i.e. they will
    115be copied into memory along with the other SHF_ALLOC sections).
    116
    117The name of a livepatch relocation section must conform to the following
    118format::
    119
    120  .klp.rela.objname.section_name
    121  ^        ^^     ^ ^          ^
    122  |________||_____| |__________|
    123     [A]      [B]        [C]
    124
    125[A]
    126  The relocation section name is prefixed with the string ".klp.rela."
    127
    128[B]
    129  The name of the object (i.e. "vmlinux" or name of module) to
    130  which the relocation section belongs follows immediately after the prefix.
    131
    132[C]
    133  The actual name of the section to which this relocation section applies.
    134
    135Examples:
    136---------
    137
    138**Livepatch relocation section names:**
    139
    140::
    141
    142  .klp.rela.ext4.text.ext4_attr_store
    143  .klp.rela.vmlinux.text.cmdline_proc_show
    144
    145**`readelf --sections` output for a patch
    146module that patches vmlinux and modules 9p, btrfs, ext4:**
    147
    148::
    149
    150  Section Headers:
    151  [Nr] Name                          Type                    Address          Off    Size   ES Flg Lk Inf Al
    152  [ snip ]
    153  [29] .klp.rela.9p.text.caches.show RELA                    0000000000000000 002d58 0000c0 18 AIo 64   9  8
    154  [30] .klp.rela.btrfs.text.btrfs.feature.attr.show RELA     0000000000000000 002e18 000060 18 AIo 64  11  8
    155  [ snip ]
    156  [34] .klp.rela.ext4.text.ext4.attr.store RELA              0000000000000000 002fd8 0000d8 18 AIo 64  13  8
    157  [35] .klp.rela.ext4.text.ext4.attr.show RELA               0000000000000000 0030b0 000150 18 AIo 64  15  8
    158  [36] .klp.rela.vmlinux.text.cmdline.proc.show RELA         0000000000000000 003200 000018 18 AIo 64  17  8
    159  [37] .klp.rela.vmlinux.text.meminfo.proc.show RELA         0000000000000000 003218 0000f0 18 AIo 64  19  8
    160  [ snip ]                                       ^                                             ^
    161                                                 |                                             |
    162                                                [*]                                           [*]
    163
    164[*]
    165  Livepatch relocation sections are SHT_RELA sections but with a few special
    166  characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will
    167  not be discarded when the module is loaded into memory, as well as with the
    168  SHF_RELA_LIVEPATCH flag ("o" - for OS-specific).
    169
    170**`readelf --relocs` output for a patch module:**
    171
    172::
    173
    174  Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
    175      Offset             Info             Type               Symbol's Value  Symbol's Name + Addend
    176  000000000000001f  0000005e00000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.printk,0 - 4
    177  0000000000000028  0000003d0000000b R_X86_64_32S           0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0
    178  0000000000000036  0000003b00000002 R_X86_64_PC32          0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4
    179  000000000000004c  0000004900000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4
    180  [ snip ]                                                                   ^
    181                                                                             |
    182                                                                            [*]
    183
    184[*]
    185  Every symbol referenced by a relocation is a livepatch symbol.
    186
    1874. Livepatch symbols
    188====================
    189
    190Livepatch symbols are symbols referred to by livepatch relocation sections.
    191These are symbols accessed from new versions of functions for patched
    192objects, whose addresses cannot be resolved by the module loader (because
    193they are local or unexported global syms). Since the module loader only
    194resolves exported syms, and not every symbol referenced by the new patched
    195functions is exported, livepatch symbols were introduced. They are used
    196also in cases where we cannot immediately know the address of a symbol when
    197a patch module loads. For example, this is the case when livepatch patches
    198a module that is not loaded yet. In this case, the relevant livepatch
    199symbols are resolved simply when the target module loads. In any case, for
    200any livepatch relocation section, all livepatch symbols referenced by that
    201section must be resolved before livepatch can call apply_relocate_add() for
    202that reloc section.
    203
    204Livepatch symbols must be marked with SHN_LIVEPATCH so that the module
    205loader can identify and ignore them. Livepatch modules keep these symbols
    206in their symbol tables, and the symbol table is made accessible through
    207module->symtab.
    208
    2094.1 A livepatch module's symbol table
    210=====================================
    211Normally, a stripped down copy of a module's symbol table (containing only
    212"core" symbols) is made available through module->symtab (See layout_symtab()
    213in kernel/module.c). For livepatch modules, the symbol table copied into memory
    214on module load must be exactly the same as the symbol table produced when the
    215patch module was compiled. This is because the relocations in each livepatch
    216relocation section refer to their respective symbols with their symbol indices,
    217and the original symbol indices (and thus the symtab ordering) must be
    218preserved in order for apply_relocate_add() to find the right symbol.
    219
    220For example, take this particular rela from a livepatch module:::
    221
    222  Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
    223      Offset             Info             Type               Symbol's Value  Symbol's Name + Addend
    224  000000000000001f  0000005e00000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.printk,0 - 4
    225
    226  This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded
    227  in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the
    228  symbol index 94.
    229  And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol:
    230  [ snip ]
    231  94: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0
    232  [ snip ]
    233
    2344.2 Livepatch symbol format
    235===========================
    236
    237Livepatch symbols must have their section index marked as SHN_LIVEPATCH, so
    238that the module loader can identify them and not attempt to resolve them.
    239See include/uapi/linux/elf.h for the actual definitions.
    240
    241Livepatch symbol names must conform to the following format::
    242
    243  .klp.sym.objname.symbol_name,sympos
    244  ^       ^^     ^ ^         ^ ^
    245  |_______||_____| |_________| |
    246     [A]     [B]       [C]    [D]
    247
    248[A]
    249  The symbol name is prefixed with the string ".klp.sym."
    250
    251[B]
    252  The name of the object (i.e. "vmlinux" or name of module) to
    253  which the symbol belongs follows immediately after the prefix.
    254
    255[C]
    256  The actual name of the symbol.
    257
    258[D]
    259  The position of the symbol in the object (as according to kallsyms)
    260  This is used to differentiate duplicate symbols within the same
    261  object. The symbol position is expressed numerically (0, 1, 2...).
    262  The symbol position of a unique symbol is 0.
    263
    264Examples:
    265---------
    266
    267**Livepatch symbol names:**
    268
    269::
    270
    271	.klp.sym.vmlinux.snprintf,0
    272	.klp.sym.vmlinux.printk,0
    273	.klp.sym.btrfs.btrfs_ktype,0
    274
    275**`readelf --symbols` output for a patch module:**
    276
    277::
    278
    279  Symbol table '.symtab' contains 127 entries:
    280     Num:    Value          Size Type    Bind   Vis     Ndx         Name
    281     [ snip ]
    282      73: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0
    283      74: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0
    284      75: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0
    285      76: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0
    286    [ snip ]                                               ^
    287                                                           |
    288                                                          [*]
    289
    290[*]
    291  Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
    292  "OS" means OS-specific.
    293
    2945. Symbol table and Elf section access
    295======================================
    296A livepatch module's symbol table is accessible through module->symtab.
    297
    298Since apply_relocate_add() requires access to a module's section headers,
    299symbol table, and relocation section indices, Elf information is preserved for
    300livepatch modules and is made accessible by the module loader through
    301module->klp_info, which is a klp_modinfo struct. When a livepatch module loads,
    302this struct is filled in by the module loader. Its fields are documented below::
    303
    304	struct klp_modinfo {
    305		Elf_Ehdr hdr; /* Elf header */
    306		Elf_Shdr *sechdrs; /* Section header table */
    307		char *secstrings; /* String table for the section headers */
    308		unsigned int symndx; /* The symbol table section index */
    309	};