sc/emsha
sc
/
emsha
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation updates and circleCI config update.

This commit is contained in:
Kyle Isom 2023-10-22 02:32:51 -07:00
parent d4065a9668
commit a682c339bf
3 changed files with 52 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
.circleci/config.yml
View File

@ -1,25 +1,18 @@
# Use the latest 2.1 version of CircleCI pipeline process engine.
# See: https://circleci.com/docs/configuration-reference
version: 2.1
# Define a job to be invoked later in a workflow.
# See: https://circleci.com/docs/configuration-reference/#jobs
jobs:
ctest:
# Specify the execution environment. You can specify an image from Docker Hub or use one of our convenience images from CircleCI's Developer Hub.
# See: https://circleci.com/docs/configuration-reference/#executor-job
docker:
- image: git.wntrmute.dev/sc/dev:alpine
# Add steps to the job
# See: https://circleci.com/docs/configuration-reference/#steps
- image: git.wntrmute.dev/sc/dev:main
steps:
- checkout
- run:
name: Setup cmake build
command: setup-cmake.sh
command: cmake-build-and-test.sh
- run:
name: Valgrind checks.
command: cmake-run-valgrind.sh
# Orchestrate jobs using workflows
# See: https://circleci.com/docs/configuration-reference/#workflows
workflows:
ctest:
jobs:

13
CMakeLists.txt
View File

@ -1,15 +1,15 @@
cmake_minimum_required(VERSION 3.22)
project(emsha
VERSION 1.1.0
VERSION 1.1.1
LANGUAGES CXX
DESCRIPTION "A compact HMAC-SHA-256 C++11 library.")
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_VERBOSE_MAKEFILES ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
set(EMSHA_NO_HEXSTRING OFF CACHE BOOL
set(SET_EMSHA_NO_HEXSTRING OFF CACHE BOOL
"Don't include support for hex strings.")
if (EMSHA_NO_HEXSTRING)
if (SET_EMSHA_NO_HEXSTRING)
add_definitions(EMSHA_NO_HEXSTRING)
endif ()
set(SET_EMSHA_NO_HEXLUT OFF CACHE BOOL
@ -18,6 +18,13 @@ if (SET_EMSHA_NO_HEXLUT)
add_definitions("-DEMSHA_NO_HEXLUT")
endif ()
set(SET_EMSHA_NO_SELFTEST OFF CACHE BOOL
"Disable the internal self-tests.")
if (SET_EMSHA_NO_SELFTEST)
add_definitions("-DEMSHA_NO_SELFTEST")
endif ()
include(CTest)
enable_testing()

88
README.md
View File

@ -1,74 +1,60 @@
libemsha
========
# emsha
[![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.
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
-------------------------------
### Getting and Building the Source
The source code is available via
[Github](https://github.com/kisom/libemsha/); each version should be git
tagged. :
git clone https://github.com/kisom/libemsha
git clone git@github.com:kisom/libemsha
[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.0.1](https://github.com/kisom/libemsha/releases/tag/v1.0.1).
[1.1.1](https://git.wntrmute.dev/sc/emsha/releases/tag/v1.1.0).
The project is built using Autotools and `make`.
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).
When building from a git checkout, the [autobuild]{.title-ref} script
will bootstrap the project from the autotools sources (e.g. via
`autoreconf -i`), run `configure` (by default to use clang), and attempt
to build the library and run the unit tests.
Once the autotools infrastructure has been bootstrapped, the following
should work: :
There are two cache variables that might be useful:
./configure && make && make check && make install
- `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.
There are three flags to `configure` that might be useful:
### Documentation
- `--disable-hexstring` disables the provided `hexstring` function;
while this might be useful in many cases, it also adds extra size to
the code.
- `--disable-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.
- `--disable-selftest` disables the internal self-tests, which can
reclaim some additional program space.
Documentation
-------------
Documentation is currently done with [Sphinx](http://sphinx-doc.org/).
See `doc/`.
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)[^1]
- [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.
linux/amd64 standard library's [crypto/sha256](https://golang.org/src/crypto/sha256/) package.
**Footnotes**
### Acknowledgements
[^1]: 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 base.
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.