Encryption wrapper for BasicStream. More...

#include <EncryptedStream.h>

Inheritance diagram for OtaUpgrade::EncryptedStream:
[legend]
Collaboration diagram for OtaUpgrade::EncryptedStream:
[legend]

Public Types

enum  Error {
  None, InvalidFormat, UnsupportedData, DecryptionFailed,
  NoRomFound, RomTooLarge, DowngradeNotAllowed, VerificationFailed,
  FlashWriteFailed, RomActivationFailed, OutOfMemory, Internal
}
 Error code values. More...
 

Public Member Functions

 EncryptedStream ()=default
 
 ~EncryptedStream ()
 
size_t write (const uint8_t *data, size_t size) override
 Process an arbitrarily sized chunk of an encrypted OTA upgrade file. More...
 
size_t write (uint8_t charToWrite) override
 Write a single character to the stream. More...
 
size_t write (const char *str)
 Writes a c-string to output stream. More...
 
size_t write (const char *buffer, size_t size)
 Writes characters from a buffer to output stream. More...
 
bool hasError () const
 Returns true if an error happened during the upgrade process. More...
 
uint16_t readMemoryBlock (char *data, int bufSize) override
 Read a block of memory. More...
 
virtual int available () override
 Return the total length of the stream. More...
 
bool isFinished () override
 Check if all data has been read. More...
 
virtual size_t copyFrom (IDataSourceStream *source, size_t size)
 Copy data from a source stream. More...
 
virtual StreamType getStreamType () const
 Get the stream type. More...
 
virtual bool isValid () const
 Determine if the stream object contains valid data. More...
 
int read () override
 Read one character and moves the stream pointer. More...
 
int peek () override
 Read a character without advancing the stream pointer. More...
 
virtual int seekFrom (int offset, unsigned origin)
 Change position in stream. More...
 
virtual bool seek (int len)
 Move read cursor. More...
 
int length ()
 Return the total length of the stream. More...
 
void flush () override
 
virtual String id () const
 Returns unique id of the resource. More...
 
virtual String getName () const
 Returns name of the resource. More...
 
String readString (size_t maxLen=UINT16_MAX)
 Overrides Stream method for more efficient reading. More...
 
String readString ()
 
void setTimeout (unsigned long timeout)
 
bool find (char *target)
 
bool find (char *target, size_t length)
 
bool findUntil (char *target, char *terminator)
 
bool findUntil (char *target, size_t targetLen, char *terminate, size_t termLen)
 
long parseInt ()
 
float parseFloat ()
 
size_t readBytes (char *buffer, size_t length)
 
size_t readBytesUntil (char terminator, char *buffer, size_t length)
 
String readStringUntil (char terminator)
 
virtual int indexOf (char c)
 
int getWriteError ()
 Gets last error. More...
 
void clearWriteError ()
 Clears the last write error. More...
 
size_t print (char c)
 Prints a single character to output stream. More...
 
size_t print (const char str[])
 Prints a c-string to output stream. More...
 
size_t print (double num, int digits=2)
 Print a floating-point number to output stream. More...
 
size_t print (const Printable &p)
 Prints a Printable object to output stream. More...
 
size_t print (const String &s)
 Prints a String to output stream. More...
 
size_t println ()
 Prints a newline to output stream. More...
 
size_t println (const char str[])
 Prints a c-string to output stream, appending newline. More...
 
size_t println (char c)
 Prints a single character to output stream, appending newline. More...
 
size_t println (double num, int digits=2)
 Print a floating-point number to output stream, appending newline. More...
 
size_t println (const Printable &p)
 Prints a Printable object to output stream, appending newline. More...
 
size_t println (const String &s)
 Prints a String to output stream, appending newline. More...
 
size_t printf (const char *fmt,...) __attribute__((format(printf
 Prints a formatted c-string to output stream. More...
 
Print an integral number to output stream
Parameters
numNumber to print
baseThe base for output (Default: Decimal (base 10))
Return values
size_tQuantity of characters written to stream
size_t print (unsigned long num, int base=DEC)
 
size_t print (const unsigned long long &num, int base=DEC)
 
size_t print (long, int base=DEC)
 
size_t print (const long long &, int base=DEC)
 
size_t print (unsigned int num, int base=DEC)
 
size_t print (unsigned char num, int base=DEC)
 
size_t print (int num, int base=DEC)
 
Print an integral number to output stream, appending newline
Parameters
numNumber to print
baseThe base for output (Default: Decimal (base 10))
Return values
size_tQuantity of characters written to stream
size_t println (unsigned char num, int base=DEC)
 
size_t println (unsigned int num, int base=DEC)
 
size_t println (unsigned long num, int base=DEC)
 
size_t println (const unsigned long long &num, int base=DEC)
 
size_t println (int num, int base=DEC)
 
size_t println (long num, int base=DEC)
 
size_t println (const long long &num, int base=DEC)
 

Static Public Member Functions

static String errorToString (Error code)
 Convert error code to string. More...
 

Public Attributes

Error errorCode = Error::None
 Error code. Only relevant if hasError() returns true. More...
 
uint8_t header [crypto_secretstream_xchacha20poly1305_HEADERBYTES]
 
uint16_t chunkSizeMinusOne
 

Protected Member Functions

void setError (Error ec)
 
int timedRead ()
 
int timedPeek ()
 
int peekNextDigit ()
 
long parseInt (char skipChar)
 
float parseFloat (char skipChar)
 
void setWriteError (int err=1)
 

Protected Attributes

unsigned long receiveTimeout = 1000
 
unsigned long startMillis = 0
 

Detailed Description

Encryption wrapper for BasicStream.

The class processes encrypted firmware upgrade files created by otatool.py. A buffer is allocated dynamically to fit the largest chunk of the encryption container (2kB unless otatool.py was modified). The actual processing of the decrypted data is defered to BasicStream.

Member Enumeration Documentation

◆ Error

Error code values.

Enumerator
None 

No error occured thus far (default value of errorCode if hasError() returns false)

InvalidFormat 

Invalid/unsupported upgrade file format.

UnsupportedData 

Some content of the upgrade file is not supported by this version of OtaUpgradeStream.

DecryptionFailed 

Decryption failed. Probably wrong decryption key.

NoRomFound 

The file did not contain a ROM image suitable for the start address of the slot to upgrade.

RomTooLarge 

The contained ROM image does not fit into the application firmware slot.

DowngradeNotAllowed 

Attempt to downgrade to older firmware version.

VerificationFailed 

Signature/checksum verification failed - updated ROM not activated.

FlashWriteFailed 

Error while writing to Flash memory.

RomActivationFailed 

Error while activating updated ROM slot.

OutOfMemory 

Dynamic memory allocation failed.

Internal 

An unexpected error occured.

Constructor & Destructor Documentation

◆ EncryptedStream()

OtaUpgrade::EncryptedStream::EncryptedStream ( )
default

◆ ~EncryptedStream()

OtaUpgrade::EncryptedStream::~EncryptedStream ( )
inline

Member Function Documentation

◆ available()

virtual int OtaUpgrade::BasicStream::available ( )
inlineoverridevirtualinherited

Return the total length of the stream.

Return values
int-1 is returned when the size cannot be determined

Reimplemented from IDataSourceStream.

◆ clearWriteError()

void Print::clearWriteError ( )
inlineinherited

Clears the last write error.

◆ copyFrom()

virtual size_t ReadWriteStream::copyFrom ( IDataSourceStream source,
size_t  size 
)
virtualinherited

Copy data from a source stream.

Parameters
sourceStream to read data from
sizeQuantity of chars to write, determines size of intermediate buffer to use
Return values
size_tQuantity of chars actually written, may be less than requested

◆ errorToString()

static String OtaUpgrade::BasicStream::errorToString ( Error  code)
staticinherited

Convert error code to string.

See also
errorCode

◆ find() [1/2]

bool Stream::find ( char *  target)
inherited

◆ find() [2/2]

bool Stream::find ( char *  target,
size_t  length 
)
inherited

◆ findUntil() [1/2]

bool Stream::findUntil ( char *  target,
char *  terminator 
)
inherited

◆ findUntil() [2/2]

bool Stream::findUntil ( char *  target,
size_t  targetLen,
char *  terminate,
size_t  termLen 
)
inherited

◆ flush()

void IDataSourceStream::flush ( )
inlineoverridevirtualinherited

Implements Stream.

Reimplemented in HardwareSerial.

◆ getName()

virtual String IDataSourceStream::getName ( ) const
inlinevirtualinherited

Returns name of the resource.

Return values
String
Note
Commonly used to obtain name of file

Reimplemented in TemplateStream, FileStream, StreamTransformer, GdbFileStream, and HostFileStream.

◆ getStreamType()

virtual StreamType IDataSourceStream::getStreamType ( ) const
inlinevirtualinherited

◆ getWriteError()

int Print::getWriteError ( )
inlineinherited

Gets last error.

Return values
intError number of last write error

◆ hasError()

bool OtaUpgrade::BasicStream::hasError ( ) const
inlineinherited

Returns true if an error happened during the upgrade process.

See also
errorCode

◆ id()

virtual String IDataSourceStream::id ( ) const
inlinevirtualinherited

Returns unique id of the resource.

Return values
Stringthe unique id of the stream.

Reimplemented in FileStream, GdbFileStream, and CircularBuffer.

◆ indexOf()

virtual int Stream::indexOf ( char  c)
inlinevirtualinherited

Reimplemented in HardwareSerial.

◆ isFinished()

bool OtaUpgrade::BasicStream::isFinished ( )
inlineoverridevirtualinherited

Check if all data has been read.

Return values
boolTrue on success.

Implements IDataSourceStream.

◆ isValid()

virtual bool IDataSourceStream::isValid ( ) const
inlinevirtualinherited

Determine if the stream object contains valid data.

Return values
booltrue if valid, false if invalid
Note
Where inherited classes are initialised by constructor this method indicates whether that was successful or not (e.g. FileStream)

Reimplemented in FileStream, GdbFileStream, and HostFileStream.

◆ length()

int IDataSourceStream::length ( )
inlineinherited

Return the total length of the stream.

Return values
int-1 is returned when the size cannot be determined
Deprecated:
Use available() instead

◆ parseFloat() [1/2]

float Stream::parseFloat ( )
inherited

◆ parseFloat() [2/2]

float Stream::parseFloat ( char  skipChar)
protectedinherited

◆ parseInt() [1/2]

long Stream::parseInt ( )
inherited

◆ parseInt() [2/2]

long Stream::parseInt ( char  skipChar)
protectedinherited

◆ peek()

int IDataSourceStream::peek ( )
overridevirtualinherited

Read a character without advancing the stream pointer.

Return values
intThe character that was read or -1 if none is available

Implements Stream.

Reimplemented in HardwareSerial.

◆ peekNextDigit()

int Stream::peekNextDigit ( )
protectedinherited

◆ print() [1/12]

size_t Print::print ( char  c)
inlineinherited

Prints a single character to output stream.

Parameters
cCharacter to print
Return values
size_tQuantity of characters written to stream

◆ print() [2/12]

size_t Print::print ( const char  str[])
inlineinherited

Prints a c-string to output stream.

Parameters
strc-string to print
Return values
size_tQuantity of characters written to output stream

◆ print() [3/12]

size_t Print::print ( unsigned long  num,
int  base = DEC 
)
inlineinherited

◆ print() [4/12]

size_t Print::print ( const unsigned long long &  num,
int  base = DEC 
)
inlineinherited

◆ print() [5/12]

size_t Print::print ( long  ,
int  base = DEC 
)
inherited

◆ print() [6/12]

size_t Print::print ( const long long &  ,
int  base = DEC 
)
inherited

◆ print() [7/12]

size_t Print::print ( unsigned int  num,
int  base = DEC 
)
inlineinherited

◆ print() [8/12]

size_t Print::print ( unsigned char  num,
int  base = DEC 
)
inlineinherited

◆ print() [9/12]

size_t Print::print ( int  num,
int  base = DEC 
)
inlineinherited

◆ print() [10/12]

size_t Print::print ( double  num,
int  digits = 2 
)
inlineinherited

Print a floating-point number to output stream.

Parameters
numNumber to print
digitsThe decimal places to print (Default: 2, e.g. 21.35)
Return values
size_tQuantity of characters written to stream

◆ print() [11/12]

size_t Print::print ( const Printable p)
inlineinherited

Prints a Printable object to output stream.

Parameters
pObject to print
Return values
size_tQuantity of characters written to stream

◆ print() [12/12]

size_t Print::print ( const String s)
inlineinherited

Prints a String to output stream.

Parameters
sString to print
Return values
size_tQuantity of characters written to stream

◆ printf()

size_t Print::printf ( const char *  fmt,
  ... 
)
inherited

Prints a formatted c-string to output stream.

Parameters
fmtPointer to formated c-string to print
...Parameters for placeholders within formated string
Return values
size_tQuantity of characters written to stream
Note
Use standard printf placeholders, e.g. d for integer, s for c-string, etc.

◆ println() [1/13]

size_t Print::println ( )
inlineinherited

Prints a newline to output stream.

Return values
size_tQuantity of characters written to stream

◆ println() [2/13]

size_t Print::println ( const char  str[])
inlineinherited

Prints a c-string to output stream, appending newline.

Parameters
strc-string to print
Return values
size_tQuantity of characters written to stream

◆ println() [3/13]

size_t Print::println ( char  c)
inlineinherited

Prints a single character to output stream, appending newline.

Parameters
cCharacter to print
Return values
size_tQuantity of characters written to stream

◆ println() [4/13]

size_t Print::println ( unsigned char  num,
int  base = DEC 
)
inlineinherited

◆ println() [5/13]

size_t Print::println ( unsigned int  num,
int  base = DEC 
)
inlineinherited

◆ println() [6/13]

size_t Print::println ( unsigned long  num,
int  base = DEC 
)
inlineinherited

◆ println() [7/13]

size_t Print::println ( const unsigned long long &  num,
int  base = DEC 
)
inlineinherited

◆ println() [8/13]

size_t Print::println ( int  num,
int  base = DEC 
)
inlineinherited

◆ println() [9/13]

size_t Print::println ( long  num,
int  base = DEC 
)
inlineinherited

◆ println() [10/13]

size_t Print::println ( const long long &  num,
int  base = DEC 
)
inlineinherited

◆ println() [11/13]

size_t Print::println ( double  num,
int  digits = 2 
)
inlineinherited

Print a floating-point number to output stream, appending newline.

Parameters
numNumber to print
digitsThe decimal places to print (Default: 2, e.g. 21.35)
Return values
size_tQuantity of characters written to stream

◆ println() [12/13]

size_t Print::println ( const Printable p)
inlineinherited

Prints a Printable object to output stream, appending newline.

Parameters
pObject to print
Return values
size_tQuantity of characters written to stream

◆ println() [13/13]

size_t Print::println ( const String s)
inlineinherited

Prints a String to output stream, appending newline.

Parameters
sString to print
Return values
size_tQuantity of characters written to stream

◆ read()

int IDataSourceStream::read ( )
overridevirtualinherited

Read one character and moves the stream pointer.

Return values
Thecharacter that was read or -1 if none is available

Implements Stream.

Reimplemented in HardwareSerial.

◆ readBytes()

size_t Stream::readBytes ( char *  buffer,
size_t  length 
)
inherited

◆ readBytesUntil()

size_t Stream::readBytesUntil ( char  terminator,
char *  buffer,
size_t  length 
)
inherited

◆ readMemoryBlock()

uint16_t OtaUpgrade::BasicStream::readMemoryBlock ( char *  data,
int  bufSize 
)
inlineoverridevirtualinherited

Read a block of memory.

Parameters
dataPointer to the data to be read
bufSizeQuantity of chars to read
Return values
uint16_tQuantity of chars read
Todo:
Should IDataSourceStream::readMemoryBlock return same data type as its bufSize param?

Implements IDataSourceStream.

◆ readString() [1/2]

String Stream::readString ( )
inherited

◆ readString() [2/2]

String IDataSourceStream::readString ( size_t  maxLen = UINT16_MAX)
inherited

Overrides Stream method for more efficient reading.

Note
Content is read using readMemoryBlock() so read position (for seekable streams) is not changed

◆ readStringUntil()

String Stream::readStringUntil ( char  terminator)
inherited

◆ seek()

virtual bool IDataSourceStream::seek ( int  len)
inlinevirtualinherited

Move read cursor.

Parameters
lenRelative cursor adjustment
Return values
boolTrue on success.

Reimplemented in HardwareSerial, StreamTransformer, TemplateStream, CircularBuffer, UrlencodedOutputStream, LimitedMemoryStream, EndlessMemoryStream, and MultiStream.

◆ seekFrom()

virtual int IDataSourceStream::seekFrom ( int  offset,
unsigned  origin 
)
inlinevirtualinherited

Change position in stream.

Parameters
offset
originSEEK_SET, SEEK_CUR, SEEK_END
Return values
Newposition, < 0 on error
Note
This method is implemented by streams which support random seeking, such as files and memory streams.

Reimplemented in FileStream, MemoryDataStream, HostFileStream, FSTR::Stream, and GdbFileStream.

◆ setError()

void OtaUpgrade::BasicStream::setError ( Error  ec)
protectedinherited

◆ setTimeout()

void Stream::setTimeout ( unsigned long  timeout)
inherited

◆ setWriteError()

void Print::setWriteError ( int  err = 1)
inlineprotectedinherited

◆ timedPeek()

int Stream::timedPeek ( )
protectedinherited

◆ timedRead()

int Stream::timedRead ( )
protectedinherited

◆ write() [1/4]

size_t ReadWriteStream::write ( uint8_t  charToWrite)
inlineoverridevirtualinherited

Write a single character to the stream.

Parameters
charToWrite
Return values
size_tNumber of chars written (1 on success, 0 on failure)

Reimplemented from IDataSourceStream.

◆ write() [2/4]

size_t OtaUpgrade::EncryptedStream::write ( const uint8_t *  data,
size_t  size 
)
overridevirtual

Process an arbitrarily sized chunk of an encrypted OTA upgrade file.

Parameters
dataPointer to chunk of data.
sizeSize of chunk pointed to by data in bytes.
Returns
If less than size, an error occured. Check errorCode for more details.
Note
size does not have to match the chunk size used by otatool.py

Reimplemented from OtaUpgrade::BasicStream.

◆ write() [3/4]

size_t Print::write ( const char *  str)
inlineinherited

Writes a c-string to output stream.

Parameters
strPointer to c-string
Return values
size_tQuantity of characters written to stream

◆ write() [4/4]

size_t Print::write ( const char *  buffer,
size_t  size 
)
inlineinherited

Writes characters from a buffer to output stream.

Parameters
bufferPointer to character buffer
sizeQuantity of characters to write
Return values
size_tQuantity of characters written to stream

Member Data Documentation

◆ chunkSizeMinusOne

uint16_t OtaUpgrade::EncryptedStream::chunkSizeMinusOne

◆ errorCode

Error OtaUpgrade::BasicStream::errorCode = Error::None
inherited

Error code. Only relevant if hasError() returns true.

◆ header

uint8_t OtaUpgrade::EncryptedStream::header[crypto_secretstream_xchacha20poly1305_HEADERBYTES]

◆ receiveTimeout

unsigned long Stream::receiveTimeout = 1000
protectedinherited

◆ startMillis

unsigned long Stream::startMillis = 0
protectedinherited

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