diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 267cf4f..a965483 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -19,6 +19,6 @@ jobs: - name: Install xsltproc run: sudo apt-get install xsltproc - name: Build - run: make ${{ matrix.target }}/K12Tests ${{ matrix.target }}/libk12.a ${{ matrix.target }}/libk12.so + run: make ${{ matrix.target }}/KTtests ${{ matrix.target }}/libKT.a ${{ matrix.target }}/libKT.so - name: Test - run: bin/${{ matrix.target }}/K12Tests -K12 + run: bin/${{ matrix.target }}/KTtests -K12 diff --git a/Makefile.build b/Makefile.build index a0e1c55..3f1bc93 100644 --- a/Makefile.build +++ b/Makefile.build @@ -79,7 +79,7 @@ http://creativecommons.org/publicdomain/zero/1.0/ - + tests/main.c tests/testPerformance.c tests/timing.c @@ -92,9 +92,9 @@ http://creativecommons.org/publicdomain/zero/1.0/ - - - + + + @@ -112,7 +112,7 @@ http://creativecommons.org/publicdomain/zero/1.0/ - + diff --git a/README.markdown b/README.markdown index 4a85e1b..232aae0 100644 --- a/README.markdown +++ b/README.markdown @@ -1,37 +1,37 @@ # What is KangarooTwelve ? -[**KangarooTwelve**][k12] (or **K12**) is a fast and secure extendable-output function (XOF), the generalization of hash functions to arbitrary output lengths. -Derived from Keccak, it aims at higher speeds than FIPS 202's SHA-3 and SHAKE functions, while retaining their flexibility and basis of security. +[**KangarooTwelve**][k12] is a family of two (**KT128** and **KT256**) fast and secure extendable-output functions (XOF), the generalization of hash functions to arbitrary output lengths. +Derived from Keccak, they aim at higher speeds than FIPS 202's SHA-3 and SHAKE functions, while retaining their flexibility and basis of security. -On high-end platforms, it can exploit a high degree of parallelism, whether using multiple cores or the single-instruction multiple-data (SIMD) instruction set of modern processors. -On Intel's Haswell and Skylake architectures, KangarooTwelve tops at less than 1.5 cycles/byte for long messages on a single core, and at 0.51 cycles/byte on the SkylakeX and Cascade Lake architectures. -On the latest Apple A14 and M1 processors, KangarooTwelve can take advantage of the ARMv8-A's SHA-3 dedicated instructions to deliver 0.75 cycles/byte for long messages on a single core. -On low-end platforms, as well as for short messages, it also benefits from about a factor two speed-up compared to the fastest FIPS 202 instance SHAKE128. +On high-end platforms, they can exploit a high degree of parallelism, whether using multiple cores or the single-instruction multiple-data (SIMD) instruction set of modern processors. +On Intel's Haswell and Skylake architectures, KT128 tops at less than 1.5 cycles/byte for long messages on a single core, and at 0.51 cycles/byte on the SkylakeX and Cascade Lake architectures. +On the latest Apple A14 and M1 processors, KangarooTwelve can take advantage of the ARMv8-A's SHA-3 dedicated instructions and KT128 delivers 0.75 cycles/byte for long messages on a single core. +On low-end platforms, as well as for short messages, KT128 also benefits from about a factor two speed-up compared to the fastest FIPS 202 instance SHAKE128. -More details can be found in our [ACNS Paper][eprint]. +More details can be found in our [ACNS paper][eprint] (KT128 only) and in the [RFC draft](ietf). # What can I find here? -This repository contains source code that implements the extandable output (or hash) function [**KangarooTwelve**][k12] (or **K12**). -Its purpose is to offer optimized implementations of K12 and nothing else. +This repository contains source code that implements the extendable output (or hash) function **KT128** and **KT256**. +Its purpose is to offer optimized implementations of the KangarooTwelve and nothing else. -The code comes from the [**eXtended Keccak Code Package**][xkcp] (or **XKCP**), after much trimming to keep only what is needed for K12. -It is still structured like the XKCP in two layers. The lower layer implements the permutation Keccak-_p_[1600, 12] and possibly parallel versions thereof, whereas the higher layer implements the sponge construction and the K12 tree hash mode. +The code comes from the [**eXtended Keccak Code Package**][xkcp] (or **XKCP**), after much trimming to keep only what is needed for KT. +It is still structured like the XKCP in two layers. The lower layer implements the permutation Keccak-_p_[1600, 12] and possibly parallel versions thereof, whereas the higher layer implements the sponge construction and the tree hash mode. Also, some sources have been merged to reduce the file count. -* For the higher layer, we kept only the code needed for K12. -* For the lower layer, we removed all the functions that are not needed for K12. The lower layer therefore implements a subset of the SnP and PlSnP interfaces. +* For the higher layer, we kept only the code needed for KT. +* For the lower layer, we removed all the functions that are not needed for KT. The lower layer therefore implements a subset of the SnP and PlSnP interfaces. -For Keccak or Xoodoo-based functions other than K12 only, it is recommended to use the XKCP itself instead and not to mix both this repository and the XKCP. +For Keccak or Xoodoo-based functions other than KT128 and KT256, it is recommended to use the XKCP itself instead and not to mix both this repository and the XKCP. -# Is there a tool to compute the K12 hash of a file? +# Is there a tool to compute the hash of a file? Not in this repository, but Jack O'Connor's [`kangarootwelve_xkcp.rs` repository](https://github.com/oconnor663/kangarootwelve_xkcp.rs) contains Rust bindings to this code and a `k12sum` utility. Pre-built binaries can be found [there](https://github.com/oconnor663/kangarootwelve_xkcp.rs/releases). -# How can I build this K12 code? +# How can I build this code? This repository uses the same build system as that of the XKCP. To build, the following tools are needed: @@ -72,6 +72,7 @@ Please refer to the documention of [XKCP][xkcp] for more details on the limitati [k12]: https://keccak.team/kangarootwelve.html [xkcp]: https://github.com/XKCP/XKCP [eprint]: https://eprint.iacr.org/2016/770.pdf +[ietf]: https://datatracker.ietf.org/doc/draft-irtf-cfrg-kangarootwelve/ # Acknowledgments @@ -82,3 +83,4 @@ We wish to thank: - Duc Tri Nguyen for his benchmark on the Apple M1 - Jack O'Connor for bug fixes and more importantly for his [Rust bindings](https://github.com/oconnor663/kangarootwelve_xkcp.rs) - Kent Ross for his contributions to this code and its quality +- Hadi El Yakhni for adding KT256