TectroLabs | TL200 General Documentation

Software & Documentation Kit contents

Folder linux-32 – contains all necessary files and source code for building the GetRND and EF download software utilities and the tlrandom kernel module used with Linux 32 bit distributions (kernel 2.6 and up). The folder also contains C++ source code of the TL200 software API.

Folder linux-64 – contains all necessary files and source code for building the GetRND and EF download software utilities and the tlrandom kernel module used with Linux 64 bit distributions (kernel 2.6 and up). The folder also contains C++ source code of the TL200 software API.

Folder OS X-64 – contains all necessary files and source code for building the GetRND download software utility used with macOS. The folder also contains C++ source code of the TL200 software API.

Folder windows – contains all necessary files and source code for building the GetRND download software utility used with Windows XP SP3 / Vista / 7 / 8 / 8.1 / 10 (32 bit or 64 bit). A pre-built getrnd.exe executable is available in that folder. The utility program can be built with Microsoft Visual C++ 2010 Express or newer. The folder also contains a C++ source code of the TL200 software API

File TL200 – Technical Specifications.pdf – device operation and technical characteristics File TL200 device API.pdf – detailed API description

Using with Windows XP/Vista/7/8 (32 bit or 64 bit) /8.1/10

The TL200 device should be connected to the PC using one of the available USB 2.0 or 3.0 ports and the supplied USB extension cable. Once the TL200 device is connected for the first time, Windows OS will automatically start looking for an appropriate device driver to install. Alternatively, when the OS is not able to locate the driver, it can manually be installed by running the CDM21224_Setup.exe installer supplied with the Software & Documentation Kit and located in the folder windows.

The Software & Documentation Kit contains the getrnd.exe software utility located in the folder windows\getrnd\Release that can be used to verify the successful device installation. Alternatively, the folder windows\getrnd contains a Visual C++ 2010 Express project that can be used to build the getrnd.exe software utility. The project also contains the software API source code and FTDI third party files that can be included in other projects for communicating with the TL200 device.

To verify the TL200 device installation status, run the following command from the command line:

windows\getrnd\Release\getrnd.exe -ld

When the TL200 device is successfully installed and ready, the output from running the above command should look similar to this:

{DevNum=0 WinPort=COM1 ID=0x4037001 LocId=0x2111 UsbCfg=AMWU4OR5 DevModel=TL200 DevVer=1.7 DevS/N=789A04154435535948202020FF0801 DevPowerProfile=5}

Please note that each time the TL200 device is connected to a USB interface, the monitoring logic will flash the LED light and then run HCT, Repetition Count Test and Adaptive Proportion Test on random bytes as part of the start-up test suite for about 10 seconds before the device can be used.

Using with Linux (32 bits)

The TL200 device should be connected to the PC using one of the available USB 2.0 or 3.0 ports and the supplied USB extension cable. Linux running kernel 2.6 and up already contains the appropriate USB drivers for using with the TL200 device. All necessary files for Linux OS 32 bits, including the project for the GetRND and EF software utilities are located in the folder linux- 32\getrnd.

The GetRND software utility can be used to verify the TL200 installation status. The GetRND project requires make, gcc and c++/g++ components to be installed prior to building the GetRND and EF utilities.

On Ubuntu, use the following commands to install the required dependencies:

sudo apt-get update
sudo apt-get install make
sudo apt-get install g++

On CentOS or Red Hat, use the following commands to install the required dependencies:

yum update
yum install make
yum install gcc-c++

To build the GetRND and EF software utilities, you will need to run the following commands from the command line:

cd linux-32\getrnd
make

To use TL200 device with the Linux OS, you will need to configure it (a one-time procedure) by running the configure utility from the command line (the configure utility is available in the same folder along with getrnd utility):

sudo ./configure –slo –dn 0

To verify that the device was successfully configured for Linux OS, run the following command from the command line:

sudo ./configure –ld

When the TL200 device is successfully installed and ready, the output from running the above command should look similar to this (configured for Linux and Mac OSX):

{DevNum=0 DevModel=TL200 DevVer=1.8 DevS/N=789A04154435535948202020FF0801}

A successful installation of theTL200 device can also be verified by executing the following command from the command line (please note that the sudo command, since GetRND requires appropriate permissions):

sudo ./getrnd -ld

When the TL200 device is successfully installed and ready, the output from running the above command should look similar to this:

{DevNum=0 ID=0x4037001 LocId=0x2111 UsbCfg=AMWU4OR5 DevModel=TL200 DevVer=1.7 DevS/N=789A04154435535948202020FF0801 DevPowerProfile=5}

Please note that each time the TL200 is connected to a USB interface, the monitoring logic will flash the LED light and then run HCT, Repetition Count Test and Adaptive Proportion Test on random bytes as part of the start-up test suite for about 10 seconds before the device can be used.

Using with Linux (64 bits)

Instructions for installing the TL200 on 64 bit Linux are the same as those for 32 bit Linux shown above, with the exceptions that all of the files for 64 bit Linux are located in the linux-64\getrnd folder.

To build the GetRND and EF software utilities you will need to run the following commands from the command line:

cd linux-64\getrnd
make

Building and loading `tlrandom` kernel module with Linux

The TL200 device can be used with the tlrandom kernel module that is available with the TL200 SDK. The module has been tested with Ubuntu 14.04 LTS (server/desktop), Cent OS 7, Cent OS 6 (32/64), and should also work with other Linux based x86/x64 systems.

You will need to configure the TL200 device for use with Linux/OS X prior using it with tlrandom module (read the Using with Linux section for configuration details)

The tlrandom make project is available in the following SDK locations:

linux-32\tlrandom
linux-64\tlrandom

We strongly recommend performing the following steps before building the tlrandom module on Ubuntu:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get reboot
sudo apt-get install make
sudo apt-get install gcc

We strongly recommend performing the following steps before building the tlrandom module on Cent OS with system administration permissions:

yum install make
yum install gcc
yum install kernel-devel
reboot

The tlrandom module can be built with make. You will need to re-build the module each time a new version of the kernel is installed.

Once the module is successfully built with make, it should be loaded into the kernel by running the ins-tlrandom.sh script with system administration permissions:

./ins-tlrandom.sh

After the tlrandom module is successfully loaded by the kernel, the random bytes will be available for download from the following device:

/dev/tlrandom

The module allows the entropy available in /dev/tlrandom to be shared concurrently by multiple applications. The device can be used to feed the rngd daemon with random data generated by TL200 device using the following command (Use sudo apt-get install rng-tools to install the rngd daemon on Ubuntu)

sudo rngd -r /dev/tlrandom

Alternatively, you can download random bytes to a file using the following command:

dd if=/dev/tlrandom of=download.bin bs=100 count=120000

The tlrandom module will automatically detect the event when a TL200 device is plugged in or unplugged from any USB port.

Please note that you will not be able to use getrnd utility when the TL200 device is in use by the tlrandom module.

To verify if the tlrandom module has successfully detected the TL200 device, simply check the kernel system logs, you should see a log that should look similar to this:

--------------------------------------
-- TL200 device connected and ready --
--------------------------------------

Currently the tlrandom module can only use one TL200 device at a time.

tlrandom module can be unloaded from the kernel by running the following command (using system administration privileges):

rmmod tlrandom

Using with macOS

The TL200 device should be connected using one of the available USB 2.0 or 3.0 ports and the supplied USB extension cable. macOS v10.6 already contains the appropriate USB drivers for using with the TL200 device. All necessary files for OS X, including the project for the GetRND software utility are located in the OS X-64 \getrnd folder.

The GetRND software utility can be used to verify the TL200 installation status. The GetRND project requires Make, gcc and C++ components to be installed prior to building the GetRND utility.

To build GetRND software utility you will need to run the following commands from the command line:

cd “OS X-64 \getrnd”
make

To use the TL200 device with macOS, you will need to configure it (a one-time procedure) by running the following command from command line (the configure utility is available in the same folder along with getrnd utility):

sudo ./configure –slo –dn 0

To verify that the device was successfully configured for Linux macOS, run the following command from the command line:

sudo ./configure –ld

When the TL200 device is successfully installed and ready, the output from running the above command should look similar to this (configured for Linux and Mac OSX):

{DevNum=0 DevModel=TL200 DevVer=1.8 DevS/N=789A04154435535948202020FF0801}

A successful installation of the TL200 device can also be verified by executing the following command from the command line:

./getrnd -ld

When the TL200 device is successfully installed and ready, the output from running the above command should look similar to this:

{DevNum=0 ID=0x4037001 LocId=0x2111 UsbCfg=AMWU4OR5 DevModel=TL200 DevVer=1.6 DevS/N=789A04154435535948202020FF0801 DevPowerProfile=5}

Using the GetRND software utility

The GetRND software utility can be used to discover TL200 devices connected to the host computer, as well as for downloading random bytes from such devices. Please note that the GetRND command should be used with sudo prefix when used in Linux.

Use the following command (for Windows OS, replace sudo ./getrnd with getrnd.exe) to scan and discover all TL200 connected devices (it will only retrieve information about TL200 devices that are not currently in use):

sudo ./getrnd -ld

The output will look like this (one line per attached device):

{DevNum=0 ID=0x4037001 LocId=0x2111 UsbCfg=AMWU4OR5 DevModel=TL200 DevVer=1.6 DevS/N=789A04154435535948202020FF0801 DevPowerProfile=5}

Where:
DevNum – logical device number starting with 0
ID – FTDI USB internal ID
LocId – FTDI location ID
UsbCfg – FTDI USB configuration version
DevModel – TL device model
DevVer – TL200 device version
DevS/N – TL200 device unique serial number
DevPowerProfile – TL200 device power profile (5 – the fastest speed)

To download 12 MB of true random numbers from the TL200 device and store them in a file named rnd.bin:

sudo ./getrnd -dd -fn rnd.bin -nb 12000000

To download 12 MB of true random numbers from the TL200 device and send them to standard output (do not use it with Windows because the OS will add extra bytes to the standard output stream):

sudo ./getrnd -dd -nb 12000000 -wtso

To download an unlimited amount of true random numbers from the TL200 device and store them in a file named rnd.bin:

sudo ./getrnd -dd -fn rnd.bin

To download 12 MB of raw random numbers (this mode should only be used when applying an external bias removing logic, do not expect the random bytes will pass any statistical tests when using this mode) from the TL200 device and store them in a file named rnd.bin:

sudo ./getrnd -dd -fn rnd.bin -nb 12000000 -gm r

To generate a random sequence of non-repeatable numbers 1 through 10 in a random order:

sudo ./getrnd -grs 1 10

To generate a random sequence of non-repeatable numbers (including negative numbers) -10 through 5 in a random order:

sudo ./getrnd -grs -10 5

You can also limit the amount of numbers generated to less than the range. For example, you can choose to generate only the first five numbers of a random sequence of numbers from 1 through 10,000,000:

sudo ./getrnd -grs 1 10000000 5

To obtain a complete list of command line options available for using the GetRND utility:

./getrnd

Using the EF (Entropy Feeder) software utility

Currently available only for Linux, the EF utility is used for interacting with the hardware random number generator device TL200 for the purpose of downloading random bytes and feeding them into the Linux /dev/random entropy pool. The TL200 device should be connected to an available USB port before running this utility.

You can start continuously feeding the kernel entropy pool /dev/random using the TL200 device by running this command:

sudo ./ef

The EF utility can be started with option -crm. This option will prevent the running utility from quitting if the TL200 device is disconnected from and re-connected back to the host computer. This option should be used when running EF in background. EF can run in background with the following command:

sudo nohup ./ef -crm > ./ef.log 2>&1 &

Use the following command to see all options available for the EF utility:

./ef -?

Example C++ code for downloading random data

The TL200 software kit contains a C++ class that can be included in any C++ source code and used for downloading true random bytes.

The sample code below demonstrates how to download 100000 true random bytes from the connected TL200 device using the software API:

#include "TL200.h"
//
// Main entry
//
int main(int argc, char **argv) {<!-- fix** -->
    TL200 tl;

    // Reserve 100000 bytes plus one additional byte for random data
    // and for the status byte
    uint8_t rnd[100001];

    int resp = tl.open(0); // Open the first TL200 device available
    if (resp) {
        // Couldn`t open TL200 device
        return (resp);
    }
    // Download 100000 true random bytes from the TL200 device
    // using default (recommended) mode (SHA256)
    int status = tl.getBytes(rnd, 100000);

    if (status) {
        // Couldn`t retrieve random bytes from the TL200 device // Retrieve last error message
        char *errMessage = tl.getLastErrMsg();<!-- fix* -->
        tl.close();
        return status;
    }
    // Successfully retrieved 100000 true random bytes tl.close();
    return status;
}

User Interactive Mode (for Windows OS)

User Interactive Mode can be activated by sending a u single character (command) to the TL200 device using the GetRND software utility.

In this mode, you can perform the following:

Set a different power profile (5 power profiles are available based on speed vs power consumption)
Enable or disable specific statistical start-up test
Run statistical tests
Generate frequency data reports for random sources
Generate new user pass code
Retrieve device unique serial number

When entering this mode, you will be prompted to enter a valid pass code. For security reason, this unique access passcode is sent to you with the regular mail in a separate envelope.

Steps for activating the User Interactive Mode in Windows OS:

The TL200 device should be connected to the PC using one of the available USB 2.0 or 3.0 ports and the supplied USB extension cable.
Open a Command Prompt window and, using the command line, change the current directory to the directory location that contains getrnd.exe utility (it can be found in the windows\getrnd\Release folder)
Run the following command to activate User Interactive Mode: getrnd.exe -uis
Press the u single key. You will be prompted to enter the access passcode. Enter the passcode promptly within a limited amount of time.
Upon successful authentication your interactive mode will display the menu.
Follow the interactive menu options by selecting appropriate letters assigned to a specific menu item.
When finished, make sure you exit the user session back to command mode and then press . key to exit this software utility (or disconnect the TL200 device from the USB port and connect it back).

Using `/dev/tlrandom` device with non ROOT access permissions on Linux platforms

To enable a non ROOT user to access the /devtlrandom device, simply copy the supplied 80-tl-device-access.rules file to /etc/udev/rules.d/` location.

Software & Documentation Kit contents

Using with Windows XP/Vista/7/8 (32 bit or 64 bit) /8.1/10

Using with Linux (32 bits)

Using with Linux (64 bits)

Building and loading tlrandom kernel module with Linux

Using with macOS

Using the GetRND software utility

Using the EF (Entropy Feeder) software utility

Example C++ code for downloading random data

User Interactive Mode (for Windows OS)

Using /dev/tlrandom device with non ROOT access permissions on Linux platforms

Building and loading `tlrandom` kernel module with Linux

Using `/dev/tlrandom` device with non ROOT access permissions on Linux platforms