Changeset 39 in Project Repository


Ignore:
Timestamp:
11/15/2020 08:03:07 PM (2 months ago)
Author:
pchapin
Message:

Added the first cut of a description of the system architecture.

Location:
trunk/doc
Files:
2 added
1 deleted
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/Architecture.tex

    r29 r39  
    66the architecture of the system and the architecture of the development environment. 
    77 
    8 \section{Overview} 
    9 \label{sec:overview} 
     8\section{System Architecture} 
    109 
     10The system architecture describes the structure of the deployed system. There are three aspects 
     11of the system to consider: 
     12 
     13\begin{enumerate} 
     14\item The hardware controller and noise generating hardware used as the source of randomness. 
     15\item The command language used between the host computer and the hardware controller. 
     16\item The driver and library software on the host computer. 
     17\end{enumerate} 
     18 
     19Each of these aspects are described in separate subsections below. 
     20 
     21\subsection{Hardware Architecture} 
     22 
     23The hardware controller consists of a low cost, single board microcontroller based on an ARM 
     24architecture processor. Specifically, we use the STM32F4DISCOVERY with the STM32F407VG 
     25microcontroller (32~bit ARM Cortex M4). In normal operation the controller is connected to a 
     26host computer as a USB slave via a USB 2.0 (or higher) interface. A virtual serial port is 
     27created on the USB interface so the controller appears as a serially connected device from the 
     28point of view of the host computer. 
     29 
     30Also connected to the controller, via it's general purpose I/O interface, is a supplementary 
     31board containing a white noise generator together with an appropriate analog to digital 
     32converter (ADC) to convert the generated noise into a stream of digital values. The word size of 
     33the ADC is 8~bits; if more bits are available, only the lower 8~bits are used. 
     34 
     35A software task on the controller reads the ADC ten times per second and appends the 8 bit value 
     36read to a buffer of random data 2~KiB in size called the ``entropy pool.'' The part of the pool 
     37that is filled with data is called the ``active pool.'' In normal operation, the pool is 
     38completely filled, and the active pool is the same as the whole pool. Initially, while the pool 
     39is filling (or later after some data has been extracted from it), the yellow LED on the 
     40controller is lite. When the pool is completely filled the green LED on the controller lights 
     41and the yellow LED turns off. The red LED on the controller is used to indicate an error 
     42condition. 
     43 
     44Once the pool is filled, whenever a new value is read from the ADC, the following steps are 
     45taken: 
     46 
     47\begin{enumerate} 
     48\item The entire pool is hashed using SHA-256 and the resulting hash value is appended to the 
     49  pool, causing the oldest 32~bytes to be discarded. 
     50\item The new value from the ADC is appended to the pool, causing the oldest byte to be 
     51  discarded. 
     52\end{enumerate} 
     53 
     54Thus 33~bytes are discarded from the pool for each new byte added. However, those bytes 
     55participate in the hash that gets appended (and that hash is further hashed again, etc.). 
     56 
     57A second task on the controller interacts with the USB interface, receiving commands from the 
     58host computer, interpreting those commands, and acting on them. This ``interface task'' prepares 
     59random data from the entropy pool in a separate buffer area with a size equal to the amount of 
     60random data requested (which might be smaller or larger than the size of the active pool). The 
     61task takes data from the pool, oldest data first, thereby reducing the active pool size, waiting 
     62for more data to appear in the pool if necessary to completely fill the result buffer. Note that 
     63when the pool is less than completely filled, the hashing process described above is temporarily 
     64suspended until the pool is filled. 
     65 
     66\subsection{Command Language} 
     67 
     68This subsection describes the command language used between the host computer and the hardware 
     69controller. These commands and their corresponding responses flow over a serial connection and, 
     70for convenience, are entirely ASCII text. The generator hardware never sends an unsolicited 
     71response. Furthermore, every command sent by the PC elicits a response of some kind (even if 
     72only a success code). This behavior facilities testing the generator hardware using a standard 
     73terminal emulation program. 
     74 
     75Every command and every response is terminated by a CR/LF pair. Lines will never exceed 80 
     76characters in length. If a command line is longer than 80 characters, the extra characters are 
     77ignored. Unless otherwise mentioned below, commands and responses are only one line. Unless 
     78otherwise mentioned below, responses are returned in a "timely" manner. Commands are case 
     79insensitive. 
     80 
     81\begin{verbatim} 
     82Command: CHECK 
     83Purpose: 
     84  Verify proper operation of the generator hardware 
     85 
     86Possile responses: 
     87   "!OK" 
     88   "!OK: STATISTICS UNKNOWN" 
     89   "!HARDWARE FAILURE: [message]" 
     90   "!BAD STATISTICS" 
     91   "!SOFTWARE FAILURE: [message]" 
     92   "!UNKNOWN ERROR." 
     93\end{verbatim} 
     94 
     95Note that support for hardware evaluation of statistics is not required. The generator hardware 
     96should probably provide a way to tell the calling software if it does statistical analysis or 
     97not. How that might be done is currently unspecified. 
     98 
     99\begin{verbatim} 
     100Command: GET IMMEDIATE n 
     101Purpose: 
     102  Obtain n bits of random data "immediately" (without blocking) 
     103 
     104Possible responses: 
     105  A string of '0' and '1' characters of size n bits 
     106  One of the same responses to the CHECK command 
     107  "!INSUFFICIENT DATA: n" 
     108\end{verbatim} 
     109 
     110Errors are indicated as for the CHECK command. The !INSUFFICIENT DATA response is sent if there 
     111is not enough entropy to satisfy the request immediately. The value of $n$ returned by 
     112!INSUFFICIENT DATA is the number of bits currently in the buffer. A GET IMMEDIATE with that 
     113value of $n$ or less will definitely succeed. Use GET IMMEDIATE 0 to elicit an insufficient data 
     114response regardless of the amount of data available, and to thus learn how much data is 
     115available. 
     116 
     117If <n> is greater than 80, the data will be delivered in multiple lines. The precise number of 
     118lines is unspecified, but no line will be blank. The value of $n$ in the GET IMMEDIATE command 
     119must be greater than or equal to zero. 
     120 
     121\begin{verbatim} 
     122Command: GET n 
     123Purpose: 
     124  Obtain n bits of random data, possibly blocking 
     125 
     126Possible responses: 
     127  A string of '0' and '1' characters of size n bits 
     128  One of the same responses to the CHECK command 
     129\end{verbatim} 
     130 
     131The returned data might be possibly split over several lines as described above, until a total 
     132of $n$ bits are returned. If all the bits are not yet available, the generator hardware will 
     133wait until they are, either returning the bits as they are produced (meaning in spurts) or in a 
     134single block once they are all produced. The generator hardware will accept no other commands 
     135while it is generating data. However, the unit may output an error response (as defined for the 
     136CHECK command) on a line by itself at any time during the random output. 
     137 
     138\subsection{Driver/Library Architecture} 
     139 
     140There are two parts to the software that runs on the computer host. The first part is a kernel 
     141level driver that presents a device file such that when the device file is read, random binary 
     142data is returned following the usual semantics for reading devices. The driver should also 
     143provide a ``raw'' mode that allows applications to write commands directly in the command 
     144language described above and read the corresponding responses. This allows applications to be 
     145built that interact directly with the controller hardware for special purposes. 
     146 
     147The second software component is a library that uses the device in its raw mode but presents a 
     148simple API to the application for reading random binary data. That that respect the library 
     149provides the same interface as the driver, except in application space. However, this allows the 
     150library to also do significant statistical analysis on the data stream before returning it to 
     151the application. That analysis can be used to monitor the statistical properties of the data and 
     152alert the application if any biases are found. The goal of the library is thus to keep the 
     153statistical analysis out of kernel space. 
     154 
     155\section{Development Environment Architecture} 
     156 
     157Since the development is done using SPARK/Ada, AdaCore's GPS is the primary development 
     158environment. That environment includes the ability to program and debug code on the 
     159STM32F4DISCOVERY board. See Section~\ref{chapt:test-plan} for more information about the test 
     160plan for the system. 
     161 
     162For convenience, the development platform is the same as the initial target platform: Ubuntu 
     163Linux 20.04. Driver development takes place inside a Virtual machine to avoid the possibility of 
     164destablizing the development platform while debugging the driver. 
  • trunk/doc/Requirements.tex

    r29 r39  
    77 
    88Random Thoughts consists of two parts: a hardware generator that attaches to the computer using 
    9 a standard USB version 1.1 connection, and a command interfaces for communicating with the 
     9a standard USB version 2.0 connection, and a command interface for communicating with the 
    1010generator hardware. The generator's direct I/O facilities shall consist of three LEDs as 
    1111follows. 
     
    2626all its power from the USB connection. No batteries or other adjustments are required. 
    2727 
    28 In addition the generator has a command language that detailing how the driver can interact with 
     28In addition the generator has a command language that details how the driver can interact with 
    2929the hardware. This command language shall be usable by third parties for building drivers on 
    3030systems not otherwise supported. 
     
    9292  art. 
    9393 
    94 \item \textbf{NonFun.Platform}. Random Thoughts shall support both 64 bit Windows 10 and 64 bit 
    95   Ubuntu Linux 14.04 LTS. The low level interface shall be sufficiently well documented so that 
    96   third parties could reasonably create drivers or interface libraries for other systems not 
    97   mentioned here. 
     94\item \textbf{NonFun.Platform}. Random Thoughts shall support both 64 bit Ubuntu Linux 20.04 
     95  LTS. The low level interface shall be sufficiently well documented so that third parties could 
     96  reasonably create drivers or interface libraries for other systems. 
    9897 
    9998\item \textbf{NonFun.Deployment}. Software installers, with appropriate digital signatures, 
  • trunk/doc/main.tex

    r29 r39  
    11%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    22% FILE    : main.tex 
    3 % AUTHOR  : (C) Copyright 2015 by Vermont Technical College 
     3% AUTHOR  : (C) Copyright 2020 by Vermont Technical College 
    44% SUBJECT : Documentation on the Hardware Random Number Generator. 
    55% 
     
    1212%    201 Lawrence Place 
    1313%    Williston, VT 05495 
    14 %    PChapin@vtc.vsc.edu 
     14%    pchapin@vtc.edu 
    1515%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
    1616 
     
    2323\usepackage{url} 
    2424\usepackage{hyperref} 
    25 %\setlength{\parindent}{0em} 
    26 %\setlength{\parskip}{1.75ex plus0.5ex minus0.5ex} 
     25 
     26\setlength{\parindent}{0em} 
     27\setlength{\parskip}{1.75ex plus0.5ex minus0.5ex} 
    2728 
    2829\input{macros} 
     
    3738%----------------------- 
    3839\title{Random Thoughts} 
    39 \author{\copyright\ Copyright 2015 by Vermont Technical College} 
     40\author{\copyright\ Copyright 2020 by Peter Chapin} 
    4041\date{Last Generated: \today} 
    4142\maketitle 
     
    6263\input{Architecture} 
    6364\input{Design} 
     65\input{Test} 
    6466\newpage 
    6567\input{Manual} 
Note: See TracChangeset for help on using the changeset viewer.