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

Documentation and build updates in preparation for 1.0.0.

Browse Source
This commit is contained in:
Kyle Isom
2015-12-22 14:31:15 -08:00
parent bfcf11129c
commit 98853d8549
24 changed files with 374 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
doc/source/_static/.gitkeep Normal file
View File

0
doc/source/_templates/.gitkeep Normal file
View File

37
doc/source/building.rst Normal file
View File

@@ -0,0 +1,37 @@
-------------------------------
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.

335
doc/source/conf.py.in Normal file
View File

@@ -0,0 +1,335 @@
# -*- coding: utf-8 -*-
#
# @PACKAGE_NAME@ documentation build configuration file, created by
# sphinx-quickstart on Tue Dec 15 23:35:10 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import sphinx_rtd_theme
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.todo',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'@PACKAGE_NAME@'
copyright = u'2015, K. Isom <coder@kyleisom.net>'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '@PACKAGE_VERSION@'
# The full version, including alpha/beta/rc tags.
release = '@PACKAGE_VERSION@'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
highlight_language = 'c++'
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = '@PACKAGE_NAME@doc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', '@PACKAGE_NAME@.tex', u'@PACKAGE_NAME@ Documentation',
u'K. Isom <coder@kyleisom.net>', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'package_name', u'@PACKAGE_NAME@ Documentation',
[u'K. Isom <coder@kyleisom.net>'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', '@PACKAGE_NAME@', u'@PACKAGE_NAME@ Documentation',
u'K. Isom <coder@kyleisom.net>', '@PACKAGE_NAME@', 'HMAC-SHA-256 C++11 library designed for embedded systems.',
'Development'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'@PACKAGE_NAME@'
epub_author = u'K. Isom <coder@kyleisom.net>'
epub_publisher = u'K. Isom <coder@kyleisom.net>'
epub_copyright = u'2015, K. Isom <coder@kyleisom.net>'
# The basename for the epub file. It defaults to the project name.
#epub_basename = u'@PACKAGE_NAME@'
# The HTML theme for the epub output. Since the default themes are not optimized
# for small screen space, using the same theme for HTML and epub output is
# usually not wise. This defaults to 'epub', a theme designed to save visual
# space.
#epub_theme = 'epub'
# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# A unique identification for the text.
#epub_uid = ''
# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()
# A sequence of (type, uri, title) tuples for the guide element of content.opf.
#epub_guide = ()
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True
# Choose between 'default' and 'includehidden'.
#epub_tocscope = 'default'
# Fix unsupported image types using the PIL.
#epub_fix_images = False
# Scale large images.
#epub_max_image_width = 0
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#epub_show_urls = 'inline'
# If false, no index is generated.
#epub_use_index = True

74
doc/source/hash.rst Normal file
View File

@@ -0,0 +1,74 @@
------------------
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.

113
doc/source/hmac.rst Normal file
View File

@@ -0,0 +1,113 @@
--------------
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``.

27
doc/source/index.rst Normal file
View File

@@ -0,0 +1,27 @@
.. libemsha documentation master file, created by
sphinx-quickstart on Tue Dec 15 23:35:10 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
libemsha
========
.. toctree::
:maxdepth: 2
intro
building
overview
hash
sha256
hmac
misc
tests
refs
Indices and tables
==================
* :ref:`genindex`

21
doc/source/intro.rst Normal file
View File

@@ -0,0 +1,21 @@
-------------
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>`_

107
doc/source/misc.rst Normal file
View File

@@ -0,0 +1,107 @@
-----------------------
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``.

46
doc/source/overview.rst Normal file
View File

@@ -0,0 +1,46 @@
----------------
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`

17
doc/source/refs.rst Normal file
View File

@@ -0,0 +1,17 @@
----------
References
----------
* `FIPS 180-4, the Secure Hash Standard <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf>`_
* `FIPS 198-1, The Keyed-Hash Message Authentication Code (HMAC) <http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf>`_
* `RFC 2014, HMAC: Keyed-Hashing for Message Authentication <https://tools.ietf.org/html/rfc2104>`_
* `RFC 6234, US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF) <https://tools.ietf.org/html/rfc6234>`_\ [#f1]_
* The behaviour of this package was cross-checked using the Go 1.5.1
linux/amd64 standard library's `crypto/sha256 <https://golang.org/src/crypto/sha256/>`_
package.
.. rubric:: Footnotes
.. [#f1] This library came about after extracting the relevant C code
from RFC 6234, and needing a C++ version. It draws heavy
inspiration from that code base.

112
doc/source/sha256.rst Normal file
View File

@@ -0,0 +1,112 @@
-----------------
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``.

50
doc/source/tests.rst Normal file
View File

@@ -0,0 +1,50 @@
-------------
Test Programs
-------------
Running ``make check`` builds and runs the test programs. These are:
* ``emsha_core_test`` runs the core tests.
* ``emsha_sha256_test`` runs test vectors on the SHA-256 code.
* ``emsha_hmac_test`` runs test vectors on the HMAC code.
Additionally, the following test programs are built but not run. These
programs do not link with the library as the above programs do; instead,
they compile the object files in to avoid the libtool dance before the
library is installed.
* ``emsha_mem_test`` and ``emsha_static_mem_test`` are for memory
profiling (e.g., with `Valgrind <http://valgrind.org/>`_ during
development.
* ``emsha_static_sha256_test`` and ``emsha_static_hmac_test`` are used
to facilitate testing and debugging the library. These programs run
the same tests as the ``emsha_sha256_test`` and ``emsha_hmac_test``
programs.
Core Tests
^^^^^^^^^^
There are three tests run in the core tests: a hexstring test (if
`support is built in <./building.html>`_) and the constant time
check. The constant time test does not validate that the function
is constant time, only that it correctly verifies that two byte
arrays are equal.
SHA-256 Tests
^^^^^^^^^^^^^
The SHA-256 checks take a number of test vectors from the Go standard
library's SHA-256 library.
HMAC Tests
^^^^^^^^^^
The HMAC checks apply the `RFC 4231 <http://tools.ietf.org/html/rfc4231>`_
test vectors to the HMAC code.