Commit ccc5e2ad authored by Davide Bellizia's avatar Davide Bellizia

another pass over README.md

parent 6c16f897
......@@ -7,7 +7,7 @@ datasets (currently available on the [Spook website](https://www.spook.dev/)).
The hardware core follows a custom API broadly based
on the [LWC HW API](https://cryptography.gmu.edu/athena/LWC/LWC_HW_API.pdf), proposed in the context of the
LWC NIST competition. We provide a python library that generates from an high level the data that
LWC NIST competition. We provide a python library that generates from a high level the data that
should be sent to the core in order to perform different operations (e.g., load the key, encryption, ...).
The latter is used to generate the test vectors used in simulatations as well as the actual FPGA implementation.
......@@ -255,9 +255,9 @@ As shown next, the Clyde module is separated in two mechanisms: the Clyde comput
generation/handling of the randomness. The computation takes as input the sharing of the key (i.e., the `sharing_key` bus), the
tweak (i.e., the `tweak` bus) and either the plaintext or the ciphertext (i.e., the `data_in` bus). The control signal `inverse` is used to
specify to the core which operation (i.e., encryption or decryption) is currently perfomed. Next, control signals will be represented in blue.
The randomness is generated by the use of two (similar) instances of a maximum length
The randomness is generated by using two (similar) instances of a maximum length
[128-bits LFSR](https://www.xilinx.com/support/documentation/application_notes/xapp210.pdf) (i.e., the `prng_unit` module). Seeds can be
sent to these instances through the `feed_data` signal by the mean of a `SEED` segment, as explained above.
sent to these instances through the `feed_data` signal by means of a `SEED` segment, as explained above.
A specific controller (i.e., the `stalling_unit`) is used to properly handle the interaction between the PRNGs and the Clyde logic (using the
`control_sig*`, `control_status*`and `stall_control*` signals). Basically, the latter enables the LFSRs and stalls the computation
core when randomness is required and not ready. It is also used as a control wrapper interface for the Clyde computation logic.
......@@ -268,11 +268,11 @@ core when randomness is required and not ready. It is also used as a control wra
</div>
Going deeper, the architecture of the practical Clyde's logic is decribed and shown next. Before everything, the non-sensitive data are
Going deeper, the architecture of the practical Clyde's logic is described and shown next. First of all, non-sensitive data are
formatted as a valid sharing (using an instance of the module `cst_mask`). This operation boils down to a proper formatting of the data.
Another way to see it is to compare it to a sharing operation of each bits of the data with a constant randomness of 0. A sharing data
representation is next represented in green. Although this operation is not visible for the tweak on the schematic, it is also
implicitly present in the `MSKaddWTK` module developped next.
implicitly present in the `MSKaddWTK` module developed next.
An execution of Clyde128 starts with a tweakey addition, as well as a
constant addition in the case of a decryption. These are performed by the `MSKaddWTK` module. The latter takes as input the key sharing,
......@@ -294,9 +294,9 @@ up to some point.
### Lbox Layer
The first layer presented is the lbox layer. The latter is in fact composed of parallel `MSKlbox_dual` module
The first layer presented is the Lbox layer. The latter is in fact composed of parallel `MSKlbox_dual` module
instances (inside the `MSKlbox_unit_dual` module). Each of these instances either computes the direct or
the inverse lbox operation depending on the `inverse` control signal. A full lbox layer is performed following
the inverse Lbox operation depending on the `inverse` control signal. A full Lbox layer is performed following
a shift register approach by looping over the `MSKlbox_unit_dual` module each time with a different part of the shared state.
<div align="center">
......@@ -322,9 +322,9 @@ The different configuration are summed up in the following table:
### Sbox Layer
Similarly to the lbox layer, the sbox layer is composed of parallel `MSKspook_sbox_dual` module instances
Similarly to the Lbox layer, the Sbox layer is composed of parallel `MSKspook_sbox_dual` module instances
(inside of the `MSKsbox_unit_dual` module). Each of these instances can either computes the direct of the
inverse sbox operation depending on the `inverse` control signal. A full sbox layer is performed following
inverse sbox operation depending on the `inverse` control signal. A full Sbox layer is performed following
a shift register approach by looping over the `MSKsbox_unit_dual` module each time with a different part if the shared state.
In comparison with the lbox layer, some data representation transformation are applied at the IOs of the logic. The
latter are intended to move from a bundle representation to a columns representation (the `MSKbundle2cols` module) or
......@@ -336,9 +336,9 @@ inversely (the `MSKcols2bundle` module). These only consist in wiring modificati
</div>
A `MSKspook_sbox_dual` instance is implemented using dedicated logic for the sbox operation. The inverse sbox
operation is performed by reusing the sbox logic with two additional linear layers (`MSKpre_inv_sbox` before
the sbox logic and `MSKpost_inv_sbox` after). In particular, the input of the sbox logic comes either
A `MSKspook_sbox_dual` instance is implemented using dedicated logic for the Sbox operation. The inverse Sbox
operation is performed by reusing the Sbox logic with two additional linear layers (`MSKpre_inv_sbox` before
the sbox logic and `MSKpost_inv_sbox` after). In particular, the input of the Sbox logic comes either
from `MSKpre_inv_sbox` or from the instance input depending on the value of the `inverse` control signal.
Similarly, the output of the instance comes either from `MSKpost_inv_sbox` or from the output of the sbox.
......@@ -349,10 +349,10 @@ Similarly, the output of the instance comes either from `MSKpost_inv_sbox` or fr
</div>
The amount of parallel `MSKspook_sbox_dual` instances lies in [1,2,4,8,16,32] and can be chosen with the
parameter `PDSBOX` (for Power Divider SBOX). The latter directly impacts the bus size `SIZE_REM_SB` and `SIZE_CHUNK_SB` as
parameter `PDSBOX` (for Power Divider SBOX). The latter directly impacts on the bus size of `SIZE_REM_SB` and `SIZE_CHUNK_SB`, as
well as the computation latency required. Finally, because of the specific architecture of the protected AND gates,
the sbox logic is implemented as a 3-levels pipeline. The induced latency is thus taken into account of an offset of 3 clock cycles.
The different configuration are summed up in the following table:
the Sbox logic is implemented as a 3-levels pipeline. The induced latency is thus taken into account, requiring an offset of 3 clock cycles, as shown above.
The different configurations are summed up in the following table:
<div align="center">
......@@ -370,11 +370,11 @@ The different configuration are summed up in the following table:
### Simulations Script (unix-like)
As mentionned above, the [simu](spook_msk/simu) contains the simulation script
[sim_spook_MSK](spook_msk/simu/sim_spook_MSK.sh). The later proceeds to the following operations:
[sim_spook_MSK.sh](spook_msk/simu/sim_spook_MSK.sh). The latter performs the following operations:
+ **Testvectors generation**: this process is generates the different commands that will be sent to the
core based on the file specified. The latter should be formatted similarly to the NIST LWC testvectors files.
This is done using the [gen_tv](spook_msk/spook_hw_api/gen_tv.py) script.
+ **Testvectors generation**: this process generates the different commands that will be sent to the
core based on the file specified. Those commands are formatted similarly to the NIST LWC testvectors files.
This is done using the [gen_tv.py](spook_msk/spook_hw_api/gen_tv.py) script.
+ **Simulation file building**: the simulation file is built using Iverilog.
+ **Simulation**: the simulation is performed using vvp.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment