sc/emsha
sc
/
emsha
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Major refactoring effort underway.

This commit is contained in:
Kyle Isom 2023-10-17 23:43:18 -07:00
parent 5ec7d4462e
commit ad07da5a39
76 changed files with 2493 additions and 3609 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
.clang-format Normal file
View File

@ -0,0 +1,67 @@
# Generated from CLion C/C++ Code Style settings
BasedOnStyle: LLVM
AccessModifierOffset: -8
AlignAfterOpenBracket: Align
AlignConsecutiveAssignments: Consecutive
AlignOperands: Align
AllowAllArgumentsOnNextLine: false
AllowAllConstructorInitializersOnNextLine: false
AllowAllParametersOfDeclarationOnNextLine: false
AllowShortBlocksOnASingleLine: Always
AllowShortCaseLabelsOnASingleLine: false
AllowShortFunctionsOnASingleLine: All
AllowShortIfStatementsOnASingleLine: Always
AllowShortLambdasOnASingleLine: All
AllowShortLoopsOnASingleLine: true
AlwaysBreakAfterReturnType: TopLevel
AlwaysBreakTemplateDeclarations: Yes
BreakBeforeBraces: Custom
BraceWrapping:
AfterCaseLabel: false
AfterClass: false
AfterControlStatement: Never
AfterEnum: false
AfterFunction: true
AfterNamespace: false
AfterUnion: false
BeforeCatch: false
BeforeElse: false
IndentBraces: false
SplitEmptyFunction: false
SplitEmptyRecord: true
BreakBeforeBinaryOperators: None
BreakBeforeTernaryOperators: true
BreakConstructorInitializers: BeforeColon
BreakInheritanceList: BeforeColon
ColumnLimit: 0
CompactNamespaces: false
ContinuationIndentWidth: 4
IndentCaseLabels: false
IndentPPDirectives: None
IndentWidth: 8
KeepEmptyLinesAtTheStartOfBlocks: true
MaxEmptyLinesToKeep: 2
NamespaceIndentation: None
ObjCSpaceAfterProperty: false
ObjCSpaceBeforeProtocolList: true
QualifierAlignment: Left
PointerAlignment: Right
ReflowComments: false
SpaceAfterCStyleCast: true
SpaceAfterLogicalNot: false
SpaceAfterTemplateKeyword: false
SpaceBeforeAssignmentOperators: true
SpaceBeforeCpp11BracedList: false
SpaceBeforeCtorInitializerColon: true
SpaceBeforeInheritanceColon: true
SpaceBeforeParens: ControlStatements
SpaceBeforeRangeBasedForLoopColon: false
SpaceInEmptyParentheses: false
SpacesBeforeTrailingComments: 0
SpacesInAngles: false
SpacesInCStyleCastParentheses: false
SpacesInContainerLiterals: false
SpacesInParentheses: false
SpacesInSquareBrackets: false
TabWidth: 8
UseTab: ForContinuationAndIndentation

34
.clang-tidy Normal file
View File

@ -0,0 +1,34 @@
Checks: >-
bugprone-*,
cppcoreguidelines-*,
google-*,
misc-*,
modernize-*,
performance-*,
readability-*,
-bugprone-lambda-function-name,
-bugprone-reserved-identifier,
-cppcoreguidelines-avoid-goto,
-cppcoreguidelines-avoid-magic-numbers,
-cppcoreguidelines-avoid-non-const-global-variables,
-cppcoreguidelines-pro-bounds-array-to-pointer-decay,
-cppcoreguidelines-pro-type-vararg,
-google-readability-braces-around-statements,
-google-readability-function-size,
-misc-no-recursion,
-modernize-return-braced-init-list,
-modernize-use-nodiscard,
-modernize-use-trailing-return-type,
-performance-unnecessary-value-param,
-readability-identifier-length,
-readability-magic-numbers
CheckOptions:
- key: readability-function-cognitive-complexity.Threshold
value: 100
- key: readability-function-cognitive-complexity.IgnoreMacros
value: true
# Set naming conventions for your style below (there are dozens of naming settings possible):
# See https://clang.llvm.org/extra/clang-tidy/checks/readability/identifier-naming.html
- key: readability-identifier-naming.ClassCase
value: CamelCase

58
.gitignore vendored
View File

@ -1,59 +1,7 @@
*.o
*.lo
*.a
*.la
*.dirstamp
*.pc
*.log
*.trs
build
cmake-build-*
TAGS
tags
core*
# autoconf output
autom4te.cache
*.in
!/src/libemsha-1.pc.in
config.*
compile
*.m4
configure
depcomp
*.info
mdate-sh
stamp-*
texinfo.tex
version.texi
install-sh
missing
Makefile
.deps
.libs
libtool
ltmain.sh
RELEASE_NOTES
debian/files
debian/libemsha-1.postinst.debhelper
debian/libemsha-1.postrm.debhelper
debian/libemsha-1.substvars
debian/libemsha-1/
debian/libemsha-dev.substvars
debian/libemsha-dev/
debian/shlibs.local
debian/source/
debian/tmp/
doc/source/header.dated.rst
doc/source/header.rst
src/cov-int/
src/emsha_core_test
src/emsha_hmac_test
src/emsha_mem_test
src/emsha_sha256_test
src/emsha_static_hmac_test
src/emsha_static_mem_test
src/emsha_static_sha_test
src/libemsha.tgz
doc/source/conf.py
/test-driver
do-release

8
.idea/.gitignore vendored Normal file
View File

@ -0,0 +1,8 @@
# Default ignored files
/shelf/
/workspace.xml
# Editor-based HTTP Client requests
/httpRequests/
# Datasource local storage ignored files
/dataSources/
/dataSources.local.xml

29
.idea/codeStyles/Project.xml Normal file
View File

@ -0,0 +1,29 @@
<component name="ProjectCodeStyleConfiguration">
<code_scheme name="Project" version="173">
<Objective-C>
<option name="FUNCTION_BRACE_PLACEMENT" value="2" />
</Objective-C>
<files>
<extensions>
<pair source="cc" header="h" fileNamingConvention="PASCAL_CASE" />
<pair source="c" header="h" fileNamingConvention="NONE" />
<pair source="cu" header="cuh" fileNamingConvention="NONE" />
<pair source="ixx" header="" fileNamingConvention="NONE" />
<pair source="mxx" header="" fileNamingConvention="NONE" />
<pair source="cppm" header="" fileNamingConvention="NONE" />
<pair source="ccm" header="" fileNamingConvention="NONE" />
<pair source="cxxm" header="" fileNamingConvention="NONE" />
<pair source="c++m" header="" fileNamingConvention="NONE" />
</extensions>
</files>
<codeStyleSettings language="ObjectiveC">
<option name="ALIGN_GROUP_FIELD_DECLARATIONS" value="true" />
<indentOptions>
<option name="INDENT_SIZE" value="8" />
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="8" />
<option name="USE_TAB_CHARACTER" value="true" />
</indentOptions>
</codeStyleSettings>
</code_scheme>
</component>

5
.idea/codeStyles/codeStyleConfig.xml Normal file
View File

@ -0,0 +1,5 @@
<component name="ProjectCodeStyleConfiguration">
<state>
<option name="PREFERRED_PROJECT_CODE_STYLE" value="Project copy" />
</state>
</component>

2
.idea/emsha.iml Normal file
View File

@ -0,0 +1,2 @@
<?xml version="1.0" encoding="UTF-8"?>
<module classpath="CMake" type="CPP_MODULE" version="4" />

9
.idea/inspectionProfiles/Project_Default.xml Normal file
View File

@ -0,0 +1,9 @@
<component name="InspectionProjectProfileManager">
<profile version="1.0">
<option name="myName" value="Project Default" />
<inspection_tool class="ClangTidy" enabled="false" level="WARNING" enabled_by_default="false" />
<inspection_tool class="Misra" enabled="false" level="WARNING" enabled_by_default="false">
<scope name="ProjectSources" level="WARNING" enabled="false" />
</inspection_tool>
</profile>
</component>

4
.idea/misc.xml Normal file
View File

@ -0,0 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="CMakeWorkspace" PROJECT_DIR="$PROJECT_DIR$" />
</project>

8
.idea/modules.xml Normal file
View File

@ -0,0 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="ProjectModuleManager">
<modules>
<module fileurl="file://$PROJECT_DIR$/.idea/emsha.iml" filepath="$PROJECT_DIR$/.idea/emsha.iml" />
</modules>
</component>
</project>

3
.idea/scopes/ProjectSources.xml Normal file
View File

@ -0,0 +1,3 @@
<component name="DependencyValidationManager">
<scope name="ProjectSources" pattern="file[emsha]:emsha/*||file:hmac.cc||file:emsha.cc||file:sha256.cc" />
</component>

6
.idea/vcs.xml Normal file
View File

@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="VcsDirectoryMappings">
<mapping directory="" vcs="Git" />
</component>
</project>

8
.trunk/.gitignore vendored Normal file
View File

@ -0,0 +1,8 @@
*out
*logs
*actions
*notifications
*tools
plugins
user_trunk.yaml
user.yaml

39
.trunk/configs/.clang-tidy Normal file
View File

@ -0,0 +1,39 @@
Checks: >-
bugprone-*,
cppcoreguidelines-*,
google-*,
misc-*,
modernize-*,
performance-*,
readability-*,
-bugprone-lambda-function-name,
-bugprone-reserved-identifier,
-cppcoreguidelines-avoid-goto,
-cppcoreguidelines-avoid-magic-numbers,
-cppcoreguidelines-avoid-non-const-global-variables,
-cppcoreguidelines-pro-bounds-array-to-pointer-decay,
-cppcoreguidelines-pro-type-vararg,
-google-readability-braces-around-statements,
-google-readability-function-size,
-misc-no-recursion,
-modernize-return-braced-init-list,
-modernize-use-nodiscard,
-modernize-use-trailing-return-type,
-performance-unnecessary-value-param,
-readability-magic-numbers,
CheckOptions:
- key: readability-function-cognitive-complexity.Threshold
value: 100
- key: readability-function-cognitive-complexity.IgnoreMacros
value: true
# Set naming conventions for your style below (there are dozens of naming settings possible):
# See https://clang.llvm.org/extra/clang-tidy/checks/readability/identifier-naming.html
# - key: readability-identifier-naming.ClassCase
# value: CamelCase
# - key: readability-identifier-naming.NamespaceCase
# value: lower_case
# - key: readability-identifier-naming.PrivateMemberSuffix
# value: _
# - key: readability-identifier-naming.StructCase
# value: CamelCase

2
.trunk/configs/.isort.cfg Normal file
View File

@ -0,0 +1,2 @@
[settings]
profile=black

10
.trunk/configs/.markdownlint.yaml Normal file
View File

@ -0,0 +1,10 @@
# Autoformatter friendly markdownlint config (all formatting rules disabled)
default: true
blank_lines: false
bullet: false
html: false
indentation: false
line_length: false
spaces: false
url: false
whitespace: false

7
.trunk/configs/.shellcheckrc Normal file
View File

@ -0,0 +1,7 @@
enable=all
source-path=SCRIPTDIR
disable=SC2154
# If you're having issues with shellcheck following source, disable the errors via:
# disable=SC1090
# disable=SC1091

10
.trunk/configs/.yamllint.yaml Normal file
View File

@ -0,0 +1,10 @@
rules:
quoted-strings:
required: only-when-needed
extra-allowed: ["{|}"]
empty-values:
forbid-in-block-mappings: true
forbid-in-flow-mappings: true
key-duplicates: {}
octal-values:
forbid-implicit-octal: true

5
.trunk/configs/ruff.toml Normal file
View File

@ -0,0 +1,5 @@
# Generic, formatter-friendly config.
select = ["B", "D3", "E", "F"]
# Never enforce `E501` (line length violations). This should be handled by formatters.
ignore = ["E501"]

39
.trunk/trunk.yaml Normal file
View File

@ -0,0 +1,39 @@
# This file controls the behavior of Trunk: https://docs.trunk.io/cli
# To learn more about the format of this file, see https://docs.trunk.io/reference/trunk-yaml
version: 0.1
cli:
version: 1.17.0
plugins:
sources:
- id: trunk
ref: v1.2.6
uri: https://github.com/trunk-io/plugins
runtimes:
enabled:
- go@1.21.0
- node@18.12.1
- python@3.10.8
lint:
enabled:
- clang-tidy@16.0.3
- bandit@1.7.5
- black@23.9.1
- checkov@2.5.9
- git-diff-check
- isort@5.12.0
- markdownlint@0.37.0
- osv-scanner@1.4.1
- prettier@3.0.3
- ruff@0.0.292
- shellcheck@0.9.0
- shfmt@3.6.0
- trivy@0.46.0
- trufflehog@3.60.0
- yamllint@1.32.0
actions:
disabled:
- trunk-announce
- trunk-check-pre-push
- trunk-fmt-pre-commit
enabled:
- trunk-upgrade-available

5
CHANGELOG
View File

@ -1,6 +1,11 @@
LIBEMSHA CHANGELOG
==================
1.0.3 (2023-10-17):
Changed:
+ Switched from autotools to cmake.
1.0.2 (2015-01-28):
Added:

71
CMakeLists.txt Normal file
View File

@ -0,0 +1,71 @@
cmake_minimum_required(VERSION 3.22)
project(emsha
VERSION 1.0.3
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
"Don't include support for hex strings.")
set(EMSHA_NO_HEXLUT OFF CACHE BOOL
"Don't use a LUT for hex strings (saves ~256B of memory).")
include(CTest)
enable_testing()
# compile options:
# -Wall Default to all errors.
# -Wextra And a few extra.
# -Werror And require them to be fixed to build.
# -Wno-unused-function This is a library. Not every function is used here.
# -Wno-unused-parameter Some functions have parameters defined for compatibility,
# and aren't used in the implementation.
add_compile_options(
"-static"
"-Wall"
"-Wextra"
"-Werror"
"-Wno-unused-function"
"-Wno-unused-parameter"
"-g"
"$<$<CONFIG:RELEASE>:-O2>"
)
if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
add_compile_options("-stdlib=libc++")
else ()
# nothing special for gcc at the moment
endif ()
### Set up the build ###
set(HEADERS
emsha/emsha.h
emsha/sha256.h
emsha/hmac.h
emsha/internal.h)
set(SOURCES emsha.cc sha256.cc hmac.cc)
include_directories(SYSTEM .)
### Build products ###
add_library(${PROJECT_NAME} STATIC ${SOURCES} ${HEADERS})
### TESTS ###
set(TEST_SOURCES test_utils.cc)
macro(generate_test name)
add_executable(${name} ${name}.cc ${TEST_SOURCES} ${ARGN})
target_link_libraries(${name} ${PROJECT_NAME})
add_test(${name} ${name})
endmacro()
generate_test(test_${PROJECT_NAME} test_${PROJECT_NAME}.cc)
generate_test(test_hmac)
generate_test(test_mem)
generate_test(test_sha256)
include(cmake/docs.cmake)
include(cmake/install.cmake)
include(cmake/packaging.cmake)

28
Makefile.am
View File

@ -1,28 +0,0 @@
ACLOCAL_AMFLAGS = -I m4
SUBDIRS = src
TESTS = src/emsha_core_test \
src/emsha_sha256_test \
src/emsha_hmac_test
dist_data_DATA = LICENSE \
README.rst \
doc/libemsha.rst
dist_noinst_DATA = autobuild \
doc/source \
doc/Makefile
.PHONY: valgrind-check
valgrind-check:
cd src && make $@
.PHONY: cloc-report
cloc-report:
cd src && make $@
.PHONY: coverity-scan
coverity-scan:
cd src && make $@
epub:
cd doc && make $@

7
autobuild
View File

@ -1,7 +0,0 @@
#!/bin/sh
CXX=g++
command -v clang 2>&1 > /dev/null && CXX=clang++
[ -d m4 ] || mkdir m4
autoreconf -i && ./configure --enable-silent-rules CXX=$CXX \
&& make && make check

37
cleanroom
View File

@ -1,37 +0,0 @@
#!/bin/sh
echo ' ____ _ _ _ ____ _____ ____ '
echo ' | _ \ / \ | \ | |/ ___| ____| _ \ '
echo ' | | | |/ _ \ | \| | | _| _| | |_) |'
echo ' | |_| / ___ \| |\ | |_| | |___| _ < '
echo ' |____/_/ \_\_| \_|\____|_____|_| \_\'
echo ''
echo "[!] This script will destroy anything not tracked by git."
echo "[!] Waiting 5 seconds before running. Press ^C to abort."
echo -n "5"
sleep 1
echo -n " 4"
sleep 1
echo -n " 3"
sleep 1
echo -n " 2"
sleep 1
echo -n " 1"
sleep 1
echo " nuking from orbit!"
sleep 1
echo ""
git clean -fxd
echo ""
echo "-------------------------------------------------------------"
echo "If you wish to make an apple pie from scratch, you must first"
echo "create the universe."
echo " -- Carl Fucking Sagan"
echo "-------------------------------------------------------------"
echo ""
./autobuild

41
cmake/docs.cmake Normal file
View File

@ -0,0 +1,41 @@
# 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_LATEX YES)
set(DOXYGEN_EXTRACT_ALL YES)
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_CURRENT_SOURCE_DIR}/docs/mainpage.md")
message(STATUS "Doxygen found, building docs.")
doxygen_add_docs(${PROJECT_NAME}_docs
${HEADER_FILES}
${SOURCE_FILES}
USE_STAMP_FILE)
add_dependencies(${PROJECT_NAME} ${PROJECT_NAME}_docs)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
${CMAKE_CURRENT_BINARY_DIR}/latex
DESTINATION share/doc/${PROJECT_NAME}/doxygen)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man
DESTINATION share)
add_dependencies(${PROJECT_NAME}_docs manpages)
endif ()

3
cmake/emshaConfig.cmake Normal file
View File

@ -0,0 +1,3 @@
set(EMSHA_INCLUDE_DIRS include/@PROJECT_NAME@)
set(EMSHA_LIBRARIES libemsha-@PROJECT_VERSION_MAJOR@.a)

27
cmake/install.cmake Normal file
View File

@ -0,0 +1,27 @@
### Install ###
include(CMakePackageConfigHelpers)
### library packaging for CMake and pkgconfig to find built targets.
write_basic_package_version_file(
${PROJECT_NAME}Config.cmake
VERSION ${PACKAGE_VERSION}
COMPATIBILITY SameMajorVersion
)
write_basic_package_version_file(
${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
VERSION ${PROJECT_VERSION}
COMPATIBILITY SameMajorVersion)
configure_file(${PROJECT_NAME}.pc.in ${PROJECT_NAME}.pc @ONLY)
### set up installation targets.
install(TARGETS ${PROJECT_NAME} LIBRARY DESTINATION lib)
install(FILES ${HEADERS} DESTINATION include/${PROJECT_NAME})
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.pc
DESTINATION lib/pkgconfig)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake
${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
DESTINATION share/${PROJECT_CMAKE_CONFIG_NAME}/cmake)

41
cmake/packaging.cmake Normal file
View File

@ -0,0 +1,41 @@
### Packaging ###
include(InstallRequiredSystemLibraries)
set(CPACK_PACKAGE_VENDOR "K. Isom")
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY ${PROJECT_DESCRIPTION})
set(CPACK_PACKAGE_VERSION_MAJOR ${PROJECT_VERSION_MAJOR})
set(CPACK_PACKAGE_VERSION_MINOR ${PROJECT_VERSION_MINOR})
set(CPACK_PACKAGE_VERSION_PATCH ${PROJECT_VERSION_PATCH})
set(CPACK_PACKAGE_FILE_NAME
${PROJECT_NAME}-${PROJECT_VERSION}-${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_ARCH}${CMAKE_HOST_SYSTEM_PROCESSOR})
# Debian settings
set(CPACK_DEBIAN_PACKAGE_MAINTAINER ${CPACK_PACKAGE_VENDOR})
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY ${CPACK_PACKAGE_DESCRIPTION})
set(CPACK_PACKAGE_DESCRIPTION ${CPACK_PACKAGE_DESCRIPTION})
set(CPACK_PACKAGE_DEPENDS)
set(CPACK_DEBIAN_PACKAGE_SECTION devel)
set(CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS ON)
set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)
if(LINUX)
set(CPACK_GENERATOR "DEB;STGZ;TGZ")
elseif(APPLE)
set(CPACK_GENERATOR "productbuild")
elseif(MSVC OR MSYS OR MINGW)
set(CPACK_GENERATOR "NSIS;ZIP")
else()
set(CPACK_GENERATOR "ZIP")
endif()
set(CPACK_SOURCE_GENERATOR "TGZ;ZIP")
set(CPACK_SOURCE_IGNORE_FILES
/.git
/dist
/.*build.*)
include (CPack)
add_custom_target(package_docs DEPENDS emsha_docs package package_source)

62
configure.ac
View File

@ -1,62 +0,0 @@
# autoconf version 2.68 and automake version 1.11 seem to be the latest
# versions that can be used with Travis right now.
AC_PREREQ([2.68])
AC_INIT([libemsha],
[1.0.2],
[coder@kyleisom.net],
[libemsha],
[https://kyleisom.net/projects/libemsha/])
AM_INIT_AUTOMAKE([1.11 foreign])
AC_CONFIG_SRCDIR([src/emsha/sha256.hh])
AC_CONFIG_FILES([Makefile src/Makefile doc/source/conf.py doc/source/header.rst src/libemsha-1.pc])
AC_CONFIG_FILES([do-release], [chmod +x do-release])
AC_CONFIG_MACRO_DIR([m4])
PKG_PROG_PKG_CONFIG
AC_CHECK_HEADERS
LT_INIT
AC_PROG_CXX
AC_PROG_INSTALL
AC_PROG_CC_C_O
AC_CHECK_PROGS([SPHINX], [sphinx-build])
if test -z "$SPHINX";
then
AC_MSG_WARN([Sphinx not found - continuing without Sphinx support])
fi
AC_ARG_ENABLE([hexstring],
AS_HELP_STRING([--disable-hexstring], [Don't build with support for hex string output (default enabled)]),
[:], [enable_hexstring=check])
AC_ARG_ENABLE([hexlut],
AS_HELP_STRING([--disable-hexlut], [Don't build with the larger LUT for building hex strings (saves ~1KB of memory). This has no effect if hex strings are disabled.]),
[:], [enable_hexlut=check])
AC_ARG_ENABLE([selftest],
AS_HELP_STRING([--disable-selftest], [Don't build with support for internal self-tests (saves some memory that is used by the test vectors.)]),
[:], [enable_selftest=check])
# The default for the ARG_ENABLE options is to have them enabled.
AS_IF([test "x$enable_hexstring" == "xno"], [
AC_MSG_NOTICE([disabling hexstrings.])
AC_DEFINE(EMSHA_NO_HEXSTRING)
])
AS_IF([test "x$enable_hexlut" == "xno"], [
AC_MSG_NOTICE([disabling the large hexstring LUT.])
AC_DEFINE(EMSHA_NO_HEXLUT)
])
AS_IF([test "x$enable_selftest" == "xno"], [
AC_MSG_NOTICE([disabling the internal self tests.])
AC_DEFINE(EMSHA_NO_SELFTEST)
])
AM_CONDITIONAL([HAVE_SPHINX],
[test -n "$SPHINX"])
AC_OUTPUT

43
do-release.in
View File

@ -1,43 +0,0 @@
#!/bin/sh
set -e
VERSION="@PACKAGE_VERSION@"
TARBALL="@PACKAGE_NAME@-$VERSION"
make clean
echo "[+] rebuilding single ReST doc"
cd doc && make clean singlerst clean && cd ..
echo "[+] building release tarballs"
make dist-gzip
if [ ! -e "$TARBALL.tar.gz" ]
then
>&2 echo "[!] Expected to find ${TARBALL}.tar.gz, but it wasn't found."
>&2 echo " Cannot proceed, aborting."
exit 1
fi
make dist-zip
if [ ! -e "$TARBALL.zip" ]
then
>&2 echo "[!] Expected to find ${TARBALL}.zip, but it wasn't found."
>&2 echo " Cannot proceed, aborting."
exit 1
fi
mv "${TARBALL}.tar.gz" "@PACKAGE_NAME@-release.tar.gz"
mv "${TARBALL}.zip" "@PACKAGE_NAME@-release.zip"
echo "[+] building release notes"
RELEASE_NOTES_AWK="/^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9]+)? \([0-9]{4}-[0-9]{2}-[0-9]{2}\):/{
nmatch++;
if (nmatch>1) exit
}
{
if (nmatch>0)
print \$0;
}"
awk "$RELEASE_NOTES_AWK" CHANGELOG > RELEASE_NOTES
echo "[+] release is ready"

204
doc/Makefile
View File

@ -1,204 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext check
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
# The autotools Makefiles don't seem to do anything for docs in all or check.
all:
check:
distclean: clean
rm -f source/header*.rst
rm -f source/conf.py
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PACKAGE_NAME.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PACKAGE_NAME.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/PACKAGE_NAME"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PACKAGE_NAME"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
pdf: latexpdf
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
singlerst:
sed -e "s/@BUILD_DATE@/$$(date +'%Y-%m-%d')/" \
source/header.rst > source/header.dated.rst
cat source/header.dated.rst \
source/intro.rst \
source/building.rst \
source/overview.rst \
source/hash.rst \
source/sha256.rst \
source/hmac.rst \
source/misc.rst \
source/tests.rst \
source/refs.rst \
> libemsha.rst

0
doc/build/.gitkeep vendored
View File

601
doc/libemsha.rst
View File

@ -1,601 +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` 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
----------------
.. cpp:namespace:: emsha
The package provides a pair of classes, :cpp:class:`SHA256` and
:cpp:class:`HMAC`, that both satisfy a common interface :cpp:class:`Hash`. All
functionality provided by this library is found under the ``emsha`` namespace.
``EMSHA_RESULT``
^^^^^^^^^^^^^^^^^
The ``EMSHA_RESULT`` enum is used to convey the result of an
operation. The possible values are:
.. cpp:enum:: _EMSHA_RESULT_ : uint8_t
::
// All operations have completed successfully so far.
EMSHA_ROK = 0,
// A self test or unit test failed.
EMSHA_TEST_FAILURE = 1,
// A null pointer was passed in as a buffer where it
// shouldn't have been.
EMSHA_NULLPTR = 2,
// The Hash is in an invalid state.
EMSHA_INVALID_STATE = 3,
// The input to SHA256::update is too large.
SHA256_INPUT_TOO_LONG = 4,
// The self tests have been disabled, but a self test
// function was called.
EMSHA_SELFTEST_DISABLED = 5
As a convenience, the following ``typedef`` is also provided.
``typedef enum _EMSHA_RESULT_`` :cpp:type:`EMSHA_RESULT`
------------------
The Hash interface
------------------
.. cpp:class:: emsha::Hash
The ``Hash`` class contains a top-level interface for the objects in
this library.
In general, a `Hash` is used along the lines of: ::
emsha::EMSHA_RESULT
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::EMSHA_RESULT res;
res = h.write(m, ml);
if (emsha::EMSHA_ROK != 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
^^^^^^^
.. cpp:function:: emsha::EMSHA_RESULT reset(void)
reset should bring the Hash back into its initial state. That is,
the idea is that::
hash->reset();
hash->update(...); // possibly many of these...
hash->result(...); // should always return the same hash.
is idempotent, assuming the inputs to ``update`` and ``result``
are constant. The implications of this for a given concrete class
should be described in that class's documentation, but in general,
it has the effect of preserving any initial state while removing any
data written to the Hash via the update method.
.. cpp:function:: emsha::EMSHA_RESULT update(const uint8_t *m, uint32_t ml)
``update`` is used to write message data into
the Hash.
.. cpp:function:: emsha::EMSHA_RESULT finalize(uint8_t *d)
``finalize`` should carry out any final operations on the `Hash`;
after a call to finalize, no more data can be written. Additionally,
it transfers out the resulting hash into its argument.
Note that this library does not allocate memory, and therefore the
caller *must* ensure that ``d`` is a valid buffer containing at least
``this->size()`` bytes.
.. cpp:function:: emsha::EMSHA_RESULT result(uint8_t *d)
``result`` is used to transfer out the hash to the argument. This implies
that the `Hash` must keep enough state for repeated calls to ``result``
to work.
.. cpp:function:: uint32_t size(void)
``size`` should return the output size of the `Hash`; this is, how large
the buffers written to by ``result`` should be.
-----------------
The SHA256 class
-----------------
.. cpp:class:: emsha::SHA256
SHA256 is an implementation of the :cpp:class:`emsha::Hash` interface
implementing the SHA-256 cryptographic hash algorithm
.. cpp:function:: SHA256::SHA256()
A SHA256 context does not need any special construction. It can be
declared and immediately start being used.
.. cpp:function:: SHA256::~SHA256()
The SHA256 destructor will clear out its internal message buffer;
all of the members are local and not resource handles, so cleanup
is minimal.
.. cpp:function:: emsha::EMSHA_RESULT SHA256::reset(void)
reset clears the internal state of the `SHA256` context and returns
it to its initial state. It should always return ``EMSHA_ROK``.
.. cpp:function:: emsha::EMSHA_RESULT SHA256::update(const uint8_t *m, uint32_t ml)
update writes data into the context. While there is an upper limit
on the size of data that SHA-256 can operate on, this package is
designed for small systems that will not approach that level of
data (which is on the order of 2 exabytes), so it is not thought to
be a concern.
**Inputs**:
+ ``m``: a byte array containing the message to be written. It must
not be NULL (unless the message length is zero).
+ ``ml``: the message length, in bytes.
**Return values**:
* ``EMSHA_NULLPTR`` is returned if ``m`` is NULL and ``ml`` is nonzero.
* ``EMSHA_INVALID_STATE`` is returned if the `update` is called
after a call to `finalize`.
* ``SHA256_INPUT_TOO_LONG`` is returned if too much data has been
written to the context.
+ ``EMSHA_ROK`` is returned if the data was successfully added to
the SHA-256 context.
.. cpp:function:: emsha::EMSHA_RESULT SHA256::finalize(uint8_t *d)
``finalize`` completes the digest. Once this method is called, the
context cannot be updated unless the context is reset.
**Inputs**:
* d: a byte buffer that must be at least ``SHA256.size()`` in
length.
**Outputs**:
* ``EMSHA_NULLPTR`` is returned if ``d`` is the null pointer.
* ``EMSHA_INVALID_STATE`` is returned if the SHA-256 context is in
an invalid state, such as if there were errors in previous
updates.
* ``EMSHA_ROK`` is returned if the context was successfully
finalised and the digest copied to ``d``.
.. cpp:function:: emsha::EMSHA_RESULT SHA256::result(uint8_t *d)
``result`` copies the result from the SHA-256 context into the
buffer pointed to by ``d``, running finalize if needed. Once
called, the context cannot be updated until the context is reset.
**Inputs**:
* ``d``: a byte buffer that must be at least ``SHA256.size()`` in
length.
**Outputs**:
* ``EMSHA_NULLPTR`` is returned if ``d`` is the null pointer.
* ``EMSHA_INVALID_STATE`` is returned if the SHA-256 context is in
an invalid state, such as if there were errors in previous
updates.
* ``EMSHA_ROK`` is returned if the context was successfully
finalised and the digest copied to ``d``.
.. cpp:function:: uint32_t SHA256::size(void)
``size`` returns the output size of SHA256, e.g.
the size that the buffers passed to ``finalize``
and ``result`` should be.
**Outputs**:
* a ``uint32_t`` representing the expected size of buffers passed
to ``result`` and ``finalize``.
--------------
The HMAC class
--------------
.. cpp:class:: emsha::HMAC
HMAC is an implementation of the :cpp:class:`emsha::Hash` interface
implementing the HMAC keyed-hash message authentication code as
defined in FIPS 198-1, using SHA-256 internally.
.. cpp:function:: HMAC::HMAC(const uint8_t *key, uint32_t keylen)
An HMAC context must be initialised with a key.
.. cpp:function:: HMAc::~HMAC()
The HMAC destructor will attempt to wipe the key and reset the
underlying SHA-256 context.
.. cpp:function:: emsha::EMSHA_RESULT HMAC::reset(void)
reset clears the internal state of the `HMAC` context and returns
it to its initial state. It should always return ``EMSHA_ROK``.
This function will **not** wipe the key; an `HMAC` object that has
`reset` called it can be used immediately after.
.. cpp:function:: emsha::EMSHA_RESULT HMAC::update(const uint8_t *m, uint32_t ml)
update writes data into the context. While there is an upper limit on
the size of data that the underlying SHA-256 context can operate on,
this package is designed for small systems that will not approach
that level of data (which is on the order of 2 exabytes), so it is
not thought to be a concern.
**Inputs**:
+ ``m``: a byte array containing the message to be written. It must
not be NULL (unless the message length is zero).
+ ``ml``: the message length, in bytes.
**Return values**:
* ``EMSHA_NULLPTR`` is returned if ``m`` is NULL and ``ml`` is nonzero.
* ``EMSHA_INVALID_STATE`` is returned if the `update` is called
after a call to `finalize`.
* ``SHA256_INPUT_TOO_LONG`` is returned if too much data has been
written to the context.
+ ``EMSHA_ROK`` is returned if the data was successfully added to
the HMAC context.
.. cpp:function:: emsha::EMSHA_RESULT SHA256::finalize(uint8_t *d)
``finalize`` completes the digest. Once this method is called, the
context cannot be updated unless the context is reset.
**Inputs**:
* d: a byte buffer that must be at least ``SHA256.size()`` in
length.
**Outputs**:
* ``EMSHA_NULLPTR`` is returned if ``d`` is the null pointer.
* ``EMSHA_INVALID_STATE`` is returned if the HMAC context is in
an invalid state, such as if there were errors in previous
updates.
* ``EMSHA_ROK`` is returned if the context was successfully
finalised and the digest copied to ``d``.
.. cpp:function:: emsha::EMSHA_RESULT SHA256::result(uint8_t *d)
``result`` copies the result from the HMAC context into the
buffer pointed to by ``d``, running finalize if needed. Once
called, the context cannot be updated until the context is reset.
**Inputs**:
* ``d``: a byte buffer that must be at least ``HMAC.size()`` in
length.
**Outputs**:
* ``EMSHA_NULLPTR`` is returned if ``d`` is the null pointer.
* ``EMSHA_INVALID_STATE`` is returned if the HMAC context is in
an invalid state, such as if there were errors in previous
updates.
* ``EMSHA_ROK`` is returned if the context was successfully
finalised and the digest copied to ``d``.
.. cpp:function:: uint32_t SHA256::size(void)
``size`` returns the output size of HMAC, e.g. the size that the
buffers passed to ``finalize`` and ``result`` should be.
**Outputs**:
* a ``uint32_t`` representing the expected size of buffers passed
to ``result`` and ``finalize``.
-----------------------
Miscellaneous functions
-----------------------
.. cpp:function:: emsha::EMSHA_RESULT sha256_self_test(void)
If the library was `compiled with support for self tests
<./building.html>`_ (the default), this function will run a few self
tests on the SHA-256 functions to validate that they are working
correctly.
**Outputs**:
* ``EMSHA_ROK`` if the self-test completed successfully.
* ``EMSHA_TEST_FAILURE`` if the SHA-256 functions did not produce
the expected value.
* ``EMSHA_SELFTEST_DISABLED`` if the library was built without
support for the self test.
* If an error occurs in the SHA-256 code, the resulting error code
will be returned.
.. cpp:function:: emsha::EMSHA_RESULT sha256_digest(const uint8_t *m, uint32_t ml, uint8_t *d)
The ``sha256_digest`` function will compute the digest on the
``ml``-byte octet string stored in ``m``, returning the result
in ``d``. This is a convenience function implemented as: ::
EMSHA_RESULT
sha256_digest(const uint8_t *m, uint32_t ml, uint8_t *d)
{
SHA256 h;
EMSHA_RESULT ret;
if (EMSHA_ROK != (ret = h.update(m, ml))) {
return ret;
}
return h.finalize(d);
}
.. cpp:function:: emsha::EMSHA_RESULT compute_hmac(const uint8_t *k, uint32_t kl, const uint8_t *m, uint32_t ml, uint8_t *d)
The ``compute_hmac`` function computes the MAC on the ``ml``-byte
octet string stored in``m``, using the ``kl``-length key ``k``. The
result is stored in ``d``. This is a convenience function implemented
as: ::
EMSHA_RESULT
compute_hmac(const uint8_t *k, uint32_t kl, const uint8_t *m, uint32_t ml,
uint8_t *d)
{
EMSHA_RESULT res;
HMAC h(k, kl);
res = h.update(m, ml);
if (EMSHA_ROK != res) {
return res;
}
res = h.result(d);
if (EMSHA_ROK != res) {
return res;
}
return res;
}
.. cpp:function:: bool hash_equal(const uint8_t *a, const uint8_t *b)
``hash_equal`` performs a constant-time comparison of the first
``emsha::SHA256_HASH_SIZE`` bytes in the two byte array arguments.
**Inputs**:
* ``a``, ``b``: byte arrays at least ``emsha::SHA256_HASH_SIZE``
bytes in length.
** Outputs**:
* true *iff* the first ``emsha::SHA256_HASH_SIZE`` bytes match in
both arrays.
* false otherwise.
.. cpp:function:: void hexstring(uint8_t *dest, uint8_t *src, uint32_t srclen)
**Note**: this function is only present if the library was
`built with support <./building.html>`_ for the hexstring functionality.
**Inputs**:
* dest: a byte array that is 2 * ``srclen``.
* src: a byte array containing the data to process.
* srclen: the size of ``src``.
**Outputs**:
When the function returns, the hex-encoded string will be placed in
``dest``.
-------------
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