SFBChecksum.h File Reference

A cryptographically insecure but fairly fast and small checksum. More...

#include <inttypes.h>

Include dependency graph for SFBChecksum.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef uint32_t	SFBChecksum [2]
	The internal representation of an SFBChecksum.
Functions
void	SFBChecksumInit (SFBChecksum cs)
	Initialize an SFBChecksum struct.
void	SFBChecksumAddByte (SFBChecksum cs, char data)
	Incorporate an additional data byte into cs, a SFBChecksum struct.
void	SFBChecksumAddBytes (SFBChecksum cs, const char *data, int length)
	Incorporate a sequence of additional data bytes into an SFBChecksum struct.
void	SFBChecksumCopy (const SFBChecksum csFrom, SFBChecksum csTo)
	Copy one SFBChecksum to another.
int	SFBChecksumEqual (const SFBChecksum cs1, const SFBChecksum cs2)
	Compare one SFBChecksum to another.
const char *	SFBChecksumToString (SFBChecksum cs)
	Access the current SFBChecksum result, as a zero-terminated, 16 character hexadecimal string.
int	SFBChecksumFromString (SFBChecksum cs, const char *hexString)
	Initialize an SFBChecksum from a string of 16 ASCII hex characers.

---

Detailed Description

A cryptographically insecure but fairly fast and small checksum.

An SFBChecksum is a compact, not too slow, fairly ARM friendly, 64 bit checksum, based on a (63 bit) linear feedback shift register (LFSR). It is designed to gain reasonable confidence that a sequence of data bytes has not been corrupted during transmission.

Attention:

NOTE WELL: SFBChecksum is ONLY aimed at detecting innocent changes (e.g., transmission noise, unintentional bugs, code development); it is NOT a cryptographic algorithm!

To repeat that:

PAY ATTENTION: Matching SFBChecksum's is no defense against malicious intent!

The SFB library uses SFBChecksum's in several contexts, including to check that code sectors and sketches exchanged during SFBCodeFlow.h operations match what is expected.

Example:

    void setup() { 
      // nothing to do, nothing to do, put some mustard in your shoe
    }
    void loop() {
      SFBCheckum cs;                         // Declare a checksum.  This DOES NOT initialize it!
      SFBChecksumInit(cs);                   // Now cs is ready for use

      SFBChecksumAddByte(cs,'!');            // Add a single byte to the checksum
      SFBChecksumAddBytes(cs, "foobar", 4);  // Add the four bytes 'f', 'o', 'o', 'b'

      u32 someData = 2468;                   // Get some data of some kind
      SFBChecksumAddBytes(cs, (const char *) &someData, sizeof(someData)); // Add it in

      println(SFBChecksumToString(cs));      // Print the current checksum in hexadecimal

      SFBChecksum cs2;                       // Get another, also uninitialized, checksum
      SFBChecksumCopy(cs, cs2);              // Copy from cs to cs2

      if (SFBChecksumEqual(cs2,cs)) println("same");   // Prints 'same'

      for (u32 i = 0; i < 100; ++i)
        SFBChecksumAddByte(cs,random(256));  // Add 100 random bytes to cs

      if (!SFBChecksumEqual(cs2,cs)) println("different"); // Prints 'different', with very high probability

      delay(5000);                           // Wait five seconds, then repeat 
    }

Author:

David H. Ackley.

Date:

(C) 2008 All rights reserved.

Code License:

The GNU Lesser General Public License

License Note:

All code samples shown in documentation are placed into the public domain.

---

Typedef Documentation

typedef uint32_t SFBChecksum[2]

The internal representation of an SFBChecksum.

An 'SFBChecksum' is simply an array of two 32 bit unsigned ints. (In other words, the same things that are abbreviated as u32 in most of the SFB codebase. They are written out here with their 'more official' abbreviation -- uint32_t -- to allow to SFBChecksum to 'stand alone'.)

Examples:

eeprom4.cpp.

---

Function Documentation

void SFBChecksumAddByte	(	SFBChecksum	cs,
		char	data
	)

Incorporate an additional data byte into cs, a SFBChecksum struct.

Parameters:

	cs	Pointer to the structure to update. Must be non-NULL.
	data	Byte to incorporate into the running SFBChecksum.

Side Effects:

cs is updated.

void SFBChecksumAddBytes	(	SFBChecksum	cs,
		const char *	data,
		int	length
	)

Incorporate a sequence of additional data bytes into an SFBChecksum struct.

Parameters:

	cs	Pointer to the structure to update. Must be non-NULL.
	data	Pointer to an array of length bytes to add to the running SFBChecksum in order, starting with data[0] and including up through data[length-1]. Must be non-NULL.
	length	Number of bytes in array data to use.

Side Effects:

cs is updated (unless length is less than 1).

Examples:

eeprom4.cpp.

void SFBChecksumCopy	(	const SFBChecksum	csFrom,
		SFBChecksum	csTo
	)

Copy one SFBChecksum to another.

Parameters:

	csFrom	source SFBChecksum
	csTo	destination SFBChecksum

Side Effects:

csTo is updated.

int SFBChecksumEqual	(	const SFBChecksum	cs1,
		const SFBChecksum	cs2
	)

Compare one SFBChecksum to another.

Parameters:

	cs1	one checksum
	cs2	the other checksum

Returns:

1 if and only cs1 and cs2 contain the same checksum, 0 otherwise

Examples:

eeprom4.cpp.

int SFBChecksumFromString	(	SFBChecksum	cs,
		const char *	hexString
	)

Initialize an SFBChecksum from a string of 16 ASCII hex characers.

Parameters:

	cs	Checksum to initialize. Must not be NULL.
	hexString	Pointer to an array of at least 16 ASCII hex characters with nothing else (no leading or embedded whitespace, etc). Must not be NULL. Routine only looks at first 16 positions, so anything after that is not a problem.

Returns:

1 if cs was successfully initialized from hexString,

0 an invalid (non-hex) ASCII character was encountered.

Example:

 void setup() { }
 void loop() {
   SFBChecksum cs;
   SFBChecksumInit(cs);
   SFBChecksumAddBytes(cs,"bytes",5);
   char * str = SFBChecksumToString(cs);           // Get cs as zero-terminated string of hex
   println(str);                                   // Print it.

   SFBChecksum cs2;
   SFBChecksumFromString(cs2,str);                 // Init cs2 from zstring of hex
   if (SFBChecksumEqual(cs,cs2)) println("same");  // Prints 'same'
   delay(1000);
 }

void SFBChecksumInit

(

SFBChecksum

cs

)

Initialize an SFBChecksum struct.

May be called at any time; may be called repeatedly; must be called before the SFBChecksum is first used and whenever a new SFBChecksum is being started.

Parameters:

cs

the SFBChecksum to initialize or reinitialize

Side Effects:

cs is initialized.

Examples:

eeprom4.cpp.

const char* SFBChecksumToString

(

SFBChecksum

cs

)

Access the current SFBChecksum result, as a zero-terminated, 16 character hexadecimal string.

Note this function returns a pointer to a statically allocated buffer, so:

1. The value returned from this function MUST NOT be 'free()'d.
2. The content pointed-to by the return value of this function is only valid until the next call of SFBChecksumToString on ANY SFBChecksum struct.

Note the pointed-to value is 16 ASCII-encoded hexadecimal characters.

Parameters:

cs

Checksum to read out

Returns:

Pointer to a zero-terminated string of 16 hexadecimal characters containing the current SFBChecksum result. See limitations above on the use of the pointed-to-data. Never returns NULL.

Side Effects:

The statically allocated char* buffer is overwritten, erasing its previous contents.