.. _stdlib_sha_256:

=======
SHA-256
=======

.. das:module:: sha_256

FIPS 180-4 SHA-256 in pure daslang: one-shot hashing of strings and byte arrays to lowercase hex, plus a streaming init/update/final state for data that arrives in pieces. Content addressing and integrity checks need a collision-resistant hash; the builtin 64-bit hash is not one.



++++++++++
Structures
++++++++++

.. _struct-sha_256-Sha256State:

.. das:attribute:: Sha256State

Streaming hash state. Create with ``sha256_init``; do not mutate directly.

:Fields: * **h** : uint\ [8] - Current hash values (eight 32-bit words).

         * **buf** : uint8\ [64] - Pending input block.

         * **bufLen** : int - Bytes buffered in the pending block.

         * **totalBytes** : uint64 - Total bytes absorbed so far.




++++++++++++++++
One-shot hashing
++++++++++++++++

  *  :ref:`sha256_hex (data: array\<uint8\>) : string <function-sha_256_sha256_hex_array_ls_uint8_gr_>`
  *  :ref:`sha256_hex (s: string) : string <function-sha_256_sha256_hex_string>`


sha256_hex
^^^^^^^^^^

.. _function-sha_256_sha256_hex_array_ls_uint8_gr_:

.. das:function:: sha256_hex(data: array<uint8>) : string

SHA-256 of a byte array, lowercase hex.


:Arguments: * **data** : array<uint8>

.. _function-sha_256_sha256_hex_string:

.. das:function:: sha256_hex(s: string) : string


+++++++++
Streaming
+++++++++

  *  :ref:`sha256_final (var st: Sha256State) : uint[8] <function-sha_256_sha256_final_Sha256State>`
  *  :ref:`sha256_hex_digest (digest: uint const[8]) : string <function-sha_256_sha256_hex_digest_uint_const_lb_8_rb_>`
  *  :ref:`sha256_init () : Sha256State <function-sha_256_sha256_init>`
  *  :ref:`sha256_update (var st: Sha256State; b: uint8) <function-sha_256_sha256_update_Sha256State_uint8>`
  *  :ref:`sha256_update (var st: Sha256State; data: array\<uint8\>) <function-sha_256_sha256_update_Sha256State_array_ls_uint8_gr_>`

.. _function-sha_256_sha256_final_Sha256State:

.. das:function:: sha256_final(st: Sha256State) : uint[8]

Apply FIPS 180-4 padding and return the digest as eight big-endian words.
The state is consumed — reuse requires a fresh ``sha256_init``.


:Arguments: * **st** :  :ref:`Sha256State <struct-sha_256-Sha256State>`

.. _function-sha_256_sha256_hex_digest_uint_const_lb_8_rb_:

.. das:function:: sha256_hex_digest(digest: uint const[8]) : string

Digest words → 64-char lowercase hex.


:Arguments: * **digest** : uint\ [8]

.. _function-sha_256_sha256_init:

.. das:function:: sha256_init() : Sha256State

Fresh streaming state (FIPS 180-4 initial hash values).



sha256_update
^^^^^^^^^^^^^

.. _function-sha_256_sha256_update_Sha256State_uint8:

.. das:function:: sha256_update(st: Sha256State; b: uint8)

Absorb one byte.


:Arguments: * **st** :  :ref:`Sha256State <struct-sha_256-Sha256State>`

            * **b** : uint8

.. _function-sha_256_sha256_update_Sha256State_array_ls_uint8_gr_:

.. das:function:: sha256_update(st: Sha256State; data: array<uint8>)