Page last updated: Sun Apr 23 23:14:36 CDT 2017

Table of contents

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) {
    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();
        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:

  1. 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.
  2. 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)
  3. Run the following command to activate User Interactive Mode: getrnd.exe -uis
  4. Press the ‘u’ single key. You will be prompted to enter the access passcode. Enter the passcode promptly within a limited amount of time.
  5. Upon successful authentication your interactive mode will display the menu.
  6. Follow the interactive menu options by selecting appropriate letters assigned to a specific menu item.
  7. 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 ’/dev’tlrandom’ device, simply copy the supplied ’80-tl-device-access.rules’ file to ‘/etc/udev/rules.d/’ location.