elftosb::EncoreBootImageReader Class Reference

Reads a Piano/Encore boot image from an input stream. More...

`#include <EncoreBootImageReader.h>`

Collaboration diagram for elftosb::EncoreBootImageReader:
[legend]

## Classes

class | read_error
| Exception class used for error found while reading a boot image. More...

## Public Types

typedef std::vector< EncoreBootImage::section_header_t > | section_array_t
| An array of section headers.
typedef std::vector< EncoreBootImage::boot_command_t > | boot_tag_array_t
| An array of boot tags.

## Public Member Functions

| EncoreBootImageReader (std::istream &stream)
| Default constructor.
virtual | ~EncoreBootImageReader ()
| Destructor.
Decryption key
These methods provide access to the Data Encryption Key (DEK). Normally the DEK is discovered using the readKeyDictionary() method.
void | setKey (const AESKey< 128 > &key)
const AESKey< 128 > & | getKey () const
Readers
This group of methods is responsible for reading and parsing different pieces and parts of the boot image file.
void | readImageHeader ()
| Reads the header from the image. More...
void | computeHeaderDigest (sha1_digest_t &digest)
| Computes the actual SHA-1 digest of the image header. More...
void | readImageDigest ()
| Reads the digest at the end of the image. More...
void | computeImageDigest (sha1_digest_t &digest)
| Run a SHA-1 digest over the entire image. More...
void | readSectionTable ()
| Read the plaintext section table entries. More...
bool | readKeyDictionary (const AESKey< 128 > &kek)
| Reads the key dictionary, if the image is encrypted. More...
void | readBootTags ()
EncoreBootImage::Section * | readSection (unsigned index)
Accessors
Information retrieved with reader methods is accessible through these methods.
bool | isEncrypted () const
| Returns whether the image is encrypted or not. More...
const EncoreBootImage::boot_image_header_t & | getHeader () const
| Returns a reference to the image's header.
const sha1_digest_t & | getDigest () const
| Returns a reference to the SHA-1 digest read from the image.
const section_array_t & | getSections () const
| Returns a reference to the STL container holding the section headers.
const boot_tag_array_t & | getBootTags () const
| Returns a reference to the STL container holding the boot tags.

## Protected Member Functions

uint8_t | calculateCommandChecksum (EncoreBootImage::boot_command_t &header)
| Calculates the 8-bit checksum on a boot command header.

## Protected Attributes

std::istream & | m_stream
| The input stream to read the image from.
AESKey< 128 > | m_dek
| DEK (data encryption key) read from the key dictionary.
EncoreBootImage::boot_image_header_t | m_header
| Header from the boot image.
sha1_digest_t | m_digest
| SHA-1 digest as read from the image.
section_array_t | m_sections
| The section table.
boot_tag_array_t | m_bootTags
| The array of boot tags read from the image.

## Detailed Description

Reads a Piano/Encore boot image from an input stream.

## Member Function Documentation

void EncoreBootImageReader::computeHeaderDigest | ( | sha1_digest_t & | digest | ) |

Computes the actual SHA-1 digest of the image header.

Precondition
  The image header must have already been read with a call to readImageHeader().

void EncoreBootImageReader::computeImageDigest | ( | sha1_digest_t & | digest | ) |

Run a SHA-1 digest over the entire image.

Precondition
  The image header must have already been read with a call to readImageHeader().

Postcondition
  The stream head is at the end of the image minus the last two cipher blocks.

Parameters

  digest | Where to store the resulting digest.

Exceptions

  read_error | Thrown if the image header is invalid.

bool elftosb::EncoreBootImageReader::isEncrypted | ( |  | ) | const

inline

Returns whether the image is encrypted or not.

Precondition
  The header must have been read already.

void EncoreBootImageReader::readBootTags | ( |  | ) |

Before the boot tag is added to the m_bootTags member, some basic checks are performed. The command tag field is checked to make sure it matches #ROM_TAG_CMD. And the checksum field is verified to be sure it's correct.

After the call to this method returns, the array of boot tags is accessible with the getBootTags() method. The array is sorted in the order in which the boot tags appeared in the image.

Precondition
  Image header must have been read.
  Key dictionary must have been read and a valid DEK found.

Postcondition
  The stream head is left pointing just after the last boot tag.

Exceptions

  read_error | A failure to read the boot tag, or a failure on one of the consistency checks will cause this exception to be thrown.

void EncoreBootImageReader::readImageDigest | ( |  | ) |

Reads the digest at the end of the image.

Precondition
  The image header must have already been read.
  The DEK must have been found already.

Postcondition
  The stream head is at the end of the digest.

void EncoreBootImageReader::readImageHeader | ( |  | ) |

Reads the header from the image.

Postcondition
  Stream head points to just after the image header.

Exceptions

  read_error | Thrown if the image header is invalid.

bool EncoreBootImageReader::readKeyDictionary | ( | const AESKey< 128 > & | kek | ) |

Reads the key dictionary, if the image is encrypted.

Requires that an OTP key has been provided as the sole argument. Passing the key into this method lets the caller search the key dictionary for any number of keys and determine which are valid. If kek is found in the dictionary, the decrypted DEK is saved and true is returned. A result of false means that kek was not found.

Precondition
  The image header and section table must have been read already.

Postcondition
  The stream head points somewhere inside the key dictionary, or just after it.
  If the search was successful, the m_dek member will contain the decrypted session key. Otherwise m_dek is not modified.

Parameters

  kek | Search for this KEK in the dictionary.

Return values

  true | The DEK was found and decrypted. True is also returned when the image is not encrypted at all.
  false | No matching key entry was found. The image cannot be decrypted.

EncoreBootImage::Section * EncoreBootImageReader::readSection | ( | unsigned | index | ) |

Parameters

  index | The index of the section to read.

Precondition
  Both the image header and section table must have been read already before calling this method.

Exceptions

  read_error | This exception is raised if the stream reports an error while trying to read from the section.

void EncoreBootImageReader::readSectionTable | ( |  | ) |

Read the plaintext section table entries.

Precondition
  Image header must have been read before this method is called.

The documentation for this class was generated from the following files:

- EncoreBootImageReader.h
- EncoreBootImageReader.cpp