OSCL/sha3
2
0
Fork 0
mirror of https://github.com/pmai/sha3.git synced 2025-12-21 23:34:29 +01:00
Code Issues Packages Projects Releases Wiki Activity

Change README to markdown syntax, add CI status

Browse Source
This commit is contained in:
Pierre R. Mai
2018-02-23 12:52:12 +01:00
parent 0aca46e76c
commit 55979bd429
1 changed files with 63 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
README → README.md
View File

@ -1,16 +1,18 @@
This library is an implementation of the Secure Hash Algorithm 3 [![Build Status](https://travis-ci.org/pmai/sha3.svg?branch=master)](https://travis-ci.org/pmai/sha3)
(SHA-3), also known as Keccak. The implementation is constrained to
messages with an integral number of octets, i.e. sub-byte length
messages are not supported.
NOTE that prior to release 1.0.2 this package had a bug in the This library is an implementation of the Secure Hash Algorithm 3
([SHA-3][]), also known as [Keccak][]. The implementation is
constrained to messages with an integral number of octets, i.e.
sub-byte length messages are not supported.
**NOTE** that prior to release 1.0.2 this package had a bug in the
generation of message digests where multiple calls to sha3-update generation of message digests where multiple calls to sha3-update
with partial buffers could lead to input data being ignored and with partial buffers could lead to input data being ignored and
therefore erroneous message digests being generated. Uses with therefore erroneous message digests being generated. Uses with
only one call to sha3-update and the high-level routines were not only one call to sha3-update and the high-level routines were not
affected by this bug. affected by this bug.
NOTE that prior to release 1.1.0 this package computed digests **NOTE** that prior to release 1.1.0 this package computed digests
based on the Keccak submission to the SHA-3 contest and did not based on the Keccak submission to the SHA-3 contest and did not
yet take into account the added suffix that the FIPS 202 SHA-3 yet take into account the added suffix that the FIPS 202 SHA-3
final standard adds to messages prior to calculating the digest, final standard adds to messages prior to calculating the digest,
@ -18,7 +20,7 @@ since this was not part of the Keccak submission. Starting with
1.1.0 the functions in the sha3 package do by default calculate 1.1.0 the functions in the sha3 package do by default calculate
disgests that match the FIPS 202 standard, and will calculate disgests that match the FIPS 202 standard, and will calculate
the old pre-standard digests only if the new optional keyword the old pre-standard digests only if the new optional keyword
argument :raw-keccak-p is passed with a true value. argument `:raw-keccak-p` is passed with a true value.
The code should be portable across nearly all ANSI compliant CL The code should be portable across nearly all ANSI compliant CL
implementations with specialized versions tuned for implementations implementations with specialized versions tuned for implementations
@ -36,95 +38,95 @@ compiler backend.
The mid-level interfaces to the digest routines are the functions The mid-level interfaces to the digest routines are the functions
- sha3:sha3-init &key output-bit-length bit-rate - `sha3:sha3-init &key output-bit-length bit-rate`
Create and return a new SHA-3 state. If `output-bit-length' is Create and return a new SHA-3 state. If `output-bit-length` is
specified then the state will run at the bit rate specified for the specified then the state will run at the bit rate specified for the
given output bit length. If `output-bit-length' is unspecified, given output bit length. If `output-bit-length` is unspecified,
`bit-rate' can be specified to select a suitable bit rate. If both `bit-rate` can be specified to select a suitable bit rate. If both
are left unspecified then a default bit rate of 1024 bits is are left unspecified then a default bit rate of 1024 bits is
selected, which is suitable for arbitrary output bit lengths of up selected, which is suitable for arbitrary output bit lengths of up
to 288 bits. to 288 bits.
- sha3:sha3-copy state - `sha3:sha3-copy state`
Return an independent copy of the SHA-3 state `state'. Return an independent copy of the SHA-3 state `state`.
- sha3:sha3-state-p state - `sha3:sha3-state-p state`
Test whether a given object is a SHA-3 state, i.e. is an instance of Test whether a given object is a SHA-3 state, i.e. is an instance of
the class sha3:sha3-state. the class `sha3:sha3-state`.
- sha3:sha3-update state vector &key (start 0) (end (length vector)) - `sha3:sha3-update state vector &key (start 0) (end (length vector))`
Update the given SHA-3 state `state' from `vector', which must be a Update the given SHA-3 state `state` from `vector`, which must be a
simple-array with element-type (unsigned-byte 8), bounded by `start' simple-array with element-type (unsigned-byte 8), bounded by `start`
and `end', which must be numeric bounding-indices. and `end`, which must be numeric bounding-indices.
- sha3:sha3-final state &key output-bit-length raw-keccak-p - `sha3:sha3-final state &key output-bit-length raw-keccak-p`
If the given SHA-3 state `state' has not already been finalized, If the given SHA-3 state `state` has not already been finalized,
finalize it by processing any remaining input in its buffer, with finalize it by processing any remaining input in its buffer, with
the specified suffix of 01 and suitable padding as specified by the the specified suffix of 01 and suitable padding as specified by the
SHA-3 standard (the specified SHA-3 suffix can be elided with the SHA-3 standard (the specified SHA-3 suffix can be elided with the
optional keyword argument `raw-keccak-p' to generate digests as the optional keyword argument `raw-keccak-p` to generate digests as the
initial Keccak submission would have generated). Returns the initial Keccak submission would have generated). Returns the
message digest as a simple-array of (unsigned-byte 8). The length message digest as a `simple-array` of `(unsigned-byte 8)`. The
of the returned digest is determined either by the output bit length length of the returned digest is determined either by the output bit
or bit rate specified on state creation, or for the special case of length or bit rate specified on state creation, or for the special
default parameters being used, by the optional keyword argument case of default parameters being used, by the optional keyword
`output-bit-length'. If the state has previously been finalized, argument `output-bit-length`. If the state has previously been
the function will return the digest again. finalized, the function will return the digest again.
For convenience the following high-level functions produce digests in For convenience the following high-level functions produce digests in
one step from 1d simple-arrays and streams with element-type one step from 1d simple-arrays and streams with element-type
(unsigned-byte 8), as well as files: `(unsigned-byte 8)`, as well as files:
- sha3:sha3-digest-vector vector &key (start 0) end (output-bit-length 512) raw-keccak-p - `sha3:sha3-digest-vector vector &key (start 0) end (output-bit-length 512) raw-keccak-p`
Calculate an SHA-3 message-digest of data in `vector', which should Calculate an SHA-3 message-digest of data in `vector`, which should
be a 1d simple-array with element type (unsigned-byte 8), bounded by be a 1d simple-array with element type `(unsigned-byte 8)`, bounded
`start' and `end'. The bit length of the message digest produced is by `start` and `end`. The bit length of the message digest produced
controlled by `output-bit-length', which can take on the values 224, is controlled by `output-bit-length`, which can take on the values
256, 288, 384 and 512, which is the default value. Using the optional 224, 256, 288, 384 and 512, which is the default value. Using the
`raw-keccak-p' keyword argument the SHA-3 mandated 01 suffix that is optional `raw-keccak-p` keyword argument the SHA-3 mandated 01 suffix
appended to the actual message prior to padding can be elided to yield that is appended to the actual message prior to padding can be elided
message digests that match the original Keccak submission instead of to yield message digests that match the original Keccak submission
the actual SHA-3 standard. Use this option only for compatibility instead of the actual SHA-3 standard. Use this option only for
with historical implementations. compatibility with historical implementations.
- sha3:sha3-digest-stream stream &key (output-bit-length 512) raw-keccak-p - `sha3:sha3-digest-stream stream &key (output-bit-length 512) raw-keccak-p`
Calculate an SHA-3 message-digest of data read from `stream', which Calculate an SHA-3 message-digest of data read from `stream`, which
should be a stream with element type (unsigned-byte 8). The bit should be a `stream` with element type `(unsigned-byte 8)`. The bit
length of the message digest produced is controlled by length of the message digest produced is controlled by
`output-bit-length', which can take on the values 224, 256, 288, 384 `output-bit-length`, which can take on the values 224, 256, 288, 384
and 512, which is the default value. Using the optional `raw-keccak-p' and 512, which is the default value. Using the optional `raw-keccak-p`
keyword argument the SHA-3 mandated 01 suffix that is appended to the keyword argument the SHA-3 mandated 01 suffix that is appended to the
actual message prior to padding can be elided to yield message digests actual message prior to padding can be elided to yield message digests
that match the original Keccak submission instead of the actual SHA-3 that match the original Keccak submission instead of the actual SHA-3
standard. Use this option only for compatibility with historical standard. Use this option only for compatibility with historical
implementations. implementations.
- sha3:sha3-digest-file pathname &key (output-bit-length 512) raw-keccak-p - `sha3:sha3-digest-file pathname &key (output-bit-length 512) raw-keccak-p`
Calculate an SHA-3 message-digest of the file specified by Calculate an SHA-3 message-digest of the file specified by
`pathname'. The bit length of the message digest produced is `pathname`. The bit length of the message digest produced is
controlled by `output-bit-length', which can take on the values 224, controlled by `output-bit-length`, which can take on the values 224,
256, 288, 384 and 512, which is the default value. Using the optional 256, 288, 384 and 512, which is the default value. Using the optional
`raw-keccak-p' keyword argument the SHA-3 mandated 01 suffix that is `raw-keccak-p` keyword argument the SHA-3 mandated 01 suffix that is
appended to the actual message prior to padding can be elided to yield appended to the actual message prior to padding can be elided to yield
message digests that match the original Keccak submission instead of message digests that match the original Keccak submission instead of
the actual SHA-3 standard. Use this option only for compatibility the actual SHA-3 standard. Use this option only for compatibility
with historical implementations. with historical implementations.
Note that in order to generate a message digest of a string it will Note that in order to generate a message digest of a string it will
have to be converted to a simple-array with element-type have to be converted to a `simple-array` with element-type
(unsigned-byte 8) in the proper output-encoding. This will have to `(unsigned-byte 8)` in the proper output-encoding. This will have to
rely on implementation-specific functions and is not part of the SHA3 rely on implementation-specific functions and is not part of the SHA3
library. library.
The file keccak-reference.lisp contains a slow simple reference The file `keccak-reference.lisp` contains a slow simple reference
implementation, and testdriver code, which allows testing of the tuned implementation, and testdriver code, which allows testing of the tuned
implementations against this reference and against test data available implementations against this reference and against test data available
from the Keccak Site at: http://keccak.noekeon.org/KeccakKAT-3.zip from the Keccak Site at: http://keccak.noekeon.org/KeccakKAT-3.zip
@ -132,28 +134,35 @@ from the Keccak Site at: http://keccak.noekeon.org/KeccakKAT-3.zip
The testcases from the Keccak test data can be run with the following The testcases from the Keccak test data can be run with the following
form: form:
```lisp
(keccak:test-keccak-msgkat (keccak:test-keccak-msgkat
"/Path/To/MsgKatDirectory" "/Path/To/MsgKatDirectory"
(lambda (total-bits bit-rate output-bits message) (lambda (total-bits bit-rate output-bits message)
(declare (ignore total-bits bit-rate)) (declare (ignore total-bits bit-rate))
(sha3:sha3-digest-vector message :output-bit-length output-bits :raw-keccak-p t))) (sha3:sha3-digest-vector message :output-bit-length output-bits :raw-keccak-p t)))
```
The adapted SHA-3 testcases from the Keccak Code Package test vectors The adapted SHA-3 testcases from the Keccak Code Package test vectors
available under https://github.com/gvanas/KeccakCodePackage/tree/master/TestVectors available under https://github.com/gvanas/KeccakCodePackage/tree/master/TestVectors
can be run with the following form: can be run with the following form:
```lisp
(keccak:test-sha3-msgkat (keccak:test-sha3-msgkat
"/Path/To/MsgKatDirectory" "/Path/To/MsgKatDirectory"
(lambda (total-bits bit-rate output-bits message) (lambda (total-bits bit-rate output-bits message)
(declare (ignore total-bits bit-rate)) (declare (ignore total-bits bit-rate))
(sha3:sha3-digest-vector message :output-bit-length output-bits))) (sha3:sha3-digest-vector message :output-bit-length output-bits)))
```
This SHA-3 implementation is licensed under the MIT-style license This SHA-3 implementation is licensed under the MIT-style license
contained in the file COPYING and the header of each source file. contained in the file COPYING and the header of each source file.
Many thanks go to the Keccak Team (Guido Bertoni, Joan Daemen, Michaël Many thanks go to the Keccak Team (Guido Bertoni, Joan Daemen, Michaël
Peeters and Gilles Van Assche, cf. http://keccak.noekeon.org) for Peeters and Gilles Van Assche, cf. http://keccak.team) for
their algorithm and excellent documentation and reference their algorithm and excellent documentation and reference
implementations. implementations.
Please direct any feedback to pmai@pmsf.de. A git repository of this Please direct any feedback to pmai@pmsf.de. A git repository of this
library is available under git://github.com/pmai/sha3.git library is available under git://github.com/pmai/sha3.git
[SHA-3]: https://en.wikipedia.org/wiki/SHA-3
[Keccak]: https://keccak.team/