75 lines
2.5 KiB
ReStructuredText
75 lines
2.5 KiB
ReStructuredText
------------------
|
|
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.
|
|
|