emsha/doc/sphinx/source/sha256.rst

-----------------
The SHA256 class
-----------------

.. cpp:class:: emsha::SHA256

   SHA256 is an implementation of the :cpp:class:`emsha::Hash`
   interface.

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