Readme for replicability submission of paper ID #73 ("Acoustic Integrity Codes: Secure Device Pairing Using Short-Range Acoustic Communication")

A) Source code info
Repository: N/A
List of Programming Languages: Matlab, Bash
Compiler Info: Matlab R2019b, Matlab Runtime Version 9.7
Packages/Libraries Needed:
    - Matlab Signal Processing Toolbox
    - Matlab Communications Toolbox

B) Datasets info
Repository: N/A
Data generators: N/A

C) Hardware Info
    Running the simulations and generating the figures does not require any
    special hardware. Only Matlab is required.

    Reference hardware:
C1) Processor (architecture, type, and number of processors/sockets)
    - Host: 1 * Intel(R) Core(TM) i7-8700K CPU @ 3.70GHz
    - Virtual Machine: 1 vCPU
C2) Caches (number of levels, and size of each level)
    - L1D cache: 192 KiB
    - L1I cache: 192 KiB
    - L2 cache: 1.5 MiB
    - L3 cache: 12 MiB
C3) Memory (size and speed)
    - Host: 2 * 8 GiB DIMM DDR4 Synchronous Unbuffered 2133 MHz
    - Virtual Machine: 2 GiB
C4) Secondary Storage (type: SSD/HDD/other, size, performance: random read/sequential read/random write/sequential write)
    - Type: SSD
    - Size: 500 GB
    - Random read: 370 MiB/s
    - Sequential read: 530 MiB/s
    - Random write: 305 MiB/s
    - Sequential write: 480 MiB/s


D) Experimentation Info
D1) Scripts and how-tos to generate all necessary data or locate datasets
    N/A

D2) Scripts and how-tos to prepare the software for system

Download the VM applicance and import the OVA file into VirtualBox. This VM
contains a Xubuntu 20.04 LTS (64-bit) system with all the necessary material for
the Replicability label.

The system should log in automatically after booting. The login details are:
    user: wisec
    password: wisec

We cannot distribute the Matlab IDE directly, therefore we compiled all
experiments with the Matlab Compiler mcc so that you can run them with the
freely available Matlab Runtime. If you have a Matlab licence, you can also
directly execute our code in the Matlab IDE. You can recompile our binaries
using the file `src/make.m`.


D3) Scripts and how-tos for all experiments executed for the paper

The directory `replicability` on the desktop contains all scripts to replicate
the generated figures from our paper.

    cd ~/Desktop/replicability

You can run all experiments at once to generate all 8 figures (note that the
last figure requires manual input, see details below):

   ./runExperiments.sh

The figures will be generated in the current directory.

The directory `src` contains the Matlab source files for use with a Matlab IDE
(not included, see D2). The source files corresponding to the distributed
binaries are in `src/figures`. They can be executed in the Matlab IDE (with the
Matlab path at `src`) to generate each individual figure.

The directory `bin` contains a binary to generate each figure. You can generate
these figures as follows:

  MATLAB_RUNTIME="/home/wisec/matlab-runtime/v97"

  # Figure 5
  ./bin/run_fig5_aic_spectrogram.sh $MATLAB_RUNTIME

  # Figure 8a
  ./bin/run_fig8a_aic_qpsk.sh $MATLAB_RUNTIME

  # Figure 8b
  ./bin/run_fig8b_aic_gaussian.sh $MATLAB_RUNTIME

  # Figure 9a
  ./bin/run_fig9a_aic_qpsk_attenuation.sh $MATLAB_RUNTIME

  # Figure 9b
  ./bin/run_fig9b_aic_qpsk_autocorrelation.sh $MATLAB_RUNTIME

  # Figure 10a
  ./bin/run_fig10a_aic_gaussian_attenuation.sh $MATLAB_RUNTIME

  # Figure 10b
  ./bin/run_fig10b_aic_gaussian_autocorrelation.sh $MATLAB_RUNTIME

  # Figure 11 (requires manual input)
  ./bin/run_fig11_evaluation_robustness_threshold.sh $MATLAB_RUNTIME

Each figure should take less than a minute to generate, except the last figure
(figure 11). The simulation for figure 11 can take a long time, depending on the
number of repetitions involved. The script will ask you for the number of
repetitions, which allows you to control the runtime. You can already get a
similar looking figure with a low number of 5 (takes about 5 minutes in the VM).
A higher number such as 200 gives better results but takes much longer. During
the experiment, a matrix will be filled up sequentially. You can estimate the
remaining runtime by looking at the remaining entries in this matrix.


These scripts generate the dynamic figures 5, 8a, 8b, 9a, 9b, 10a, 10b, and 11.
Figures 6a and 6b are screenshots of our Android prototype, which is available
at https://seemoo.de/aic-prototype. The remaining figures are static images,
which are explained in the paper.

Table 1 lists all possible combinations of legitimate bit d and attacker bit
d_M. The power values directly result from the given noise floor (-90 dBFS), the
legitimate SNR (20 dB, resulting in -70 dBFS), and the attacker's SNR (30 dB,
resulting in -60 dBFS). The value of -59.6 dBFS results from the superposition
of -60 dBFS and -70 dBFS and can be calculated using `pow2db(db2pow(-70) +
db2pow(-60))`.