Merge pull request #20 from hadielyakhni/KT256

Add KT256

.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

Makefile.build

@@ -79,7 +79,7 @@ http://creativecommons.org/publicdomain/zero/1.0/
     </fragment>
 
     <!-- To run many tests -->
-    <fragment name="K12Tests" inherits="common KangarooTwelve">
+    <fragment name="KTtests" inherits="common KangarooTwelve">
         <c>tests/main.c</c>
         <c>tests/testPerformance.c</c>
         <c>tests/timing.c</c>
@@ -92,9 +92,9 @@ http://creativecommons.org/publicdomain/zero/1.0/
     </fragment>
 
     <!-- To make a library -->
-    <fragment name="libk12.a" inherits="KangarooTwelve"/>
-    <fragment name="libk12.so" inherits="KangarooTwelve"/>
-    <fragment name="libk12.dylib" inherits="KangarooTwelve"/>
+    <fragment name="libKT.a" inherits="KangarooTwelve"/>
+    <fragment name="libKT.so" inherits="KangarooTwelve"/>
+    <fragment name="libKT.dylib" inherits="KangarooTwelve"/>
 
     <!-- Generically optimized 32-bit implementation -->
     <fragment name="generic32" inherits="inplace32bi"/>
@@ -112,7 +112,7 @@ http://creativecommons.org/publicdomain/zero/1.0/
     <group all="all">
         <product delimiter="/">
             <factor set="generic32 generic64 generic64noAsm plain64 ARMv8Asha3"/>
-            <factor set="K12Tests libk12.a libk12.so libk12.dylib"/>
+            <factor set="KTtests libKT.a libKT.so libKT.dylib"/>
         </product>
     </group>
 </build>

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