emsha/doc/source/misc.rst

108 lines
3.0 KiB
ReStructuredText
Raw Normal View History

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