Major refactoring effort underway.
This commit is contained in:
parent
5ec7d4462e
commit
ad07da5a39
|
@ -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
|
|
@ -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
|
|
@ -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
|
||||
|
|
|
@ -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
|
|
@ -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>
|
|
@ -0,0 +1,5 @@
|
|||
<component name="ProjectCodeStyleConfiguration">
|
||||
<state>
|
||||
<option name="PREFERRED_PROJECT_CODE_STYLE" value="Project copy" />
|
||||
</state>
|
||||
</component>
|
|
@ -0,0 +1,2 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<module classpath="CMake" type="CPP_MODULE" version="4" />
|
|
@ -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>
|
|
@ -0,0 +1,4 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="CMakeWorkspace" PROJECT_DIR="$PROJECT_DIR$" />
|
||||
</project>
|
|
@ -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>
|
|
@ -0,0 +1,3 @@
|
|||
<component name="DependencyValidationManager">
|
||||
<scope name="ProjectSources" pattern="file[emsha]:emsha/*||file:hmac.cc||file:emsha.cc||file:sha256.cc" />
|
||||
</component>
|
|
@ -0,0 +1,6 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="VcsDirectoryMappings">
|
||||
<mapping directory="" vcs="Git" />
|
||||
</component>
|
||||
</project>
|
|
@ -0,0 +1,8 @@
|
|||
*out
|
||||
*logs
|
||||
*actions
|
||||
*notifications
|
||||
*tools
|
||||
plugins
|
||||
user_trunk.yaml
|
||||
user.yaml
|
|
@ -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
|
|
@ -0,0 +1,2 @@
|
|||
[settings]
|
||||
profile=black
|
|
@ -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
|
|
@ -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
|
|
@ -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
|
|
@ -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"]
|
|
@ -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
|
|
@ -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:
|
||||
|
|
|
@ -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
28
Makefile.am
|
@ -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 $@
|
|
@ -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
37
cleanroom
|
@ -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
|
||||
|
|
@ -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 ()
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
set(EMSHA_INCLUDE_DIRS include/@PROJECT_NAME@)
|
||||
set(EMSHA_LIBRARIES libemsha-@PROJECT_VERSION_MAJOR@.a)
|
||||
|
|
@ -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)
|
||||
|
||||
|
|
@ -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
62
configure.ac
|
@ -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
|
|
@ -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
204
doc/Makefile
|
@ -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
|
||||
|
||||
|
601
doc/libemsha.rst
601
doc/libemsha.rst
|
@ -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
|
||||