elftosb::EncoreBootImageReader Class Reference

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

#include <EncoreBootImageReader.h>

Collaboration diagram for elftosb::EncoreBootImageReader:

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