sha3
20180228
Secure Hash Algorithm 3 (Keccak) Implementation
Upstream URL
Author
Maintainer
License
This library is an implementation of the Secure Hash Algorithm 3 (SHA3), also known as Keccak. The implementation is constrained to messages with an integral number of octets, i.e. subbyte 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 sha3update with partial buffers could lead to input data being ignored and therefore erroneous message digests being generated. Uses with only one call to sha3update and the highlevel routines were not affected by this bug.
NOTE that prior to release 1.1.0 this package computed digests
based on the Keccak submission to the SHA3 contest and did not
yet take into account the added suffix that the FIPS 202 SHA3
final standard adds to messages prior to calculating the digest,
since this was not part of the Keccak submission. Starting with
1.1.0 the functions in the sha3 package do by default calculate
disgests that match the FIPS 202 standard, and will calculate
the old prestandard digests only if the new optional keyword
argument :rawkeccakp
is passed with a true value.
The code should be portable across nearly all ANSI compliant CL implementations with specialized versions tuned for implementations that offer unboxed 64bit arithmetic, unboxed 32bit arithmetic and for implementations with efficient fixnum arithmetic (requiring fixnums that can represent (unsignedbyte 16)). Especially the 64 and 32bit implementations have been mostly optimized for SBCL and CMU CL. For those implementations, digests with a 1024 bitrate (and 288 bit digest output) can be generated in between 30 (64bit SBCL) to around 100 (32bit CMU CL) cycles/byte on an i7640M; whereas optimized C/assembler implementations reach around 12 to 50 cycles/byte on 64/32 bit Intel hardware. The reason for the discrepancy probably lies in missing peephole and dependency optimizations in the SBCL/CMU CL compiler backend.
The midlevel interfaces to the digest routines are the functions

sha3:sha3init &key outputbitlength bitrate
Create and return a new SHA3 state. If
outputbitlength
is specified then the state will run at the bit rate specified for the given output bit length. Ifoutputbitlength
is unspecified,bitrate
can be specified to select a suitable bit rate. If both are left unspecified then a default bit rate of 1024 bits is selected, which is suitable for arbitrary output bit lengths of up to 288 bits. 
sha3:sha3copy state
Return an independent copy of the SHA3 state
state
. 
sha3:sha3statep state
Test whether a given object is a SHA3 state, i.e. is an instance of the class
sha3:sha3state
. 
sha3:sha3update state vector &key (start 0) (end (length vector))
Update the given SHA3 state
state
fromvector
, which must be a simplearray with elementtype (unsignedbyte 8), bounded bystart
andend
, which must be numeric boundingindices. 
sha3:sha3final state &key outputbitlength rawkeccakp
If the given SHA3 state
state
has not already been finalized, finalize it by processing any remaining input in its buffer, with the specified suffix of 01 and suitable padding as specified by the SHA3 standard (the specified SHA3 suffix can be elided with the optional keyword argumentrawkeccakp
to generate digests as the initial Keccak submission would have generated). Returns the message digest as asimplearray
of(unsignedbyte 8)
. The length of the returned digest is determined either by the output bit length or bit rate specified on state creation, or for the special case of default parameters being used, by the optional keyword argumentoutputbitlength
. If the state has previously been finalized, the function will return the digest again.
For convenience the following highlevel functions produce digests in
one step from 1d simplearrays and streams with elementtype
(unsignedbyte 8)
, as well as files:

sha3:sha3digestvector vector &key (start 0) end (outputbitlength 512) rawkeccakp
Calculate an SHA3 messagedigest of data in
vector
, which should be a 1d simplearray with element type(unsignedbyte 8)
, bounded bystart
andend
. The bit length of the message digest produced is controlled byoutputbitlength
, which can take on the values 224, 256, 288, 384 and 512, which is the default value. Using the optionalrawkeccakp
keyword argument the SHA3 mandated 01 suffix that is appended to the actual message prior to padding can be elided to yield message digests that match the original Keccak submission instead of the actual SHA3 standard. Use this option only for compatibility with historical implementations. 
sha3:sha3digeststream stream &key (outputbitlength 512) rawkeccakp
Calculate an SHA3 messagedigest of data read from
stream
, which should be astream
with element type(unsignedbyte 8)
. The bit length of the message digest produced is controlled byoutputbitlength
, which can take on the values 224, 256, 288, 384 and 512, which is the default value. Using the optionalrawkeccakp
keyword argument the SHA3 mandated 01 suffix that is appended to the actual message prior to padding can be elided to yield message digests that match the original Keccak submission instead of the actual SHA3 standard. Use this option only for compatibility with historical implementations. 
sha3:sha3digestfile pathname &key (outputbitlength 512) rawkeccakp
Calculate an SHA3 messagedigest of the file specified by
pathname
. The bit length of the message digest produced is controlled byoutputbitlength
, which can take on the values 224, 256, 288, 384 and 512, which is the default value. Using the optionalrawkeccakp
keyword argument the SHA3 mandated 01 suffix that is appended to the actual message prior to padding can be elided to yield message digests that match the original Keccak submission instead of the actual SHA3 standard. Use this option only for compatibility with historical implementations.
Note that in order to generate a message digest of a string it will
have to be converted to a simplearray
with elementtype
(unsignedbyte 8)
in the proper outputencoding. This will have to
rely on implementationspecific functions and is not part of the SHA3
library.
The file keccakreference.lisp
contains a slow simple reference
implementation, and testdriver code, which allows testing of the tuned
implementations against this reference and against test data available
from the Keccak Site at: http://keccak.noekeon.org/KeccakKAT3.zip
The testcases from the Keccak test data can be run with the following form:
(keccak:testkeccakmsgkat "/Path/To/MsgKatDirectory" (lambda (totalbits bitrate outputbits message) (declare (ignore totalbits bitrate)) (sha3:sha3digestvector message :outputbitlength outputbits :rawkeccakp t)))
The adapted SHA3 testcases from the Keccak Code Package test vectors available under https://github.com/gvanas/KeccakCodePackage/tree/master/TestVectors can be run with the following form:
(keccak:testsha3msgkat "/Path/To/MsgKatDirectory" (lambda (totalbits bitrate outputbits message) (declare (ignore totalbits bitrate)) (sha3:sha3digestvector message :outputbitlength outputbits)))
This SHA3 implementation is licensed under the MITstyle license 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 Peeters and Gilles Van Assche, cf. http://keccak.team) for their algorithm and excellent documentation and reference implementations.
Please direct any feedback to pmai@pmsf.de. A git repository of this library is available under git://github.com/pmai/sha3.git