TraceFormat

Overview

Although alternatives (e.g., TRS as used by Riscure) are supported in selected cases, by default SCA3S uses Hierarchical Data Format (HDF), specifically HDF5, as an on-disk storage format for trace data sets. Since the front- and back-end infrastructure is written in Python, they make use of the h5py package.
The contents of a given trace data set is divided into various classes, which are outlined within the sub-sections below.

Kernel-agnostic datasets

trace/trigger:
- type: an array of shape ( n, m ), each element of which is of a type matching signal_dtype.
- purpose: fd[ 'trace/trigger' ][ i, j ] is the j-th sample (for 0 <= j < m) of a waveform associated with the i-th acquisition (for 0 <= i < n) of the trigger.
trace/signal:
- type: an array of shape ( n, m ), each element of which is of a type matching signal_dtype.
- purpose: fd[ 'trace/signal' ][ i, j ] is the j-th sample (for 0 <= j < m) of a waveform associated with the i-th acquisition (for 0 <= i < n) of the signal, e.g., the trace of power consumption.
crop/trigger:
- type: an array of shape ( n, ), each element of which is a region reference.
- purpose: fd[ 'crop/trigger' ][ i ] is a region reference which "crops" fd[ 'trace/trigger' ][ i ] to a period where the kernel is executed, i.e., the period where fd[ 'trace/trigger' ][ i ] is high (or "armed").
crop/signal:
- type: an array of shape ( n, ), each element of which is a region reference.
- purpose: fd[ 'crop/signal' ][ i ] is a region reference which "crops" fd[ 'trace/signal' ][ i ] to a period where the kernel is executed, i.e., the period where fd[ 'trace/trigger' ][ i ] is high (or "armed").
tvla/lhs:
- type: an array of shape ( n/2, ), each element of which is of type i8.
- purpose: for a TLVA-based acquisition policy, this is the set of i for which the i-th acquisition is part of the left-hand set, e.g., "fixed" for a "fixed-vs-random" policy.
tvla/rhs:
- type: an array of shape ( n/2, ), each element of which is of type i8.
- purpose: for a TLVA-based acquisition policy, this is the set of i for which the i-th acquisition is part of the right-hand set, e.g., "random" for a "fixed-vs-random" policy.
perf/cycle:
- type: an array of shape ( n, ), each element of which is of type <u8.
- purpose: fd[ 'perf/cycle' ][ i ] records the time taken to execute the kernel (or, more specifically, period where trace/trigger is high) during the i-th acquisition, per the Time Stamp Counter (TSC).
perf/duration:
- type: an array of shape ( n, ), each element of which is of type <f8.
- purpose: fd[ 'perf/duration' ][ i ] records the time taken to execute the kernel (or, more specifically, period where trace/trigger is high) during the i-th acquisition, per the period where fd[ 'trace/trigger' ][ i ] is high (or "armed").

Kernel-agnostic attributes

board/kernel_version:
- type: str.
- purpose: a version number for the kernel used during acquisition (as reported by ?kernel).
board/kernel_id:
- type: str.
- purpose: an identifier for the kernel used during acquisition (as reported by ?kernel).
board/kernel_id_nameof:
- type: str.
- purpose: an identifier for the kernel used during acquisition (as reported by ?kernel).
board/kernel_id_modeof:
- type: str.
- purpose: an identifier for the kernel used during acquisition (as reported by ?kernel).
board/kernel_io:
- type: str (more specifically, a dict encoded as a str).
- purpose: a specification for the kernel interface (as reported by >kernel and <kernel).
scope/signal_dtype:
- type: str.
- purpose: the data type of samples in each waveform.
scope/signal_samples:
- type: <u8.
- purpose: the number of samples acquired per waveform.
scope/signal_resolution:
- type: <u8.
- purpose: the acquisition resolution, i.e., number of bits used to represent each sample.
scope/signal_interval:
- type: <f8.
- purpose: the acquisition interval, i.e., time between samples.
scope/signal_duration:
- type: <f8.
- purpose: the acquisition duration, i.e., total time.

Kernel-specific datasets

aead:
- data/k:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/k' ][ i ] is a sequence of bytes representing the cipher key during the i-th acquisition.
- data/a:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/a' ][ i ] is a sequence of bytes representing the associated data during the i-th acquisition.
- data/m:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/m' ][ i ] is a sequence of bytes representing the plaintext during the i-th acquisition.
- data/c:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/c' ][ i ] is a sequence of bytes representing the ciphertext during the i-th acquisition.
plus, for each of the above, say t,
- data/usedof_t:
  - type: an array of shape ( n, ), each element of which is of type '<u8'.
  - purpose: fd[ 'data/usedof_t' ][ i ] is the used (vs. allocated) size of each fd[ 'data/t' ][ i ]; for fixed-size registers the two are equivalent, but for variable-sized registers use of the region reference avoids any out-of-bounds content.
block:
- data/k:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/k' ][ i ] is a sequence of bytes representing the cipher key during the i-th acquisition.
- data/m:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/m' ][ i ] is a sequence of bytes representing the plaintext during the i-th acquisition.
- data/c:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/c' ][ i ] is a sequence of bytes representing the ciphertext during the i-th acquisition.
plus, for each of the above, say t,
- data/usedof_t:
  - type: an array of shape ( n, ), each element of which is of type '<u8'.
  - purpose: fd[ 'data/usedof_t' ][ i ] is the used (vs. allocated) size of each fd[ 'data/t' ][ i ]; for fixed-size registers the two are equivalent, but for variable-sized registers use of the region reference avoids any out-of-bounds content.
function:
- data/x0:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/x0' ][ i ] is a sequence of bytes representing an input to r = f( x ) during the i-th acquisition.
- data/x1:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/x1' ][ i ] is a sequence of bytes representing an input to r = f( x ) during the i-th acquisition.
- data/x2:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/x2' ][ i ] is a sequence of bytes representing an input to r = f( x ) during the i-th acquisition.
- data/x3:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/x3' ][ i ] is a sequence of bytes representing an input to r = f( x ) during the i-th acquisition.
- data/x4:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/x4' ][ i ] is a sequence of bytes representing an input to r = f( x ) during the i-th acquisition.
- data/x5:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/x5' ][ i ] is a sequence of bytes representing an input to r = f( x ) during the i-th acquisition.
- data/x6:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/x6' ][ i ] is a sequence of bytes representing an input to r = f( x ) during the i-th acquisition.
- data/x7:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/x7' ][ i ] is a sequence of bytes representing an input to r = f( x ) during the i-th acquisition.
- data/r0:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/r0' ][ i ] is a sequence of bytes representing an output from r = f( x ) during the i-th acquisition.
- data/r1:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/r1' ][ i ] is a sequence of bytes representing an output from r = f( x ) during the i-th acquisition.
- data/r2:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/r2' ][ i ] is a sequence of bytes representing an output from r = f( x ) during the i-th acquisition.
- data/r3:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/r3' ][ i ] is a sequence of bytes representing an output from r = f( x ) during the i-th acquisition.
- data/r4:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/r4' ][ i ] is a sequence of bytes representing an output from r = f( x ) during the i-th acquisition.
- data/r5:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/r5' ][ i ] is a sequence of bytes representing an output from r = f( x ) during the i-th acquisition.
- data/r6:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/r6' ][ i ] is a sequence of bytes representing an output from r = f( x ) during the i-th acquisition.
- data/r7:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/r7' ][ i ] is a sequence of bytes representing an output from r = f( x ) during the i-th acquisition.
plus, for each of the above, say t,
- data/usedof_t:
  - type: an array of shape ( n, ), each element of which is of type '<u8'.
  - purpose: fd[ 'data/usedof_t' ][ i ] is the used (vs. allocated) size of each fd[ 'data/t' ][ i ]; for fixed-size registers the two are equivalent, but for variable-sized registers use of the region reference avoids any out-of-bounds content.
hash:
- data/m:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/m' ][ i ] is a sequence of bytes representing the message during the i-th acquisition.
- data/d:
  - type: an array of shape ( n, ), each element of which is of type B.
  - purpose: fd[ 'data/d' ][ i ] is a sequence of bytes representing the digest during the i-th acquisition.
plus, for each of the above, say t,
- data/usedof_t:
  - type: an array of shape ( n, ), each element of which is of type '<u8'.
  - purpose: fd[ 'data/usedof_t' ][ i ] is the used (vs. allocated) size of each fd[ 'data/t' ][ i ]; for fixed-size registers the two are equivalent, but for variable-sized registers use of the region reference avoids any out-of-bounds content.

Kernel-specific attributes

aead:
- kernel/sizeof_k:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/k' ][ i ].
- kernel/sizeof_a:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/a' ][ i ].
- kernel/sizeof_m:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/m' ][ i ].
- kernel/sizeof_c:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/c' ][ i ].
block:
- kernel/sizeof_k:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/k' ][ i ].
- kernel/sizeof_m:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/m' ][ i ].
- kernel/sizeof_c:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/c' ][ i ].
function:
- kernel/sizeof_x0:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/x0' ][ i ].
- kernel/sizeof_x1:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/x1' ][ i ].
- kernel/sizeof_x2:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/x2' ][ i ].
- kernel/sizeof_x3:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/x3' ][ i ].
- kernel/sizeof_x4:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/x4' ][ i ].
- kernel/sizeof_x5:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/x5' ][ i ].
- kernel/sizeof_x6:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/x6' ][ i ].
- kernel/sizeof_x7:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/x7' ][ i ].
- kernel/sizeof_r0:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/r0' ][ i ].
- kernel/sizeof_r1:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/r1' ][ i ].
- kernel/sizeof_r2:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/r2' ][ i ].
- kernel/sizeof_r3:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/r3' ][ i ].
- kernel/sizeof_r4:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/r4' ][ i ].
- kernel/sizeof_r5:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/r5' ][ i ].
- kernel/sizeof_r6:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/r6' ][ i ].
- kernel/sizeof_r7:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/r7' ][ i ].
hash:
- kernel/sizeof_m:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/m' ][ i ].
- kernel/sizeof_d:
  - type: <u8.
  - purpose: the allocated size of each fd[ 'data/d' ][ i ].

Example

For example, image you download the data set ${DATASET}.hdf5.gz where ${DATASET} denotes, e.g., the associated job identifier. Having decompressed it by executing

gunzip ${DATASET}.hdf5.gz

you can then execute an interactive Python shell

python3

and proceed as follows:

Import packages:
```
import binascii, h5py
```

Open data set:

fd = h5py.File( '${DATASET}.hdf5', 'r' )

Inspect the kernel identifier(s):

fd.attrs[ 'board/kernel_id'        ]
fd.attrs[ 'board/kernel_id_nameof' ]
fd.attrs[ 'board/kernel_id_modeof' ]

Inspect the size

fd.attrs[ 'kernel/sizeof_k' ]
fd.attrs[ 'kernel/sizeof_m' ]
fd.attrs[ 'kernel/sizeof_c' ]

and (hexadecimal) value of the

binascii.b2a_hex( fd[ 'data/k' ][ 0 ] )
binascii.b2a_hex( fd[ 'data/m' ][ 0 ] )
binascii.b2a_hex( fd[ 'data/c' ][ 0 ] )

0-th cipher key, plaintext, and ciphertext.

Extract all

fd[ 'trace/trigger' ][ 0 ]
fd[ 'trace/signal'  ][ 0 ]

of the 0-th trigger and signal waveforms.

Extract part

fd[ 'trace/trigger' ][ fd[ 'crop/trigger' ][ 0 ] ][ 0 ]
fd[ 'trace/signal'  ][ fd[ 'crop/signal'  ][ 0 ] ][ 0 ]

of the 0-th trigger and signal waveforms, using the pre-computed crop of the former to match the latter, i.e.,

                                                                    t_pos                                      t_neg
                                                                     |                                          |
                                                                     v                                          v
                                                                     :                                          :
                                                           |         +------------------------------------------+
                                                           |         |                                          |
fd[ 'trace/trigger' ][ 0 ]                              => |         |                                          |
                                                           |---------+                                          +---------
                                                           |         :                                          :
                                                           +-------------------------------------------------------------->
                                                                     :                                          :
                                                           |         :   /\        /\            /\            /\
                                                           |  /\     :  /  \      /  \      /\  /  \          / :\    /\
fd[ 'trace/signal'  ][ 0 ]                              => | /  \  /\: /    \/\  /    \  /\/  \/    \    /\  /  : \  /  \
                                                           |/    \/  \/        \/      \/            \  /  \/   :  \/    \
                                                           |         :                                \/        :
                                                           +-------------------------------------------------------------->
                                                                     :                                          :
                                                                     :                                          :
                                                                     |------------------------------------------:    
                                                                     |                                          :
fd[ 'trace/trigger' ][ fd[ 'crop/trigger' ][ 0 ] ][ 0 ] =>           |                                          :
                                                                     |                                          :
                                                                     |                                          :
                                                                     +------------------------------------------->
                                                                     :                                          :
                                                                     |   /\        /\            /\            /:
                                                                     |  /  \      /  \      /\  /  \          / :
fd[ 'trace/signal'  ][ fd[ 'crop/signal'  ][ 0 ] ][ 0 ] =>           | /    \/\  /    \  /\/  \/    \    /\  /  :
                                                                     |/        \/      \/            \  /  \/   :
                                                                     |                                \/        :
                                                                     +------------------------------------------->
                                                                     ^                                          ^
                                                                     |                                          |
                                                                     0                                     t_neg-t_pos-1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly