{"id":13408711,"url":"https://github.com/abderraouf-adjal/ArduinoSpritzCipher","last_synced_at":"2025-03-14T13:31:51.228Z","repository":{"id":85282390,"uuid":"41375199","full_name":"abderraouf-adjal/ArduinoSpritzCipher","owner":"abderraouf-adjal","description":"Spritz encryption system portable C library, CSPRNG, cryptographic hash and MAC functions, symmetric-key data encryption, and general-purpose functions.  It's also an Arduino library.","archived":false,"fork":false,"pushed_at":"2020-08-20T18:55:23.000Z","size":658,"stargazers_count":75,"open_issues_count":0,"forks_count":14,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-07-31T20:31:54.660Z","etag":null,"topics":["algorithms","arduino","arduino-library","c","crypto","crypto-library","cryptography","embedded","encryption","hash","microcontroller","random-bytes","spritz","spritz-library"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abderraouf-adjal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-25T16:37:29.000Z","updated_at":"2024-05-06T09:29:26.000Z","dependencies_parsed_at":"2023-09-19T17:03:32.129Z","dependency_job_id":null,"html_url":"https://github.com/abderraouf-adjal/ArduinoSpritzCipher","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderraouf-adjal%2FArduinoSpritzCipher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderraouf-adjal%2FArduinoSpritzCipher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderraouf-adjal%2FArduinoSpritzCipher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abderraouf-adjal%2FArduinoSpritzCipher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abderraouf-adjal","download_url":"https://codeload.github.com/abderraouf-adjal/ArduinoSpritzCipher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243584391,"owners_count":20314750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithms","arduino","arduino-library","c","crypto","crypto-library","cryptography","embedded","encryption","hash","microcontroller","random-bytes","spritz","spritz-library"],"created_at":"2024-07-30T20:00:54.754Z","updated_at":"2025-03-14T13:31:51.219Z","avatar_url":"https://github.com/abderraouf-adjal.png","language":"C","readme":"# Spritz Library For Arduino\n\n\u003e Spritz - a spongy RC4-like stream cipher and hash function.\n\nThis library contains a cryptographic pseudo-random number generator,\ncryptographic hash and message authentication code (MAC) functions,\ncan perform symmetric-key authenticated data encryption, and general-purpose\nfunctions for timing-safe comparison and wiping data from memory.\n\nThis C Spritz library can be used to:\n\n- Hash and authenticate data.\n- Perform symmetric-key authenticated data encryption.\n- Generate random numbers and strings from entropy/seed.\n\n[This library's GitHub repository](https://github.com/abderraouf-adjal/ArduinoSpritzCipher).\n\n[This library's Bitbucket repository](https://bitbucket.org/abderraouf-adjal/arduinospritzcipher) (Backup).\n\n**Spritz paper:** \u003chttps://people.csail.mit.edu/rivest/pubs/RS14.pdf\u003e\n\n---\n\n## Library Content\n\n**Read the source code for details.**\n\n### Types\n\n**spritz_ctx** - The context/ctx (contains the state). The state consists of byte registers\n{i, j, k, z, w, a}, And an array {s} containing a permutation of {0, 1, ... , SPRITZ_N-1}.\n\n**uint8_t**  - unsigned integer type with width of 8-bit, MIN=0;MAX=255.\n\n**uint16_t** - unsigned integer type with width of 16-bit, MIN=0;MAX=65,535.\n\n**uint32_t** - unsigned integer type with width of 32-bit, MIN=0;MAX=4,294,967,295.\n\n### Functions\n\n```c\nuint8_t spritz_compare(const uint8_t *data_a, const uint8_t *data_b,\n                       uint16_t len)\n```\n\nTiming-safe comparison for `data_a` and `data_b` equality.\nThis function can be used to compare the password's hash safely.\n\nReturn equality result.\nZero (0x00) if `data_a` equals `data_b` OR if `len` is zero,\nNon-zero value if they are NOT equal.\n\n```c\nvoid spritz_memzero(uint8_t *buf, uint16_t len)\n```\n\nWipe `buf` data by replacing it with `len` zeros (0x00).\n\n```c\nvoid spritz_state_memzero(spritz_ctx *ctx)\n```\n\nWipe `spritz_ctx`'s data by replacing its data with zeros (0x00).\n\nIf `SPRITZ_WIPE_TRACES_PARANOID` is defined, This function will\nwipe the *sensitive* temporary variables in `spritz_ctx`.\n\n```c\nvoid spritz_setup(spritz_ctx *ctx,\n                  const uint8_t *key, uint8_t keyLen)\n```\n\nSetup the spritz state `spritz_ctx` with a `key` of length `keyLen`.\n\n```c\nvoid spritz_setup_withIV(spritz_ctx *ctx,\n                         const uint8_t *key, uint8_t keyLen,\n                         const uint8_t *nonce, uint8_t nonceLen)\n```\n\nSetup the spritz state `spritz_ctx` with a `key` and `nonce`/Salt/IV.\n\n```c\nuint8_t spritz_random8(spritz_ctx *ctx)\n```\n\nGenerates a random byte (8-bit) from the spritz state `spritz_ctx`.\n\n```c\nuint32_t spritz_random32(spritz_ctx *ctx)\n```\n\nGenerates a random 32-bit (4 bytes) from the spritz state `spritz_ctx`.\n\n```c\nuint32_t spritz_random32_uniform(spritz_ctx *ctx, uint32_t upper_bound)\n```\n\nCalculate an uniformly distributed random number less than `upper_bound` avoiding *modulo bias*.\nUniformity is achieved by generating new random numbers until the one\nreturned is outside the range [0, 2\\*\\*32 % `upper_bound`).\nThis guarantees the selected random number will be inside\n[2\\*\\*32 % `upper_bound`, 2\\*\\*32) which maps back to [0, `upper_bound`)\nafter reduction modulo `upper_bound`.\n\n```c\nvoid spritz_add_entropy(spritz_ctx *ctx,\n                        const uint8_t *entropy, uint16_t len)\n```\n\nAdd `entropy` to the spritz state `spritz_ctx` using the internal function `absorb()`.\n\n```c\nvoid spritz_crypt(spritz_ctx *ctx,\n                  const uint8_t *data, uint16_t dataLen,\n                  uint8_t *dataOut)\n```\n\nEncrypt or decrypt `data` chunk by XOR-ing it with the spritz keystream.\n\n```c\nvoid spritz_crypt_inplace(spritz_ctx *ctx,\n                          uint8_t *data, uint16_t dataLen)\n```\n\nEncrypt or decrypt data chunk by XOR-ing it with the spritz keystream\nand put the output in the same buffer `data`.\n\n```c\nvoid spritz_hash(uint8_t *digest, uint8_t digestLen,\n                 const uint8_t *data, uint16_t dataLen)\n```\n\nSpritz cryptographic hash function.\n\n```c\nvoid spritz_mac(uint8_t *digest, uint8_t digestLen,\n                const uint8_t *msg, uint16_t msgLen,\n                const uint8_t *key, uint16_t keyLen)\n```\n\nSpritz Message Authentication Code (MAC) function.\n\n```c\nvoid spritz_hash_setup(spritz_ctx *hash_ctx)\n```\n\nSetup the spritz hash state.\n\n```c\nvoid spritz_hash_update(spritz_ctx *hash_ctx,\n                        const uint8_t *data, uint16_t dataLen)\n```\n\nAdd a message/data chunk `data` to hash.\n\n```c\nvoid spritz_hash_final(spritz_ctx *hash_ctx,\n                       uint8_t *digest, uint8_t digestLen)\n```\n\nOutput the hash digest.\n\n```c\nvoid spritz_mac_setup(spritz_ctx *mac_ctx,\n                      const uint8_t *key, uint16_t keyLen)\n```\n\nSetup the spritz Message Authentication Code (MAC) state.\n\n```c\nvoid spritz_mac_update(spritz_ctx *mac_ctx,\n                       const uint8_t *msg, uint16_t msgLen)\n```\n\nAdd a message/data chunk to Message Authentication Code (MAC).\n\n```c\nvoid spritz_mac_final(spritz_ctx *mac_ctx,\n                      uint8_t *digest, uint8_t digestLen)\n```\n\nOutput the Message Authentication Code (MAC) digest.\n\n#### Notes\n\n`spritz_random8()`, `spritz_random32()`, `spritz_random32_uniform()`, `spritz_add_entropy()`, `spritz_crypt()`.\nAre usable only after calling `spritz_setup()` or `spritz_setup_withIV()`.\n\nFunctions `spritz_random*()` requires `spritz_setup()` or `spritz_setup_withIV()` initialized with an entropy (random data), 128-bit of entropy at least.\nArduino Uno's ATmega328P and many microcontrollers and microprocessors does NOT have a real/official way to get entropy,\n\n**you will/may need getting entropy** by using hardware (recommended), or at least a pre-stored random data updated with `spritz_random*()` output (NOT recommended).\n\nTo generate a random number in a range [k, m) use `k + spritz_random32_uniform(ctx, m)`,\nNot `k + (spritz_random8(ctx) % m)` or `k + (spritz_random32(ctx) % m)`.\n\nUse `spritz_state_memzero()` after `spritz_hash_final()` or `spritz_mac_final()`\nif you need to wipe the used `spritz_ctx`'s data.\n\n### Constants\n\nConfigure library settings in the file `SpritzCipher.h`.\n\n- **SPRITZ_USE_LIBC**\n\nUse C standard library functions such as `memset()` to zero buffers.\nIt can be useful for performnce if the lib-C functions are optimized in low-level.\nIf the compiler is not GCC or Clang, you will see a security warning about code optimization\nis not off in some sensitive functions.\n\n`SPRITZ_USE_LIBC` is **NOT** defined by default.\n\n- **SPRITZ_TIMING_SAFE_CRUSH**\n\nIf defined, The equal time `crush()` will be used.\n\n`SPRITZ_TIMING_SAFE_CRUSH` is defined by default.\n\n- **SPRITZ_WIPE_TRACES**\n\nIf defined, Sensitive data like `spritz_ctx` will be wiped, when they are\nno longer needed, in the functions: `spritz_hash()`, `spritz_mac()`.\n\n`SPRITZ_WIPE_TRACES` is **NOT** defined by default.\n\n- **SPRITZ_WIPE_TRACES_PARANOID**\n\nIf defined, The library functions internal variables will be wiped if they\ncontain a bit or more of spritz state, such as temporary variables in a swap\nfunction or user data. Variables that contain data length will not be wiped.\n\nIf `SPRITZ_WIPE_TRACES_PARANOID` defined, Then `SPRITZ_WIPE_TRACES` and `SPRITZ_TIMING_SAFE_CRUSH`, will be defined automatically.\n\n`SPRITZ_WIPE_TRACES_PARANOID` is **NOT** defined by default.\n\n- **SPRITZ_N** = `256` - Present the value of N in this spritz implementation, *Do NOT change `SPRITZ_N` value*.\n\n- **SPRITZ_LIBRARY_VERSION_STRING** = `\"x.y.z\"` - Present the version of this\nspritz library (MAJOR . MINOR . PATCH) using Semantic Versioning.\n\n- **SPRITZ_LIBRARY_VERSION_MAJOR** = `x` - The MAJOR version of the library.\n\n- **SPRITZ_LIBRARY_VERSION_MINOR** = `y` - The MINOR version of the library.\n\n- **SPRITZ_LIBRARY_VERSION_PATCH** = `z` - The PATCH version of the library.\n\n---\n\n## Examples\n\n- [SpritzBestPractice](examples/SpritzBestPractice/SpritzBestPractice.ino):\nHash 32 KB of a Spritz stream (pseudo-random number generator output) then print the result.\nAn embedded entropy/seed for the pseudo-random number generator is used.\n\n- [SpritzBestPracticePassword](examples/SpritzBestPracticePassword/SpritzBestPracticePassword.ino):\nGenerate a strong Alphanumeric passwords, and then print it.\nAn embedded entropy/seed for the pseudo-random number generator is used.\n\n- [SpritzBestPracticePasswordESP8266](examples/SpritzBestPracticePasswordESP8266/SpritzBestPracticePasswordESP8266.ino):\nGenerate a strong Alphanumeric passwords, and then print it.\nThis example is for ESP8266 SoC, it uses a hardware RNG in ESP8266 as an initialization entropy.\n\n- [SpritzCryptTest](examples/SpritzCryptTest/SpritzCryptTest.ino):\nTest the library encryption/decryption function.\n\n- [SpritzCryptInplaceTest](examples/SpritzCryptInplaceTest/SpritzCryptInplaceTest.ino):\nTest the library encryption/decryption function doing encrypt and decrypt\nin same buffer for less RAM usage.\n\n- [SpritzStreamTest](examples/SpritzStreamTest/SpritzStreamTest.ino):\nGenerate random bytes (Spritz stream) test.\n\n- [SpritzHashTest](examples/SpritzHashTest/SpritzHashTest.ino):\nHash function test.\n\n- [SpritzMACTest](examples/SpritzMACTest/SpritzMACTest.ino):\nMessage authentication code (MAC) function test.\n\n---\n\n## Installation Guide\n\n[Arduino IDE](https://www.arduino.cc/en/Main/Software) -\n[Additional libraries installation guide](https://www.arduino.cc/en/Guide/Libraries).\n\nCompiling this library using *GCC* or *Clang* will give more security for functions that should be compiled with *zero optimization* (`-O0`) like `spritz_compare()`.\n\n---\n\n## Reporting bugs\n\n[Create an issue on GitHub](https://github.com/abderraouf-adjal/ArduinoSpritzCipher/issues).\n\n---\n\n## Copyright and License\n\n\u003e Copyright (c) 2015-2020 Abderraouf Adjal\n\n- The source-code: ISC License.\n\n- Documentation (e.g. this file content): Public domain.\n\n- Examples: Public domain.\n","funding_links":[],"categories":["Libraries and Frameworks"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabderraouf-adjal%2FArduinoSpritzCipher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabderraouf-adjal%2FArduinoSpritzCipher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabderraouf-adjal%2FArduinoSpritzCipher/lists"}