From c2e21e502b5f4dba2994eed6df73121dba3c55db Mon Sep 17 00:00:00 2001 From: Peter Date: Sat, 1 Apr 2023 01:28:21 -0600 Subject: [PATCH] document squeeze phase --- docs/kek/README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) diff --git a/docs/kek/README.md b/docs/kek/README.md index b01ca92..fc66102 100644 --- a/docs/kek/README.md +++ b/docs/kek/README.md @@ -258,6 +258,12 @@ Both the absorption and squeezing phases invoke "inner keccak", which is where all the real bit-churning happens. (These are the Greek letter steps in the standard). +`inner_keccak/1` is a 1-arity function, and the input is just the sponge. It +scrambles the bits and does some `xor`ing and what not. The operation of +applying `inner_keccak/1` to a sponge to get a new sponge is called +**kekking**. This is vocabulary I invented and have found useful (you will not +find this in the official docs). + Just pay attention to the flow for now. - We take in our input (`Message`). @@ -412,7 +418,7 @@ The procedure is InnerKekInput : 1111101110 0100011010 1001111010 ... (1600 bits, result of xoring the two previous lines) ``` -3. Take the freshly xored sponge and pass it to `inner_keccak/1` +3. Take the freshly xored sponge and kek it 4. Repeat until you run out of `PaddedMessage` bits. @@ -444,6 +450,82 @@ absorb(<<>>, _r, _c, FinalSponge) -> FinalSponge. ``` +### Outer Keccak: Squeezing phase + +Again, the procedure is to "absorb" bits into the algorithm's state (the +"sponge"), and then "squeeze" them out. + +The way we squeeze them out is the opposite of the absorption procedure + +1. Grab `BitRate` bits off the front of the `WetSponge` +2. Concatenate them to our `ResultBits` +3. If we have enough `ResultBits`, return them +4. Otherwise, re-kek the `WetSponge` and try again. + +There is some commented out code here which I'm going to leave in. The reason +is it highlights that this procedure is trivial in the case of the SHA3-N +algorithms. For instance, SHA3-512 has a result length of 512 bits, and the +sponge is always 1600 bits long. So it is a 1-step procedure. + +For instance: + +``` +OutputBitLength = 512 +Capacity = 1024 = 2*OutputBitLength +BitRate = 576 = 1600 - Capacity +``` + +So in the SHA3-N cases, our "squeezing" phase really just amounts to grabbing N +bits off the front of the sponge. + +The squeezing phase only requires the re-kekking in the case of the SHAKE-N +algorithms where the `OutputBitLength > BitRate`. Even then, it only requires +iterative re-kekking if the user picks a very long `OutputBitLength` (remember +this is a free parameter in SHAKE-N). + +```erlang +%% https://github.com/pharpend/kek/blob/8a8a655a80c26ae32763cc25f1e0df8ab0653c82/kek.erl#L266-L300 + +-spec squeeze(WetSponge, OutputBitLength, BitRate) -> ResultBits + when WetSponge :: <<_:1600>>, + OutputBitLength :: pos_integer(), + BitRate :: pos_integer(), + ResultBits :: bitstring(). +%% @private +%% squeeze the output bits out of the sponge +%% @end + +%%% % simple case: bit length is less than (or equal to) the sponge size, just grab +%%% % the first ones +%%% % this is the case for the shas +%%% squeeze(<>, OutputBitLength, _BitRate) -> +%%% <>; +% general case: output bit length is greater than the sponge size, construct +% accumulatively +% this is the case for the variable-length encodings +squeeze(WetSponge, OutputBitLength, BitRate) -> + InitOutputAcc = <<>>, + really_squeeze(WetSponge, OutputBitLength, BitRate, InitOutputAcc). + +% terminal case: we have enough bits in the output, return those +really_squeeze(_WetSponge, OutputBitLength, _BitRate, FinalAccBits) when OutputBitLength =< bit_size(FinalAccBits) -> + <> = FinalAccBits, + <>; +% general case: need moar bits +% in this case +% - we grab the first r bits of the sponge, add them to the accumulator +% - re-kek the sponge +% - try again +really_squeeze(WetSponge, OutputBitLength, BitRate, ResultAcc)-> + <> = WetSponge, + NewResultAcc = <>, + NewWetSponge = inner_keccak(WetSponge), + really_squeeze(NewWetSponge, OutputBitLength, BitRate, NewResultAcc). +``` + +## Inner Keccak: the kek operation + + [german-lecture]: https://www.youtube.com/watch?v=JWskjzgiIa4 [german-lecture-notes]: https://www.crypto-textbook.com/download/Understanding-Cryptography-Keccak.pdf