Documentation updates and prepare for relase.

This commit is contained in:
Kyle Isom 2023-10-22 02:43:19 -07:00
parent a682c339bf
commit e05aa1295c
6 changed files with 18 additions and 261 deletions

View File

@ -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) [![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 - `SET_EMSHA_NO_SELFTEST` disables the internal self-tests, which can
reclaim some additional program space. 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
Documentation is currently done with Doxygen; documentation is Documentation is currently done with Doxygen; documentation is

View File

@ -1,29 +1,12 @@
# Doxygen support for scsl. # 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) find_package(Doxygen)
if (${DOXYGEN_FOUND}) if (${DOXYGEN_FOUND})
# prefer scdocs for manpages. # prefer scdocs for manpages.
set(DOXYGEN_GENERATE_MAN NO) set(DOXYGEN_GENERATE_MAN YES)
set(DOXYGEN_GENERATE_LATEX YES) set(DOXYGEN_GENERATE_LATEX YES)
set(DOXYGEN_EXTRACT_ALL 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" ) set(DOXYGEN_EXCLUDE_PATTERNS "test_*" "*.cc" )
message(STATUS "Doxygen found, building docs.") message(STATUS "Doxygen found, building docs.")
@ -42,6 +25,5 @@ if (${DOXYGEN_FOUND})
DESTINATION share/doc/${PROJECT_NAME}/doxygen) DESTINATION share/doc/${PROJECT_NAME}/doxygen)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man
DESTINATION share) DESTINATION share)
add_dependencies(${PROJECT_NAME}_docs manpages)
endif () endif ()

View File

@ -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.

View File

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

View File

@ -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.

View File

@ -99,8 +99,8 @@ public:
/// \note Once #Finalise is called, the context cannot be /// \note Once #Finalise is called, the context cannot be
/// updated unless the context is reset. /// 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 /// \return An EMSHAResult describing the result of this
/// method: /// method:
/// ///
@ -120,8 +120,8 @@ public:
/// `digest`, running #Finalise if needed. Once called, the /// `digest`, running #Finalise if needed. Once called, the
/// context cannot be updated until the context is reset. /// 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 /// \return An ::EMSHAResult describing the result of this
/// method: /// method:
/// ///