From a682c339bf55a6593b7c81d9a2d3ab47d3bdf82e Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Sun, 22 Oct 2023 02:32:51 -0700 Subject: [PATCH] Documentation updates and circleCI config update. --- .circleci/config.yml | 17 +++------ CMakeLists.txt | 13 +++++-- README.md | 88 +++++++++++++++++++------------------------- 3 files changed, 52 insertions(+), 66 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index d265266..1a2cca1 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -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: diff --git a/CMakeLists.txt b/CMakeLists.txt index 4b93e04..27126d6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -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() diff --git a/README.md b/README.md index 8094cf0..022e9ad 100644 --- a/README.md +++ b/README.md @@ -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.