sleeping_kangaroo12 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4aacaa549cb9d7beeef6977f03383868f29fb143cb35820a02fdbb8fa408ab1
-  data.tar.gz: e8c27359938bac4abebe69f71de89b4dcfad1880263c5f701af519e9c6a59741
+  metadata.gz: 7453def4dc8a8e3a1c2969eae931609fea5407fdba11a56e8e14fd5a09325b5f
+  data.tar.gz: ad708b12872beef715a367ba32ecefb0c869fb969a88df41a15fc3cac7379f43
 SHA512:
-  metadata.gz: e857ff9f05810ffb2f3ec55ef881f839563c7fe856f973075295b4ecd2cfa14ff864d32aaaadf4142a0fbea5fbef353077ef3a0cf8c58414bbed1eb81caee445
-  data.tar.gz: 7fa8d7a961a56d25aedd0371e75db9c24874c1812bafc43495084171762d93cc21ae3435fe68ce0f2aaa6caa6f38afb512b1ec7cd276202c372c62e1e44a1e62
+  metadata.gz: 1ec13969d3b64f83c29a4b2b7653cc080f442b0818f9e5f818fd2c8ca139b658f9692832f9d9a046320cf16d5988240c06bddc5fd3de3ce0faa920b1af0abb56
+  data.tar.gz: 748c612b41ff1460dad89f1e122b466cb052089d95eb552557c6f0ef229ce74ad5d214e9f5d371464dc93aaa65db412af284dafbb83eb62d5bccab413943f84b

data/LICENSE.md

@@ -0,0 +1,27 @@
+# BSD 3-Clause License
+
+_Copyright © `2022`, `Sarun Rattanasiri`_  
+_All rights reserved._
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of the copyright holder nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -1,5 +1,8 @@
 # SleepingKangaroo12
 
+[![GitHub version](https://badge.fury.io/gh/the-cave%2Fsleeping-kangaroo12.svg)](https://badge.fury.io/gh/the-cave%2Fsleeping-kangaroo12)
+[![Gem Version](https://badge.fury.io/rb/sleeping_kangaroo12.svg)](https://badge.fury.io/rb/sleeping_kangaroo12)
+
 ## What is it?
 
 SleepingKangaroo12 is a Ruby binding of [KangarooTwelve](https://keccak.team/kangarootwelve.html), a fast cryptographic
@@ -25,29 +28,22 @@ gem is sleeping. :-D
 
 ## What are specials?
 
-Many!  
-Just take a peek at the code, you'll notice that:
-
-- It builds on top of the [eXtended Keccak Code Package (XKCP)](https://github.com/XKCP/XKCP), an easy-to-use and highly
+- It builds on top of the [K12](https://github.com/XKCP/K12), an easy-to-use and highly
   optimized library maintained by the Keccak team themselves.
-- The binding auto-select and detects CPU features on installation, it supports `AVX512`, `AVX2`, and `SSSE3`
-  instruction sets out of the box. And able to run on a machine without special instruction sets.
-- Thin and stable binding; designed by a proper software architect
+- The instruction set `AVX512`, `AVX2`, and `SSSE3` will be detected at runtime to select the optimization dynamically.
+- Thin and stable binding layer
 - Not limited to [Matz's Ruby Interpreter (MRI)](https://en.wikipedia.org/wiki/Ruby_MRI), this is due to the gem opting
-  for [Ruby-FFI](https://github.com/ffi/ffi) instead of native extensions.
+  for [Ruby-FFI](https://github.com/ffi/ffi) instead of using the API exposed by `ruby.h`.
   (I only tested on MRI, though.)
-- Compared to other hash functions, this binding actually shipped with the optimized implementation. Some
-  other hash function might looks more performant on benchmarks, this may or may not translated to real-world
-  performance.
 
 ## Prerequisites
 
-In order to install the gem, your machine should be ready to build the XKCP package. Which mean you should prepare:
+In order to install the gem, your machine should be ready to build the K12 package. Which mean you should prepare:
 
 - GCC, the GNU Compiler Collection; our favorite
 - GNU make
 - xsltproc executable, normally comes with libxslt package
-- And for the sake of completeness: Ruby, Bundler, and Ruby related stuffs
+- Ruby related stuffs
 
 ## Installation
 
@@ -68,60 +64,59 @@ from [konsolebox/digest-kangarootwelve-ruby](https://github.com/konsolebox/diges
 binding.
 
 ~~~ruby
-# Shortcuts
-#
-::SleepingKangaroo12::Digest.digest('abc')
-# Output: "\xAB\x17O2\x8CU\xA5Q\v\v \x97\x91\xBF\x8B`\xE8\x01\xA7\xCF\xC2\xAAB\x04-\xCB\x8FT\x7F\xBE:}"
-#
+# basic usage
 ::SleepingKangaroo12::Digest.hexdigest('abc')
-# Output: "ab174f328c55a5510b0b209791bf8b60e801a7cfc2aa42042dcb8f547fbe3a7d"
+# => "ab174f328c55a5510b0b209791bf8b60e801a7cfc2aa42042dcb8f547fbe3a7d"
 
-# Multiple updates
-#
+# streaming
 digest = ::SleepingKangaroo12::Digest.new
-digest.update('a')
-digest.update('b')
-digest.update('c')
+digest << 'a'
+digest << 'b'
+digest << 'c'
 digest.hexdigest
-# Output: "ab174f328c55a5510b0b209791bf8b60e801a7cfc2aa42042dcb8f547fbe3a7d"
+# => "ab174f328c55a5510b0b209791bf8b60e801a7cfc2aa42042dcb8f547fbe3a7d"
+# `<<` is an alias of `update`, use the one you like
 
-# Hashing with a key, similar to HMAC
-# KangarooTwelve call the key "customization", it is the same thing, FYI
-#
+# keyed hash (AKA: customization)
 digest = ::SleepingKangaroo12::Digest.new(key: 'secret')
 digest << 'abc' # alternate form of update method
 digest.hexdigest
-# Output: "dc1fd53f85402e2b34fa92bd87593dd9c3fe6cc49d9db6c05dc0cf26c6a7e03f"
-# HMAC requires 2 parses of hashing, the customization is definitely faster
+# => "dc1fd53f85402e2b34fa92bd87593dd9c3fe6cc49d9db6c05dc0cf26c6a7e03f"
 
-# You can control the output length too
-#
-digest = ::SleepingKangaroo12::Digest.new(key: 'secret', output_length: 5)
-digest << 'abc'
-digest.hexdigest
-# Output: "dc1fd53f85"
-# This is marginally faster than truncating the output yourself.
-#
-digest = ::SleepingKangaroo12::Digest.new(key: 'secret', output_length: 64)
+# shortcuts
+::SleepingKangaroo12::Digest.digest('abc')
+# => "\xAB\x17O2\x8CU\xA5Q\v\v \x97\x91\xBF\x8B`\xE8\x01\xA7\xCF\xC2\xAAB\x04-\xCB\x8FT\x7F\xBE:}"
+::SleepingKangaroo12::Digest.hexdigest('abc', key: 'secret')
+# => "dc1fd53f85402e2b34fa92bd87593dd9c3fe6cc49d9db6c05dc0cf26c6a7e03f"
+::SleepingKangaroo12::Digest.base64digest('abc', output_length: 24)
+# => "qxdPMoxVpVELCyCXkb+LYOgBp8/CqkIE"
+# `digest`, `hexdigest`, and `base64digest` are available as shortcuts and also on `Digest` instances.
+# Same for the options, you may use `key`, `key_seed`, and `output_length` on both instance methods and shortcuts
+
+# XOF (extendable-output functions)
+digest = ::SleepingKangaroo12::Digest.new(output_length: 64)
 digest << 'abc'
 digest.hexdigest
-# Output: "dc1fd53f85402e2b34fa92bd87593dd9c3fe6cc49d9db6c05dc0cf26c6a7e03fc4b18c621b57dbb8967094b160dbf22ee42402d7e3d45ecab4b02ef0db14b105"
-# The output is longer now, but the security claim is still the same.
-# (as 256-bit output length, which translated to the security level of 128-bit)
-
-# Weird parameters
-#
-digest = ::SleepingKangaroo12::Digest.new(key: 'secret', output_length: 1_000_000_000_000)
-# This will error; I arbitrary set the limit at 1MiB - 1 bytes as a safety measure. Same for length <= 0
-# If you have a use case for something out of range, feel free to discuss.
-# You are probably looking for a stream cipher instead of a hash function, though.
+# => "ab174f328c55a5510b0b209791bf8b60e801a7cfc2aa42042dcb8f547fbe3a7d3f5b54d116a705d36aac2a7eac7a19e3f0f058cb3c238ac7f034178ae34f212e"
 
-# The options work with shortcuts too
-# 
-::SleepingKangaroo12::Digest.hexdigest('abc', key: 'secret')
-# Output: "dc1fd53f85402e2b34fa92bd87593dd9c3fe6cc49d9db6c05dc0cf26c6a7e03f"
+# weird parameters
+::SleepingKangaroo12::Digest.new(key: 'secret', output_length: 1_000_000_000_000)
+# error: Hash length out of range (ArgumentError)
+# I arbitrary set the limit of output length at 1MiB - 1 bytes as a safety measure. Same for length <= 0
+# If you have a use case for something out of range, feel free to discuss.
 ~~~
 
+## About CPU Throttling
+
+At the time of this writing, if you use a lot of AVX-512, your CPU would heat up significantly; this leads to frequency throttling.
+
+If you plan to use KangarooTwelve heavily yet still have other functionalities impacted by lower CPU frequencies
+(like [Cloudflare](https://blog.cloudflare.com/on-the-dangers-of-intels-frequency-scaling/)),
+you may want to customize the build to prevent the throttling.
+
+If that is the case, please check [konsolebox/digest-kangarootwelve-ruby](https://github.com/konsolebox/digest-kangarootwelve-ruby).
+At the time of this writing, they offer customizable build; in contrast, SleepingKangaroo12 will focus on ease of use.
+
 ## License
 
 SleepingKangaroo12 is released under the [BSD 3-Clause License](LICENSE.md). :tada:

data/ext/Rakefile

@@ -9,6 +9,9 @@ platform = ::SleepingKangaroo12::Build::Platform.instance
 out_dir = "#{platform.arch}-#{platform.os}"
 lib_name = ::File.join(out_dir, platform.map_library_name('SleepingKangaroo12'))
 
+k12_prefix = 'k12/bin/'
+build_prefix = 'bin/.build/'
+
 feature_set = ::POSIX::Spawn::Child.new('gcc -march=native -dM -E - < /dev/null').then(&:out).then do |output|
   output.lines.select do |line|
     line.include?('AVX') || line.include?('SSE') || line.include?('64')
@@ -19,55 +22,27 @@ end.each_with_object(::Set.new) do |line, accumulator|
   accumulator << matched[1]
 end
 
-static_target = if feature_set.include?('__AVX512F__') && feature_set.include?('__AVX512VL__')
-  'libK12-avx512.a'
-elsif feature_set.include?('__AVX2__') && feature_set.include?('__SSSE3__')
-  'libK12-avx2-ssse3.a'
-elsif feature_set.include?('__AVX2__')
-  'libK12-avx2.a'
-elsif feature_set.include?('__LP64__') && feature_set.include?('__SSSE3__')
-  'libK12-ssse3-64.a'
-elsif feature_set.include?('__LP64__')
-  'libK12-generic-64.a'
-elsif feature_set.include?('__SSSE3__')
-  'libK12-ssse3.a'
+static_target = if feature_set.include?('__LP64__')
+  'generic64/libk12.a'
 else
-  'libK12-generic.a'
+  'generic32/libk12.a'
 end
 
-xkcp_static_target = "xkcp/bin/#{static_target}"
-
 task default: [lib_name]
 
-file lib_name => FileList['bin/.build/sleeping_kangaroo12.o', xkcp_static_target] do |t|
+file lib_name => FileList["#{build_prefix}sleeping_kangaroo12.o", "#{k12_prefix}#{static_target}"] do |t|
   ::FileUtils.mkdir_p(::File.dirname(t.name))
   static_lib = t.prerequisites.last
   static_lib_dir = ::File.dirname(static_lib)
   static_lib_file = ::File.basename(static_lib)
-  sh "gcc -shared -o #{t.name} #{t.prerequisites.first} -L#{static_lib_dir} -l:#{static_lib_file} -lm -lc"
-end
-
-file 'bin/.build/sleeping_kangaroo12.o' => FileList['binding/sleeping_kangaroo12.c', xkcp_static_target] do |t|
-  sh "gcc -Wall -Wa,-adhln -O3 -march=native -I./xkcp/bin -c #{t.prerequisites.first} -o #{t.name}"
+  sh "gcc -shared -flto -o #{t.name} #{t.prerequisites.first} -L#{static_lib_dir} -l:#{static_lib_file} -lm -lc"
 end
 
-file xkcp_static_target => FileList['bin/.build/Makefile'] do |t|
-  file_name = ::File.basename(t.name)
-  sh "cd xkcp && make -f ../#{t.prerequisites.first} #{file_name}"
-end
-
-desc 'Generate XKCP\'s Makefile'
-file 'bin/.build/Makefile' => FileList['bin/.build/Makefile.expanded'] do |t|
+file "#{build_prefix}sleeping_kangaroo12.o" => FileList['binding/sleeping_kangaroo12.c', "#{k12_prefix}#{static_target}"] do |t|
   ::FileUtils.mkdir_p(::File.dirname(t.name))
-  sh "cd xkcp && xsltproc --xinclude -o ../#{t.name} support/Build/ToGlobalMakefile.xsl ../#{t.prerequisites.last}"
-  # rewrite Makefile path
-  original_make = ::File.read(t.name)
-  modified_make = original_make.gsub(%r{(\s+)(bin/.build/Makefile)}, '\1../\2')
-  ::File.write(t.name, modified_make, mode: 'wb')
+  sh "gcc -Wall -O3 -fPIC -flto -I#{::File.dirname(t.prerequisites.last)} -c #{t.prerequisites.first} -o #{t.name}"
 end
 
-desc 'Expand XKCP\'s Makefile'
-file 'bin/.build/Makefile.expanded' => FileList['config/xkcp.build'] do |t|
-  ::FileUtils.mkdir_p(::File.dirname(t.name))
-  sh "cd xkcp && xsltproc --xinclude -o ../#{t.name} support/Build/ExpandProducts.xsl ../#{t.prerequisites.last}"
+file "#{k12_prefix}#{static_target}" => FileList['k12/Makefile'] do |_t|
+  sh "cd k12 && (CFLAGS=\"-fPIC -flto\" ASMFLAGS=\"-fPIC -flto\" make #{static_target})"
 end

data/ext/binding/sleeping_kangaroo12.c

@@ -1,20 +1,5 @@
-#if defined(__AVX512F__) && defined(__AVX512VL__)
-  #include "libK12-avx512.a.headers/KangarooTwelve.h"
-#elif defined(__AVX2__) && defined(__SSSE3__)
-  #include "libK12-avx2-ssse3.a.headers/KangarooTwelve.h"
-#elif defined(__AVX2__)
-  #include "libK12-avx2.a.headers/KangarooTwelve.h"
-#elif defined(__LP64__) && defined(__SSSE3__)
-  #include "libK12-ssse3-64.a.headers/KangarooTwelve.h"
-#elif defined(__LP64__)
-  #include "libK12-generic-64.a.headers/KangarooTwelve.h"
-#elif defined(__SSSE3__)
-  #include "libK12-ssse3.a.headers/KangarooTwelve.h"
-#else
-  #include "libK12-generic.a.headers/KangarooTwelve.h"
-#endif
-
 #include <stdlib.h>
+#include "libk12.a.headers/KangarooTwelve.h"
 
 void * SleepingKangaroo12_Init(int outputLength) {
   KangarooTwelve_Instance *retVal = malloc(sizeof (KangarooTwelve_Instance)); // TODO: check result

data/ext/k12/Makefile.build

@@ -0,0 +1,118 @@
+<?xml version="1.0"?>
+<!--
+K12 based on the eXtended Keccak Code Package (XKCP)
+https://github.com/XKCP/XKCP
+
+KangarooTwelve, designed by Guido Bertoni, Joan Daemen, Michaël Peeters, Gilles Van Assche, Ronny Van Keer and Benoît Viguier.
+
+Implementation by Gilles Van Assche and Ronny Van Keer, hereby denoted as "the implementer".
+
+For more information, feedback or questions, please refer to the Keccak Team website:
+https://keccak.team/
+
+To the extent possible under law, the implementer has waived all copyright
+and related or neighboring rights to the source code in this file.
+http://creativecommons.org/publicdomain/zero/1.0/
+-->
+<build xmlns:xi="http://www.w3.org/2001/XInclude">
+
+    <fragment name="optimized">
+        <gcc>-fomit-frame-pointer</gcc>
+        <gcc>-O2</gcc>
+        <gcc>-g0</gcc>
+    </fragment>
+
+    <!-- Keccak-p[1600] -->
+
+    <fragment name="inplace32bi" inherits="optimized">
+        <c>lib/Inplace32BI/KeccakP-1600-inplace32BI.c</c>
+        <h>lib/Inplace32BI/KeccakP-1600-SnP.h</h>
+    </fragment>
+
+    <fragment name="optimized64" inherits="optimized">
+        <c>lib/Optimized64/KeccakP-1600-opt64.c</c>
+        <h>lib/Optimized64/KeccakP-1600-SnP.h</h>
+        <s>lib/Optimized64/KeccakP-1600-AVX2.s</s>
+        <s>lib/Optimized64/KeccakP-1600-AVX512.s</s>
+        <c gcc="-mssse3">lib/Optimized64/KeccakP-1600-timesN-SSSE3.c</c>
+        <c gcc="-mavx2">lib/Optimized64/KeccakP-1600-timesN-AVX2.c</c>
+        <c gcc="-mavx512f -mavx512vl">lib/Optimized64/KeccakP-1600-timesN-AVX512.c</c>
+        <c>lib/Optimized64/KeccakP-1600-runtimeDispatch.c</c>
+    </fragment>
+
+    <fragment name="optimized64noAsm" inherits="optimized">
+        <c>lib/Optimized64/KeccakP-1600-opt64.c</c>
+        <c gcc="-mavx512f -mavx512vl">lib/Optimized64/KeccakP-1600-AVX512-plainC.c</c>
+        <h>lib/Optimized64/KeccakP-1600-SnP.h</h>
+        <c gcc="-mssse3">lib/Optimized64/KeccakP-1600-timesN-SSSE3.c</c>
+        <c gcc="-mavx2">lib/Optimized64/KeccakP-1600-timesN-AVX2.c</c>
+        <c gcc="-mavx512f -mavx512vl">lib/Optimized64/KeccakP-1600-timesN-AVX512.c</c>
+        <c>lib/Optimized64/KeccakP-1600-runtimeDispatch.c</c>
+        <define>KeccakP1600_noAssembly</define>
+    </fragment>
+
+    <fragment name="optimized64plain" inherits="optimized">
+        <c>lib/Optimized64/KeccakP-1600-opt64.c</c>
+        <c>lib/Plain64/KeccakP-1600-plain64.c</c>
+        <h>lib/Plain64/KeccakP-1600-SnP.h</h>
+    </fragment>
+
+    <fragment name="ARMv8Asha3" inherits="optimized">
+        <c gcc="-march=armv8.4-a+sha3">lib/ARMv8Asha3/KeccakP-1600-opt64.c</c>
+        <s gcc="-march=armv8.4-a+sha3">lib/ARMv8Asha3/KeccakP-1600-ARMv8Asha3.S</s>
+        <h>lib/ARMv8Asha3/KeccakP-1600-SnP.h</h>
+    </fragment>
+
+    <!-- KangarooTwelve -->
+
+    <fragment name="KangarooTwelve">
+        <h>lib/align.h</h>
+        <c>lib/KangarooTwelve.c</c>
+        <h>lib/KangarooTwelve.h</h>
+    </fragment>
+
+    <!-- For the name of the targets, please see the end of this file. -->
+
+    <fragment name="common">
+        <h>lib/align.h</h>
+        <h>lib/brg_endian.h</h>
+    </fragment>
+
+    <!-- To run many tests -->
+    <fragment name="K12Tests" inherits="common KangarooTwelve">
+        <c>tests/main.c</c>
+        <c>tests/testPerformance.c</c>
+        <c>tests/timing.c</c>
+        <h>tests/timing.h</h>
+        <h>tests/testPerformance.h</h>
+        <c>tests/testKangarooTwelve.c</c>
+        <h>tests/testKangarooTwelve.h</h>
+        <gcc>-lm</gcc>
+        <define>KeccakP1600_enable_simd_options</define>
+    </fragment>
+
+    <!-- To make a library -->
+    <fragment name="libk12.a" inherits="KangarooTwelve"/>
+    <fragment name="libk12.so" inherits="KangarooTwelve"/>
+    <fragment name="libk12.dylib" inherits="KangarooTwelve"/>
+
+    <!-- Generically optimized 32-bit implementation -->
+    <fragment name="generic32" inherits="inplace32bi"/>
+
+    <!-- Generically optimized 64-bit implementation, including SSSE3, AVX2 and AVX512 -->
+    <fragment name="generic64" inherits="optimized64"/>
+
+    <!-- Same, but without the assembly file (for MS Visual Studio) -->
+    <fragment name="generic64noAsm" inherits="optimized64noAsm"/>
+
+    <!-- Plain C optimized 64-bit implementation only -->
+    <fragment name="plain64" inherits="optimized64plain"/>
+
+    <!-- Target names are of the form x/y where x is taken from the first set and y from the second set. -->
+    <group all="all">
+        <product delimiter="/">
+            <factor set="generic32 generic64 generic64noAsm plain64 ARMv8Asha3"/>
+            <factor set="K12Tests libk12.a libk12.so libk12.dylib"/>
+        </product>
+    </group>
+</build>

data/ext/k12/README.markdown

@@ -0,0 +1,86 @@
+[![Build Status](http://img.shields.io/travis/XKCP/K12.svg)](https://travis-ci.org/XKCP/K12)
+
+# 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.
+
+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.
+
+More details can be found in our [ACNS Paper][eprint].
+
+# 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.
+
+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.
+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 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.
+
+
+# Is there a tool to compute the K12 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?
+
+This repository uses the same build system as that of the XKCP.
+To build, the following tools are needed:
+
+* *GCC*
+* *GNU make*
+* *xsltproc*
+
+The different targets are defined in [`Makefile.build`](Makefile.build). This file is expanded into a regular makefile using *xsltproc*. To use it, simply type, e.g.,
+
+```
+make generic64/K12Tests
+```
+
+to build K12Tests generically optimized for 64-bit platforms. The name before the slash indicates the platform, while the part after the slash is the executable to build. As another example, the static (resp. dynamic) library is built by typing `make generic64/libK12.a` (resp. `.so`) or similarly with `generic64` replaced with the appropriate platform name.  An alternate C compiler can be specified via the `CC` environment variable.
+
+Instead of building an executable with *GCC*, one can choose to select the files needed and make a package. For this, simply append `.pack` to the target name, e.g.,
+
+```
+make generic64/K12Tests.pack
+```
+
+This creates a `.tar.gz` archive with all the necessary files to build the given target.
+
+The list of targets can be found at the end of [`Makefile.build`](Makefile.build) or by running `make` without parameters.
+
+## Microsoft Visual Studio support
+
+KangarooTwelve can be compiled with Microsoft Visual Studio (MSVC). The XKCP build system offers support for the creation of project files. To get a project file for a given target, simply append `.vcxproj` to the target name, e.g.,
+
+```
+make generic64noAsm/K12Tests.vcxproj
+```
+
+The targets `generic32` and `generic64noAsm` can be used with MSVC, but not `generic64` as it contains assembly implementations in the GCC syntax, which at this point cannot be used with MSVC.
+Please refer to the documention of [XKCP][xkcp] for more details on the limitations of the support of MSVC.
+
+[k12]: https://keccak.team/kangarootwelve.html
+[xkcp]: https://github.com/XKCP/XKCP
+[eprint]: https://eprint.iacr.org/2016/770.pdf
+
+
+# Acknowledgments
+
+We wish to thank:
+
+- Andy Polyakov for his expertise with the ARMv8-A+SHA3 code, and in particular for his core routine from [CRYPTOGAMS](https://github.com/dot-asm/cryptogams)
+- 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