10. API Reference

Here we provide documentation for important classes and methods.

10.1. Basys3Ctrl Class (controller)

class fobos.Basys3Ctrl(self, port, baudRate=115200, dummy=False)

Class to interface with Basys3 controller.

Parameters:

  • port (str) – The serial port where the Basys3 board is connected(e.g /dev/ttyUSB1).

  • baudRate (int) – Baud rate. Default is 115200.

  • dummy (bool) – When set to true, no communication with Basys3 is done. This is to test the software only. Default is False.

processData(self, data, outLen)

Sends data to FOBOS hardware for processing, e.g. encryption

Parameters:

data (str) – The data to be processed. This is a hexadecimal string.

Rtype (str, str):

Returns:

(Status (“00000000” OK | “20000000” TIMOUT) , Result from DUT (i.e. ciphertext))

setOutLen(self, outLen)

set DUT Expected Output Length (result length) in bytes.

Parameters:

outLen (int) – The number of output bytes to be returned by the DUT (e.g 16 for AES-128).

Rtype int:

Returns:

Status.

setTriggerWait(self, trigWait)

Set number of trigger wait cycles

Parameters:

int (trigWait) – The number of DUT cycles after di_ready goes to 0 to issue the trigger.

Return type:

int

Returns:

Status

setTriggerMode(self, trigType)
Set trigger mode.
param int:

trigType. Possible values (TRG_NORM = 0 | TRG_FULL = 1 | TRG_NORM_CLK = 2 | TRG_FULL_CLK = 3)

rtype:

int

return:

Status

setTimeToReset(self, dutCycles)

set number of clock cycles after di_ready goes to 0 to reset the DUT.

Parameters:

dutCycles (int) – The number of DUT cycles to reset the DUT.

Return type:

int

Returns:

Status.

setTimeout(self, seconds)

set number of seconds to stop waiting for DUT result.

Parameters:

seconds (in) – Time in seconds. Range 1-40 seconds.

Return type:

int

Returns:

Status

enableTestMode(self)

Enable test mode. When this mode is enabled, the controller sends test-vectors to its internal dummy DUT.

Return type:

int

Returns:

Status

disableTestMode(self)

Disable test mode. In this mode the ctrl board uses the real DUT. This is the default mode.

Return type:

int

Returns:

Status

forceReset(self)

Reset DUT and clear current communication with DUT.

Return type:

int

Returns:

Status

releaseReset(self)

Release DUT reset signal

Return type:

int

Returns:

Status

setDUTClk(self, clkFreqMhz)

Set DUT clock frequency generated by the control board. Range is between 0.4 MHz - 100 MHz.

Parameters:

clkFreqMhz (float) – The DUT clock frequency in Mhz.

Return type:

int

Returns:

Status

10.2. Scope (Picoscope Class)

class Picoscope(self, sampleResolution=8, preTriggerSamples=0, postTriggerSamples=1000)

A class to interface with the Picoscope oscilloscope.

__init__(self, sampleResolution=8, preTriggerSamples=0, postTriggerSamples=1000)

Open oscilloscope

Parameters:

  • sampleResolution (int) – The number of bits used to represent each sample. Possible values 8, 12, 14, 15 and 16.

  • preTriggerSamples (int) – The number of samples before the trigger to return to the user.

  • postTriggerSamples (int) – The number of samples after the trigger to return to the user.

setChannel(self, channelName='CHANNEL_A', coupling='DC', rangemv='1V')

Configure voltage range and coupling for a channel.

Parameters:

  • channelName (str) – The name of the oscilloscope channel (CHANNEL_A | CHANNELB).

  • coupling (str) – Select DC/AC coupling (DC | AC)

  • rangemv (str) – The voltage range for the selected channel (10mV|20mV|50mV|100mV|200mV|500mV|1V|2V|5V|10V|20V)

setSamplingInterval(self, samplingIntervalns)

Sets the sampling interval (time between samples T) in nano seconds. Sampling rate = 1/T.

Parameters:

samplingInterval (int) – Sampling interval (time between samples T) in nano seconds. Sampling rate = 1/T.

setTrigger(self, channelName='CHANNEL_A', thresholdmv=500, direction='RISING_EDGE', autoTriggerDelay=2000)

Configure trigger channel.

Parameters:

  • channelName (str) – The channel to use as a trigger channel (CHANNEL_A | CHANNELB | EXTERNAL).

  • thresholdmv (int) – The minimum level of voltage to assert a trigger.

  • direction (str) – The trigger signal direction (RISING_EDGE| FALLING_EDGE).

  • autoTriggerDelay (int) – Time in milliseconds after which auto trigger occurs (i.e start storing data even if no valid trigger received).

setDataBuffers()

Allocates memory buffers to store oscilloscope data.

10.3. ProjectManager Class

class ProjectManager

A class to facilitate organizing and saving results files/data files in automatically created directories. For example, when new capture is performed a directory named attempt-[number] will be created in the capture directory.

setWorkSpaceDir(self, workSpaceDir)

Sets the directory where all data will be saved.

Parameters:

workSpaceDir (str) – Workspace directory path.

setProjName()

Sets the project name.

Parameters:

projectName (str) – Project name. A directory will be created in the workspace with the project name.

getProjDir()

Gets the project directory path.

Returns:

Full project directory path.

getCaptureDir()

Creates and returns the path of a new directory created in worksapce/projectName/capture/ the folder will be named attempt-(number) for uniqueness.

10.4. Nexy3DUT Class

class Nexys3DUT

A class to program Digilent Nexy3 DUT. This class requires that Digilent Adept command line tools (djtgcfg command) is installed.

setBitFile(bitFile)

Sets the bit file name used to program the DUT FPGA.

Parameters:

bitFile (str) – Full path of the .bit file to program the FPGA.

program()

Programs the FPGA using the bit file specified using he setBitFile method.

10.5. CPA Class

class CPA

A class to perform Correlation Power Analysis.

doCPA(self, measuredPower, hypotheticalPower, numTraces, analysisDir, MTDStride)

Perform CPA.

Parameters:

  • measuredPower (numpy_array) – The power measure using the oscilloscope.

  • hypotheticalPower (numpy_array) – The hypotheticalPower estimated using the power model.

  • numTraces (int) – Number of traces in to be analyzed.

  • analysisDir (str) – Full path of the directory to store analysis results.

  • MTDStride (int) – The number of traces to add in each step when plotting the MTD graph.

10.6. DataGenerator Class

class DataGenerator

A class to generate FOBOS-ready test vectors.

randTVFile(self, pdiLen, sdiLen, rdiLen, outLen, fileName, numTVs)

Generate a FOBOS-ready test-vector file.

Parameters:

  • pdiLen (int) – The lenght of PDI data (e.g plaintext) in bytes.

  • sdiLen (int) – The lenght of SDI data (e.g secret key) in bytes.

  • rdiLen (int) – The lenght of RDI data (random data) in bytes.

  • outLen (int) – The lenght of expected output (e.g ciphertext) in bytes.

  • fileName (str) – The name of the file to store the testvectors.

randTestVector(self, pdiLen, sdiLen, rdiLen, outLen)

Generate a single FOBOS-ready test-vector.

Parameters:

  • pdiLen (int) – The lenght of PDI data (e.g plaintext) in bytes.

  • sdiLen (int) – The lenght of SDI data (e.g secret key) in bytes.

  • rdiLen (int) – The lenght of RDI data (random data) in bytes.

  • outLen (int) – The lenght of expected output (e.g ciphertext) in bytes.