Darwin: don't build .pkg, build stgz and tgz packages.

.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
+      - image: git.wntrmute.dev/sc/dev:main
-    # Add steps to the job
-    # See: https://circleci.com/docs/configuration-reference/#steps
     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:

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()
 

README.md

@@ -1,74 +1,71 @@
-libemsha
+# 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
+embedded systems. It is built following the JPL [Power of  Ten](http://spinroot.com/gerard/pdf/P10.pdf)
-Ten](http://spinroot.com/gerard/pdf/P10.pdf) rules. It was written in
+rules. It was written in response to a need for a standalone HMAC-SHA-256
-response to a need for a standalone HMAC-SHA-256 package that could run
+package that could run on several platforms, including several memory-
-on several platforms.
+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
+[Git](https://git.wntrmute.dev/sc/emsha/); each version should be git
-tagged. :
+tagged. There is also a [mirror on Github](https://github.com/shimmering-clarity/emsha).
-
-    git clone https://github.com/kisom/libemsha
-    git clone git@github.com:kisom/libemsha
 
+```
+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
+There are two cache variables that might be useful:
-should work: :
 
-    ./configure && make && make check && make install
+- `SET EMSHA_NO_HEXSTRING` disables the provided `hexstring` function;
-
-There are three flags to `configure` that might be useful:
-
--   `--disable-hexstring` disables the provided `hexstring` function;
   while this might be useful in many cases, it also adds extra size to
-    the code.
+  the code. For memory-constrained microcontrollers, this might be 
--   `--disable-hexlut` disables the larger lookup table used by
+  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.
--   `--disable-selftest` disables the internal self-tests, which can
+- `SET_EMSHA_NO_SELFTEST` disables the internal self-tests, which can
   reclaim some additional program space.
 
-Documentation
+### Synopsis
--------------
 
-Documentation is currently done with [Sphinx](http://sphinx-doc.org/).
+The Hash pure virtual class defines a basic interface for programs:
-See `doc/`.
+
+- 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
+-   [FIPS 180-4, the Secure Hash Standard](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf)
-    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)
--   [FIPS 198-1, The Keyed-Hash Message Authentication Code
+-   [RFC 2014, HMAC: Keyed-Hashing for Message Authentication](https://tools.ietf.org/html/rfc2104)
-    (HMAC)](http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf)
+-   [RFC 6234, US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)](https://tools.ietf.org/html/rfc6234)
--   [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]
 -   The behaviour of this package was cross-checked using the Go 1.5.1
-    linux/amd64 standard library\'s
+    linux/amd64 standard library's [crypto/sha256](https://golang.org/src/crypto/sha256/) package.
-    [crypto/sha256](https://golang.org/src/crypto/sha256/) package.
 
-**Footnotes**
+### Acknowledgements
 
-[^1]: This library came about after extracting the relevant C code from
+This library came about after extracting the relevant C code from  RFC 
-    RFC 6234, and needing a C++ version. It draws heavy inspiration from
+6234, and needing a C++ version. It draws heavy inspiration from that
-    that code base.
+code. I also pulled a lot of test vectors from Go's crypto/sha256.

cmake/docs.cmake

@@ -1,29 +1,12 @@
 # Doxygen support for scsl.
 
-add_custom_target(manpages)
-
-macro(md2man source)
-	block()
-		set(SOURCE_MANPAGE)
-		set(SOURCE_SECTION)
-		string(REGEX REPLACE "^.+/([^/]+)\.md$" "\\1" SOURCE_MANPAGE ${source})
-		string(REGEX REPLACE "^.+/[^/]+\.([0-9])\.md$" "\\1" SOURCE_SECTION ${source})
-		file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man/man${SOURCE_SECTION})
-		configure_file(${source} ${SOURCE_MANPAGE}.scdoc)
-		add_custom_command(TARGET manpages
-			COMMAND scdoc < ${SOURCE_MANPAGE}.scdoc > man/man${SOURCE_SECTION}/${SOURCE_MANPAGE})
-	endblock()
-endmacro()
-
-md2man(docs/emsha.3.md)
-
 find_package(Doxygen)
 if (${DOXYGEN_FOUND})
 	# prefer scdocs for manpages.
-	set(DOXYGEN_GENERATE_MAN NO)
+	set(DOXYGEN_GENERATE_MAN YES)
 	set(DOXYGEN_GENERATE_LATEX YES)
 	set(DOXYGEN_EXTRACT_ALL YES)
-	set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_CURRENT_SOURCE_DIR}/docs/mainpage.md")
+	set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
 	set(DOXYGEN_EXCLUDE_PATTERNS "test_*" "*.cc" )
 	message(STATUS "Doxygen found, building docs.")
 
@@ -42,6 +25,5 @@ if (${DOXYGEN_FOUND})
 		DESTINATION share/doc/${PROJECT_NAME}/doxygen)
 	install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man
 		DESTINATION share)
-	add_dependencies(${PROJECT_NAME}_docs manpages)
 endif ()
 

cmake/packaging.cmake

@@ -23,7 +23,7 @@ set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)
 if (LINUX)
 	set(CPACK_GENERATOR "DEB;STGZ;TGZ")
 elseif (APPLE)
-	set(CPACK_GENERATOR "productbuild")
+	set(CPACK_GENERATOR "STGZ;TGZ")
 elseif (MSVC OR MSYS OR MINGW)
 	set(CPACK_GENERATOR "NSIS;ZIP")
 else ()

docs/emsha.3.md

@@ -1,25 +0,0 @@
-libemsha(3) "@PROJECT_VERSION@"
-
-# Introduction
-
-This library is an MIT-licensed compact HMAC-SHA-256 C++11 library
-designed for embedded systems. It is built following the JPL Power of
-Ten rules.
-
-This library came about as a result of a need for a standalone SHA-256
-library for an embedded system. The original goal was to implement a
-wrapper around the code extracted from RFC 6234; instead a standalone
-implementation was decided on.
-
-# References
-
-- 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 Power of Ten – Rules for Developing Safety Critical Code: (http://spinroot.com/gerard/pdf/P10.pdf)
-
-# Validation
-
-- The behaviour of this package was cross-checked using the Go 1.5.1 linux/amd64 standard library\'s
-  crypto/sha256 package.

docs/libemsha.7.md

@@ -1,13 +0,0 @@
-@PROJECT_NAME@(7) "@PROJECT_VERSION@"
-
-# NAME
-
-# DESCRIPTION
-
-# DATA STRUCTURES
-
-# HEADER FILES
-
-# NOTES
-
-# SEE ALSO

docs/mainpage.md

@@ -1,198 +0,0 @@
-# libemsha
-
-Version: 1.0.2
-
-Date: 2016-01-28
-
-## Table of Contents
-
-- Introduction
-- Getting and Building the Source
-- Library Overview
-- The Hash interface
-- The SHA256 class
-- The HMAC class
-- Miscellaneous functions
-- Test Programs
-- References
-
-## Introduction
-
-This library is an MIT-licensed compact 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.
-
-This library came about as a result of a need for a standalone SHA-256
-library for an embedded system. The original goal was to implement a
-wrapper around the code extracted from [RFC
-6234](https://tools.ietf.org/html/rfc6234); instead a standalone
-implementation was decided on.
-
-Additional resources:
-
-- [Github page](https://github.com/kisom/libemsha)
-- [Travis CI status](https://travis-ci.org/kisom/libemsha/)
-- [Coverity Scan page](https://scan.coverity.com/projects/libemsha-52f2a5fd-e759-43c2-9073-cf6c2ed9abdb)
-
-## 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
-
-The current release is
-[1.0.0](https://github.com/kisom/libemsha/archive/1.0.0.zip).
-
-The project is built using Autotools and `make`.
-
-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 `configurei` (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: :
-
-    ./configure && make && make check && make install
-
-There are three flags to `configure` that might be useful:
-
-- `--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.
-
-## Library Overview
-
-The package provides a pair of classes, :cpp`SHA256`{.interpreted-text
-role="class"} and :cpp`HMAC`{.interpreted-text role="class"}, that both
-satisfy a common interface :cpp`Hash`{.interpreted-text role="class"}.
-All functionality provided by this library is found under the `emsha`
-namespace.
-
-### `EMSHAResult`
-
-The `EMSHAResult` enum is used to convey the result of an operation.
-The possible values are:
-
-    // All operations have completed successfully so far.
-    EMSHAResult::OK = 0,
-
-    // A self test or unit test failed.
-    EMSHAResult::TestFailure = 1,
-
-    // A null pointer was passed in as a buffer where it
-    // shouldn't have been.
-    EMSHAResult::NullPointer = 2,
-
-    // The Hash is in an invalid state.
-    EMSHAResult::InvalidState = 3,
-
-    // The input to SHA256::update is too large.
-    EMSHAResult::InputTooLong = 4,
-
-    // The self tests have been disabled, but a self test
-    // function was called.
-    EMSHAResult::SelfTestDisabled = 5
-
-As a convenience, the following `typedef` is also provided.
-
-> `typedef enum _EMSHA_RESULT_` :cpp`EMSHAResult`{.interpreted-text
-> role="type"}
-
-## The Hash interface
-
-In general, a [Hash]{.title-ref} is used along the lines of: :
-
-    emsha::EMSHAResult
-    hash_single_pass(uint8_t *m, uint32_t ml, uint8_t *digest)
-    {
-            // Depending on the implementation, the constructor may need
-            // arguments.
-            emsha::Hash         h;
-            emsha::EMSHAResult res;
-
-            res = h.write(m, ml);
-            if (emsha::EMSHAResult::OK != res) {
-                    return res;
-            }
-
-            // digest will contain the output of the Hash, and the
-            // caller MUST ensure that there is enough space in
-            // the buffer.
-            return h.result(d);
-    }
-
-### Methods
-
-## The SHA256 class
-
-## The HMAC class
-
-## Miscellaneous functions
-
-## Test Programs
-
-Running `make check` builds and runs the test programs. These are:
-
-- `emsha_core_test` runs the core tests.
-- `emsha_sha256_test` runs test vectors on the SHA-256 code.
-- `emsha_hmac_test` runs test vectors on the HMAC code.
-
-Additionally, the following test programs are built but not run. These
-programs do not link with the library as the above programs do; instead,
-they compile the object files in to avoid the libtool dance before the
-library is installed.
-
-- `emsha_mem_test` and `emsha_static_mem_test` are for memory
-  profiling (e.g., with [Valgrind](http://valgrind.org/) during
-  development.
-- `emsha_static_sha256_test` and `emsha_static_hmac_test` are used to
-  facilitate testing and debugging the library. These programs run the
-  same tests as the `emsha_sha256_test` and `emsha_hmac_test`
-  programs.
-
-### Core Tests
-
-There are three tests run in the core tests: a hexstring test (if
-[support is built in](./building.html)) and the constant time check. The
-constant time test does not validate that the function is constant time,
-only that it correctly verifies that two byte arrays are equal.
-
-### SHA-256 Tests
-
-The SHA-256 checks take a number of test vectors from the Go standard
-library\'s SHA-256 library.
-
-### HMAC Tests
-
-The HMAC checks apply the [RFC 4231](http://tools.ietf.org/html/rfc4231)
-test vectors to the HMAC code.
-
-## References
-
-- [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]
-- 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.
-
-**Footnotes**
-
-[^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.

include/emsha/hmac.h

@@ -99,8 +99,8 @@ public:
 	/// \note Once #Finalise is called, the context cannot be
 	///       updated unless the context is reset.
 	///
-	/// \param digest A byte buffer that must be at least #HMAC.Size()
+	/// \param digest A byte buffer that must be at least
-	///          in length.
+	///        #Size() in length.
 	/// \return An EMSHAResult describing the result of this
 	///         method:
 	///
@@ -120,8 +120,8 @@ public:
 	/// `digest`, running #Finalise if needed. Once called, the
 	/// context cannot be updated until the context is reset.
 	///
-	/// \param digest A byte buffer that must be at least #HMAC.size()
+	/// \param digest A byte buffer that must be at least
-	///               in length.
+	///        #Size() in length.
 	/// \return An ::EMSHAResult describing the result of this
 	///         method:
 	///