eh_frame.h

Go to the documentation of this file.

//
// Bareflank Unwind Library
//
// Copyright (C) 2015 Assured Information Security, Inc.
// Author: Rian Quinn        <quinnr@ainfosec.com>
// Author: Brendan Kerrigan  <kerriganb@ainfosec.com>
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

#ifndef EH_FRAME_H
#define EH_FRAME_H

#include <stdint.h>
#include <constants.h>
#include <eh_frame_list.h>
#include <registers_intel_x64.h>

class common_entry;
class ci_entry;
class fd_entry;

// -----------------------------------------------------------------------------
// Overview
// -----------------------------------------------------------------------------
//
// Exception Handling Framework (eh_frame) is based on the DWARF specification.
// This implementation uses the DWARF 4 specification, but the actual format
// is defined here (as there are some differences):
//
// https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic.pdf
//
// In addition to the above specification, Ian Lance Taylor has a great
// explanation of this section on his blog:
//
// http://www.airs.com/blog/archives/460
// http://www.airs.com/blog/archives/462
// http://www.airs.com/blog/archives/464
//
// and there is another good explanation of this information here:
//
// http://www.deadp0rk.com/2013/09/22/base_abi/
//
// Notes:
//
// - This implementation is not optimized for performance. Exception handling
//   in bareflank should not be used for flow control, but rather for error
//   handling (which should not happen often)
//
// - The specification is written for 32bit and 64bit. This implementation
//   only supports 64bit.
//
// - readelf can be used to parse the .eh_frame section, and provide all of
//   the information that this code should be capable of parsing. Use the
//   --debug-dump=frames flag with a binary or shared module.
//
// - If you see a function that takes a char **addr, it will use the addr and
//   then advance the addr based on the operation performed. This is because
//   the way this spec is written, decoding everything is done in a linear
//   fashion, and each operation is compressed, so you don't know how much to
//   advance the pointer until you decode the operation.
//
// In addition to this implementation, there are two other implementations that
// could provide useful information:
//
// http://www.nongnu.org/libunwind/
// https://github.com/llvm-mirror/libunwind
//

// -----------------------------------------------------------------------------
// DWARF Extensions (section 10.5)
// -----------------------------------------------------------------------------
//
// The Exception Handler Framework in our version of the LSB uses the DWARF 4
// spec, but does so by applying the following extensions
//

// -----------------------------------------------------------------------------
// DWARF Exception Header Encoding (section 10.5.1)
// -----------------------------------------------------------------------------
//
// An EH encoding is a byte, with the lower 4 bits describing the format of the
// pointer, and the upper 4 bits describing how the pointer should be applied.
//

// Data Format
#define DW_EH_PE_absptr     0x00
#define DW_EH_PE_uleb128    0x01
#define DW_EH_PE_udata2     0x02
#define DW_EH_PE_udata4     0x03
#define DW_EH_PE_udata8     0x04
#define DW_EH_PE_sleb128    0x09
#define DW_EH_PE_sdata2     0x0A
#define DW_EH_PE_sdata4     0x0B
#define DW_EH_PE_sdata8     0x0C

// Data Application
#define DW_EH_PE_pcrel      0x10
#define DW_EH_PE_textrel    0x20
#define DW_EH_PE_datarel    0x30
#define DW_EH_PE_funcrel    0x40
#define DW_EH_PE_aligned    0x50

// Special
#define DW_EH_PE_omit       0xFF

uint64_t decode_pointer(char **addr, uint64_t encoding);

// -----------------------------------------------------------------------------
// DWARF Call Frame Instruction (CFI) Extensions (section 10.5.2)
// -----------------------------------------------------------------------------
//
// These extend the call frame instructions that are defined in the DWARF 4
// specification.
//

#define DW_CFA_GNU_args_size                    0x2E
#define DW_CFA_GNU_negative_offset_extended     0x2F

// -----------------------------------------------------------------------------
// .eh_frame Section (section 10.6.1)
// -----------------------------------------------------------------------------
//
// The .eh_frame section is located in each compiled unit (binary or shared
// module). It contains one or more Call Frame Information structures (not
// to be confusd with the Call Frame Instructions which are defined in the
// DWARF portion of this code). The CFI structures have the following format:
//
//          CFI
// ---------------------
// - CIE               -
// - FDE               -
// - FDE               -
// ---------------------
// - CIE               -
// - FDE               -
// - ...               -
// ---------------------
//
// The size of the .eh_frame section dictates the number of CIEs in the CFI,
// which means that both the starting address of the .eh_frame section, and
// it's size must be available. The best way to view the difference between
// the CIE and the FDE is, the FDE contains the information needed to unwind
// the stack for a given program counter (PC), and the CIE contains the
// information for an FDE that just do happens to be shared with other FDEs.
// For this reason, when looking for the FDE associated with your PC, you
// basically scan looking for FDEs, and just ignore an entry if it happens to
// be a CIE instead of an FDE. Once you find the FDE you care about, you can
// use the CIE offset stored in the FDE to find the CIE associated with that
// FDE. It probably would have made sense for GCC to place the all of the CIEs
// at the end of the list to make scanning easier, but that's not the case.
//
// Both the CIE and the FDE's have some fields that are encoded using both
// signed and unsigned LEB128 format. What this means is the value could be
// 8bits, or even 64bits, it all depends on how many bits are needed to encode
// the value, which provides a means to compress the information in each CIE
// and FDE. For example, a length field my contain the value 0x40, which only
// takes up a byte. The length could also be 0x4000000. The problem is, in a
// lot of cases, len might end up being small most of the time, but because
// it could be larger, 64bits would need to be allocated every time. To
// prevent this, LEB128 breaks up the number in a way that allows it to be
// encoded in a compressed form, thus taking up less space. In our code, when
// you see a LEB128, we store the decoded values as 64bits. There is a really
// good explanation of this here:
//
// https://en.wikipedia.org/wiki/LEB128

class eh_frame
{
public:
    static fd_entry find_fde(register_state *state);
};

class common_entry
{
public:

    common_entry();

    explicit common_entry(const eh_frame_t &eh_frame);

    virtual ~common_entry() = default;

    common_entry(common_entry &&) noexcept = default;

    common_entry(const common_entry &) = default;

    common_entry &operator=(common_entry &&) noexcept = default;

    common_entry &operator=(const common_entry &) = default;

    common_entry &operator++();

    operator bool() const
    { return m_entry_start != nullptr; }

    bool is_cie() const
    { return m_is_cie; }

    bool is_fde() const
    { return !m_is_cie; }

    char *entry_start() const
    { return m_entry_start; }

    char *entry_end() const
    { return m_entry_end; }

    char *payload_start() const
    { return m_payload_start; }

    char *payload_end() const
    { return m_payload_end; }

    eh_frame_t eh_frame() const
    { return m_eh_frame; }

protected:
    virtual void parse(char *addr) = 0;
    void non_virtual_parse(char *addr);

protected:
    bool m_is_cie;

    char *m_entry_start;
    char *m_entry_end;

    char *m_payload_start;
    char *m_payload_end;

    eh_frame_t m_eh_frame;
};

// -----------------------------------------------------------------------------
// Common Information Entry (CIE) Format (section 10.6.1.1)
// -----------------------------------------------------------------------------
//

class ci_entry : public common_entry
{
public:

    ci_entry();

    explicit ci_entry(const eh_frame_t &eh_frame);

    explicit ci_entry(const eh_frame_t &eh_frame, void *addr);

    ~ci_entry() override = default;

    ci_entry(ci_entry &&) noexcept = default;

    ci_entry(const ci_entry &) = default;

    ci_entry &operator=(ci_entry &&) noexcept = default;

    ci_entry &operator=(const ci_entry &) = default;

    char augmentation_string(uint64_t index) const
    { return m_augmentation_string[index]; }

    uint64_t code_alignment() const
    { return m_code_alignment; }

    int64_t data_alignment() const
    { return m_data_alignment; }

    uint64_t return_address_reg() const
    { return m_return_address_reg; }

    uint64_t pointer_encoding() const
    { return m_pointer_encoding; }

    uint64_t lsda_encoding() const
    { return m_lsda_encoding; }

    uint64_t personality_encoding() const
    { return m_personality_encoding; }

    uint64_t personality_function() const
    { return m_personality_function; }

    char *initial_instructions() const
    { return m_initial_instructions; }

protected:
    void parse(char *addr) override;
    void non_virtual_parse(char *addr);

public:
    const char *m_augmentation_string;
    uint64_t m_code_alignment;
    int64_t m_data_alignment;
    uint64_t m_return_address_reg;
    uint64_t m_pointer_encoding;
    uint64_t m_lsda_encoding;
    uint64_t m_personality_encoding;
    uint64_t m_personality_function;
    char *m_initial_instructions;
};

// -----------------------------------------------------------------------------
// Frame Description Entry (FDE) (section 10.6.1.2)
// -----------------------------------------------------------------------------

class fd_entry : public common_entry
{
public:

    fd_entry();

    explicit fd_entry(const eh_frame_t &eh_frame);

    explicit fd_entry(const eh_frame_t &eh_frame, void *addr);

    ~fd_entry() override = default;

    fd_entry(fd_entry &&) noexcept = default;

    fd_entry(const fd_entry &) = default;

    fd_entry &operator=(fd_entry &&) noexcept = default;

    fd_entry &operator=(const fd_entry &) = default;

    bool is_in_range(uint64_t pc) const
    { return (pc > m_pc_begin) && (pc <= m_pc_begin + m_pc_range); }

    uint64_t pc_begin() const
    { return m_pc_begin; }

    uint64_t pc_range() const
    { return m_pc_range; }

    uint64_t lsda() const
    { return m_lsda; }

    char *instructions() const
    { return m_instructions; }

    const ci_entry &cie() const
    { return m_cie; }

protected:
    void parse(char *addr) override;
    void non_virtual_parse(char *addr);

private:
    uint64_t m_pc_begin;
    uint64_t m_pc_range;
    uint64_t m_lsda;
    char *m_instructions;

    ci_entry m_cie;
};

#endif