72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
# emsha: EMbedded Secure HAshing
|
|
|
|
[![CircleCI](https://dl.circleci.com/status-badge/img/gh/shimmering-clarity/emsha/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/shimmering-clarity/emsha/tree/master)
|
|
|
|
[![image](https://scan.coverity.com/projects/29250/badge.svg)](https://scan.coverity.com/projects/shimmering-clarity-emsha)
|
|
|
|
This library is an MIT-licensed HMAC-SHA-256 C++11 library designed for
|
|
embedded systems. It is built following the JPL [Power of Ten](http://spinroot.com/gerard/pdf/P10.pdf)
|
|
rules. It was written in response to a need for a standalone HMAC-SHA-256
|
|
package that could run on several platforms, including several memory-
|
|
constrained embedded platforms.
|
|
|
|
### Getting and Building the Source
|
|
|
|
The source code is available via
|
|
[Git](https://git.wntrmute.dev/sc/emsha/); each version should be git
|
|
tagged. There is also a [mirror on Github](https://github.com/shimmering-clarity/emsha).
|
|
|
|
```
|
|
git clone https://git.wntrmute.dev/sc/emsha
|
|
```
|
|
The current release is
|
|
[1.1.1](https://git.wntrmute.dev/sc/emsha/releases/tag/v1.1.0).
|
|
|
|
The project is built using CMake. Packages are built using the `RelWithDebInfo`
|
|
configuration; artifacts are built using the [sc3dev](https://git.wntrmute.dev/sc/sc3dev/)
|
|
[build script](https://git.wntrmute.dev/sc/sc3dev/src/branch/master/cmake-build-and-test.sh).
|
|
|
|
|
|
There are two cache variables that might be useful:
|
|
|
|
- `SET EMSHA_NO_HEXSTRING` disables the provided `hexstring` function;
|
|
while this might be useful in many cases, it also adds extra size to
|
|
the code. For memory-constrained microcontrollers, this might be
|
|
desirable.
|
|
- `SET_EMSHA_NO_HEXLUT` disables the larger lookup table used by
|
|
`hexstring`, which can save around a kilobyte of program space. If
|
|
the `hexstring` function is disabled, this option has no effect.
|
|
- `SET_EMSHA_NO_SELFTEST` disables the internal self-tests, which can
|
|
reclaim some additional program space.
|
|
|
|
### Synopsis
|
|
|
|
The Hash pure virtual class defines a basic interface for programs:
|
|
|
|
- Hash::Reset will clear an instance of a Hash class.
|
|
- Hash::Update writes data into the Hash.
|
|
- Hash::Finalize will finish the Hash function and write the results
|
|
out.
|
|
|
|
There are two implementations provided for Hash: SHA256 and HMAC.
|
|
|
|
### Documentation
|
|
|
|
Documentation is currently done with Doxygen; documentation is
|
|
available [online](https://docs.shimmering-clarity.net/emsha/).
|
|
|
|
### See also
|
|
|
|
- [FIPS 180-4, the Secure Hash Standard](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf)
|
|
- [FIPS 198-1, The Keyed-Hash Message Authentication Code (HMAC)](http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf)
|
|
- [RFC 2014, HMAC: Keyed-Hashing for Message Authentication](https://tools.ietf.org/html/rfc2104)
|
|
- [RFC 6234, US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)](https://tools.ietf.org/html/rfc6234)
|
|
- The behaviour of this package was cross-checked using the Go 1.5.1
|
|
linux/amd64 standard library's [crypto/sha256](https://golang.org/src/crypto/sha256/) package.
|
|
|
|
### Acknowledgements
|
|
|
|
This library came about after extracting the relevant C code from RFC
|
|
6234, and needing a C++ version. It draws heavy inspiration from that
|
|
code. I also pulled a lot of test vectors from Go's crypto/sha256.
|