Documentation updates and prepare for relase.

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

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

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:
 	///