diff options
Diffstat (limited to 'docs/library/uhashlib.rst')
| -rw-r--r-- | docs/library/uhashlib.rst | 70 |
1 files changed, 57 insertions, 13 deletions
diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst index 708e3d7bc9..a8f580fd84 100644 --- a/docs/library/uhashlib.rst +++ b/docs/library/uhashlib.rst @@ -4,34 +4,78 @@ .. module:: uhashlib :synopsis: hashing algorithm -This module implements binary data hashing algorithms. Currently, it -implements SHA256 algorithm. Choosing SHA256 was a deliberate choice, -as a modern, cryptographically secure algorithm. This means that a -single algorithm can cover both usecases of "any hash algorithm" and -security-related usage, and thus save space omitting legacy algorithms -like MD5 or SHA1. +.. only:: port_pyboard + + This module implements binary data hashing algorithms. Currently, it + implements SHA256 algorithm. Choosing SHA256 was a deliberate choice, + as a modern, cryptographically secure algorithm. This means that a + single algorithm can cover both usecases of "any hash algorithm" and + security-related usage, and thus save space omitting legacy algorithms + like MD5 or SHA1. + +.. only:: port_wipy + + This module implements binary data hashing algorithms. Currently, it + implements SHA1 and SHA256 algorithms only. These two algorithms are + more than enough for today's web applications. + Constructors ------------ -.. class:: uhashlib.sha256([data]) +.. only:: port_pyboard - Create a hasher object and optionally feed ``data`` into it. + .. class:: uhashlib.sha256([data]) + + Create a 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 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) # lenght 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:: sha256.update(data) +.. method:: hash.update(data) Feed more binary data into hash. -.. method:: sha256.digest() +.. method:: hash.digest() Return hash for all data passed thru hash, as a bytes object. After this method is called, more data cannot be fed into hash any longer. -.. method:: sha256.hexdigest() + .. only:: port_wipy + + SHA1 hashes are 20-byte long. SHA256 hashes are 32-byte long. + +.. method:: hash.hexdigest() - This method is NOT implemented. Use ``ubinascii.hexlify(sha256.digest())`` - to achieve similar effect. + This method is NOT implemented. Use ``ubinascii.hexlify(hash.digest())`` + to achieve a similar effect. |