circuitpython/docs/library/uhashlib.rst

86 lines
3.2 KiB
ReStructuredText

:mod:`uhashlib` -- hashing algorithms
=====================================
.. module:: uhashlib
:synopsis: hashing algorithms
This module implements binary data hashing algorithms. The exact inventory
of available algorithms depends on a board. Among the algorithms which may
be implemented:
* SHA256 - The current generation, modern hashing algorithm (of SHA2 series).
It is suitable for cryptographically-secure purposes. Included in the
MicroPython core and any board is recommended to provide this, unless
it has particular code size constraints.
* SHA1 - A previous generation algorithm. Not recommended for new usages,
but SHA1 is a part of number of Internet standards and existing
applications, so boards targetting network connectivity and
interoperatiability will try to provide this.
* MD5 - A legacy algorithm, not considered cryptographically secure. Only
selected boards, targetting interoperatibility with legacy applications,
will offer this.
Constructors
------------
.. class:: uhashlib.sha256([data])
Create an SHA256 hasher object and optionally feed ``data`` into it.
.. class:: uhashlib.sha1([data])
Create an SHA1 hasher object and optionally feed ``data`` into it.
.. class:: uhashlib.md5([data])
Create an MD5 hasher object and optionally feed ``data`` into it.
.. only:: port_wipy
.. class:: uhashlib.sha1([data[, block_size]])
Create a sha1 hasher object and optionally feed ``data`` or ``data and block_size`` into it.
.. class:: uhashlib.sha256([data[, block_size]])
Create a sha256 hasher object and optionally feed ``data`` or ``data and block_size`` into it.
.. admonition:: CPython extension
:class: attention
Due to hardware implementation details of the WiPy, data must be buffered before being
digested, which would make it impossible to calculate the hash of big blocks of data that
do not fit in RAM. In this case, since most likely the total size of the data is known
in advance, the size can be passed to the constructor and hence the HASH hardware engine
of the WiPy can be properly initialized without needing buffering. If ``block_size`` is
to be given, an initial chunk of ``data`` must be passed as well. **When using this extension,
care must be taken to make sure that the length of all intermediate chunks (including the
initial one) is a multiple of 4 bytes.** The last chunk may be of any length.
Example::
hash = uhashlib.sha1('abcd1234', 1001) # length of the initial piece is multiple of 4 bytes
hash.update('1234') # also multiple of 4 bytes
...
hash.update('12345') # last chunk may be of any length
hash.digest()
Methods
-------
.. method:: hash.update(data)
Feed more binary data into hash.
.. method:: hash.digest()
Return hash for all data passed through hash, as a bytes object. After this
method is called, more data cannot be fed into the hash any longer.
.. method:: hash.hexdigest()
This method is NOT implemented. Use ``ubinascii.hexlify(hash.digest())``
to achieve a similar effect.