# 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'.)

## 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).

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

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.

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.