API¶

This is where the documentation for the public API functions, and classes lives.

Key Text Pairs¶

Can be called directly via cwtvla.func().

class FixedVRandomKey(key_len=16)¶

Key text pairs for FixedVRandomKey TVLA

Usage:

import cwtvla
ktp = cwtvla.tkp.FixedVRandomKey(key_len=16) #16 byte key - AES128
key, text ktp.next_group_A() # Random text, fixed key
key, text ktp.next_group_B() # Random text, Random key

next_group_A()¶

next_group_B()¶

class FixedVRandomText(key_len=16)¶

Key text pairs for FixedVRandomText TVLA

Useful for evaluating the general leakage of a device, but may pick up false positives from loading/unloading of key/plaintext.

Usage:

import cwtvla
ktp = cwtvla.tkp.FixedVRandomText(key_len=16) #16 byte key - AES128
key, text ktp.next_group_A() # Fixed text, fixed key
key, text ktp.next_group_B() # Random text, fixed key

next_group_B() can also be used for Random V Random captures

next_group_A()¶: Return key, text, ciphertext for fixed text group

next_group_B()¶

Return key, text for random group. Updates random group afterwards

1st Call: I0

2nd Call: I1

3rd Call: I2…

class SemiFixedVRandomText(key_len=16, round=None)¶

Key text pairs for SemiFixedVRandomText.

Sets state in selected round to 0x8B8A490BDF7C00BDD7E6066Cxxxxxxxx. Varies the last bits and reverses to get input plaintext.

Useful since it is both non-specific and restricts TVLA results to a middle round.

Usage:

import cwtvla
ktp = cwtvla.tkp.SemiFixedVRandomText(key_len=16, round=5) #16 byte key - AES128, reverse from round 5
key, text ktp.next_group_A() # Semi fixed text, Fixed key
key, text ktp.next_group_B() # Random text, Fixed key

next_group_A()¶

next_group_B()¶

Return key, text for random group. Updates random group afterwards

1st Call: I0 2nd Call: I1 3rd Call: I2…

verify_AES(plaintext, key, ciphertext)¶: Verifies that AES(plaintext, key) == ciphertext

Analysis¶

Can be called directly via cwtvla.func().

build_centered_product(mct)¶

build_mean_corr(traces)¶

check_t_test(t, threshold=4.5)¶

Check the results of the t_test and return points where it failed.

Parameters

t (np.array(shape=(2, scope.adc.samples), dtype='float64')) – t_test results
threshold (float) – If t[0] and t[1] are above threshold or below -threshold at the same point, it is considered a failure point

Returns

list of failed points

construct_leakage_bit(operation_in, operation_out, round_offset=0)¶

Construct a leakage function using func between operation_in and operation_out

round_offset can be used to offset operation_out to a different round

Parameters

operation_in (str) – ‘addroundkey’, ‘subbytes’, ‘shiftrows’, or ‘mixcolumns’. Use None for no op.
operation_out (str) – ‘addroundkey’, ‘subbytes’, ‘shiftrows’, or ‘mixcolumns’. Use None for no op.
round_offset (int) – How many rounds to offset operation_out

Returns

leakage function

Return type

function(text, byte, bit, cipher, rnd)

construct_leakage_byte(operation_in, operation_out, round_offset=0)¶

Construct a leakage function using func between operation_in and operation_out

round_offset can be used to offset operation_out to a different round

Parameters

operation_in (str) – ‘addroundkey’, ‘subbytes’, ‘shiftrows’, or ‘mixcolumns’. Use None for no op.
operation_out (str) – ‘addroundkey’, ‘subbytes’, ‘shiftrows’, or ‘mixcolumns’. Use None for no op.
round_offset (int) – How many rounds to offset operation_out

Returns

leakage function

Return type

function(text, byte, bit, cipher, rnd)

eval_rand_v_rand(waves, textins, func, key_len=16, round_range=None, byte_range=None, bit_range=None, plot=False)¶

Evaluate rand_v_rand traces using a leakage function.

Separates waves using textins and the leakage func, then does a t_test between them.

Done for rounds in round_range, for bytes in byte_range, and bits (or vals) in bit range. Can also plot for each test.

Parameters

waves (np.array) – Rand V Rand Trace waves
textins (np.array) – Rand V Rand plaintexts
func (function(textin, byte, bit, cipher, round)) – Leakage to function used to separate traces
key_len (int) – length of key used in bytes
round_range (iterable) – Rounds to test
byte_range (iterable) – Bytes to test
bit_range (iterable) – Bits to test (or vals if using a byte leakage func)
plot (bool) – Plot t_test results?

leakage_func_bit(text, byte, bit, cipher, op_in, op_out)¶

A generic leakage function for testing a bit in the AES state

Tests between operations op_in and op_out. Assuming st0 is the state after operation op_in and st1 is the state after operation op_out, returns (st0[byte] ^ st1[byte]) & (1 << bit)

Parameters

text (list) – The input plaintext
byte (int) – Which byte to get the leakage for
bit (int) – Which bit to get the leakage for
cipher (AESCipher) – The cipher used for encryption
op_in (int) – Use the state after operation op_in. If 0, an array of 0 is used (useful for HW)
op_out (int) – Use the state after operation op_out. If 0, an array of 0 is used (useful for HW)

Returns

1 if the bit under test is 1, 0 if it is 0

Return type

int

leakage_func_byte(text, byte, val, cipher, op_in, op_out)¶

A generic leakage function for testing the value AES state

Tests between operations op_in and op_out. Assuming st0 is the state after operation op_in and st1 is the state after operation op_out, returns int((st0[byte] ^ st1[byte]) == val)

Parameters

text (list) – The input plaintext
byte (int) – Which byte to get the leakage for
val (int) – The val to separate based on
cipher (AESCipher) – The cipher used for encryption
op_in (int) – Use the state after operation op_in. If 0, an array of 0 is used (useful for HW)
op_out (int) – Use the state after operation op_out. If 0, an array of 0 is used (useful for HW)

Returns

1 if state_byte == val

Return type

int

leakage_lookup(operation, round)¶

Get the number representation for operation happening in round

Note that these all correspond to the output of the operation, so ‘subbytes’ is the output of the SBox, not the input.

Parameters

operation (str, None) – One of ‘subbytes’, ‘shiftrows’, ‘mixcolumns’, or ‘addroundkey’. If None, 0 is returned
round (int) – Which round the operation is occuring in

Returns

A number corresponding to the desired operation

roundinout_hd(text, byte, bit, cipher, rnd)¶

roundout_hw(text, byte, bit, cipher, rnd)¶

sbox_hw(text, byte, bit, cipher, rnd)¶

sboxinout_hd(text, byte, bit, cipher, rnd)¶

t_test(group1, group2)¶

Perform a t_test between two numpy arrays.

Splits the data between the first and second half of each group

Parameters

group1 (numpy.array) – Group 1
group2 (numpy.array) – Group 2

Returns

A numpy array with two elements spanning the length of the traces. The first is between the first half of groups 1 and 2. The second is between the second half of the groups.

Return type

numpy.array

CW Convenience¶

Must be manually imported

capture_all(scope, target, platform, N=10000, key_len=16)¶

Do all three non-specific captures and a Rand_V_Rand capture.

Stores the results in a CWTVLA standard zarr array

Parameters

scope (CW scope object) – Setup scope object
target (CW target object) – Setup target object
platform (str) – What to call the set in the zarr array
N (int) – Number of traces to capture
key_len (int) – 16 for AES-128, 32 for AES-256

capture_non_specific(scope, target, ktp_class, N=10000, key_len=16, group1=None, group2=None)¶

Capture data for a non-specific TVLA t-test

Parameters

scope (CW scope object) – Already setup scope object
target (CW target object) – Already setup target object
ktp_class (ktp) – Non specific KTP object (FixedVRandText, Key, etc)
N (int) – Number of traces to capture for each dataset (will end up with 2*N traces total)
key_len (int) – 16 for AES-128, 32 for AES-256
group1 (np.array) – Optional array object for storing traces in
group2 (np.array) – Optional array object for storing traces in

Returns

group1, group2

capture_rand(scope, target, N=10000, key_len=16, waves=None, textins=None)¶

Capture traces for a rand_v_rand TVLA t-test

Parameters

scope (CW scope object) – Setup scope object
target (CW target object) – Setup target object
N (int) – Number of traces to capture
key_len (int) – 16 for AES-128, 32 for AES-256
waves (np.array) – Optional array object for storing traces in
textins (np.array) – Optional array object for storing plaintexts in

Returns

waves, textins

setup_device(name)¶

Convience function for setting up and programing a CW/Target pair

Parameters: name (str) – String representing the target configuration. Currently supports ‘STM32F3’, ‘CW305’, ‘XMEGA’, ‘STM32F3-mbed’, ‘K82F’, ‘STM32F4’
Returns: Setup scope and target objects

test_cw_non_specific(platform, key_len=16)¶

Test a platform’s non_specific traces

Parameters

platform (str) – The target object’s name
key_len (int) – 16 for AES-128, 32 for AES-256

API¶

Key Text Pairs¶

Analysis¶

CW Convenience¶

ChipWhisperer-TVLA

Navigation

Related Topics