From e05aa1295c2f6865631aaaf314b3177223eaa073 Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Sun, 22 Oct 2023 02:43:19 -0700 Subject: [PATCH] Documentation updates and prepare for relase. --- README.md | 13 ++- cmake/docs.cmake | 22 +---- docs/emsha.3.md | 25 ------ docs/libemsha.7.md | 13 --- docs/mainpage.md | 198 ------------------------------------------- include/emsha/hmac.h | 8 +- 6 files changed, 18 insertions(+), 261 deletions(-) delete mode 100644 docs/emsha.3.md delete mode 100644 docs/libemsha.7.md delete mode 100644 docs/mainpage.md diff --git a/README.md b/README.md index 022e9ad..02599ae 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# emsha +# 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) @@ -39,6 +39,17 @@ There are two cache variables that might be useful: - `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 diff --git a/cmake/docs.cmake b/cmake/docs.cmake index dc0f861..6802bef 100644 --- a/cmake/docs.cmake +++ b/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 () diff --git a/docs/emsha.3.md b/docs/emsha.3.md deleted file mode 100644 index 200bbd8..0000000 --- a/docs/emsha.3.md +++ /dev/null @@ -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. diff --git a/docs/libemsha.7.md b/docs/libemsha.7.md deleted file mode 100644 index 31a11bd..0000000 --- a/docs/libemsha.7.md +++ /dev/null @@ -1,13 +0,0 @@ -@PROJECT_NAME@(7) "@PROJECT_VERSION@" - -# NAME - -# DESCRIPTION - -# DATA STRUCTURES - -# HEADER FILES - -# NOTES - -# SEE ALSO diff --git a/docs/mainpage.md b/docs/mainpage.md deleted file mode 100644 index ca088a5..0000000 --- a/docs/mainpage.md +++ /dev/null @@ -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. diff --git a/include/emsha/hmac.h b/include/emsha/hmac.h index 74c5117..597d032 100644 --- a/include/emsha/hmac.h +++ b/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() - /// in length. + /// \param digest A byte buffer that must be at least + /// #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() - /// in length. + /// \param digest A byte buffer that must be at least + /// #Size() in length. /// \return An ::EMSHAResult describing the result of this /// method: ///