README

   1 NeuG - a true random number generator implementation (for STM32F103)
   2
   3                                                            Version 0.05
   4                                                              2013-02-07
   5                                                            Niibe Yutaka
   6                                       Free Software Initiative of Japan
   7
   8 What's NeuG?
   9 ============
  10
  11 NeuG is a set of routines of random number generator (RNG) which is
  12 based on physical noise.  It supports STM32F103.  It can be stand
  13 alone USB RNG device (with main routine), too.
  14
  15 The name comes from Japanized English word "noidgy" (from English word
  16 "noisy"), where many Japanese (including me) don't distinguish
  17 pronunciations of "gee" and "zee".  NeuG includes my important letters
  18 of "g", "n", and "u", and the word "neu" (German spelling of "new").
  19
  20 My primary intention was to incorporate NeuG routines into Gnuk for
  21 random number generation, but the stand alone version could be useful
  22 too.
  23
  24 Gnuk was named after my son who loved the pacifier when he was baby.
  25 NeuG was named after my daughter, but I don't say she is noisy.
  26
  27
  28 Release notes
  29 =============
  30
  31 This is the sixth release of NeuG, which is still experimental.  Basic
  32 features (generating random numbers) are stable, but newly added
  33 things like reGNUal support should be considered unstable.  Note that
  34 you need ChibiOS/RT 2.4.x as external source code.
  35
  36
  37 FAQ
  38 ===
  39
  40 Q0: How NeuG device is good?
  41 A0: I believe it's good enough if we compare to other hardware RNGs.
  42     I evaluated it with rngtest of RNG-tools, NIST STS test suite and
  43     Dieharder.  See the directory neug/test-results/.
  44 A0-dash: For better entropy device with embedded test, you could get
  45          EntropyKey.  See http://www.entropykey.co.uk/
  46 A0-double-dash: STM32F2xx and STM32F4xx have built-in TRNG, it would
  47                 be better for you (although the quality of randomness
  48                 looks not that good).
  49
  50 Q1: How fast is NeuG device?
  51 A1: It's more than 50 Ki-byte/sec for conditioned output (by SHA-256),
  52     and more than 140 Ki-byte/sec for CRC-32 filtered output.
  53
  54 Q2: Should we check condition of noise sources?
  55 A2: Yes, we should.  Three continuous tests are implemented, following
  56     (Draft of) NIST SP 800-90B.  Those are Repetition Count Test,
  57     Adaptive Proportion Test (for 64 samples), and another Adaptive
  58     Proportion Test (for 4096 samples).  When it detect an error (it
  59     is really rare, but it could occur even for normal condition), the
  60     generation of random bits restart again.
  61
  62 Q3: Conditioning with SHA-256 sounds over-kill.  Why not simpler?
  63 A3: It is because NIST SP 800-90B mandates something like that for
  64     "full entropy source".  If your usage is as an entropy source for
  65     RNG-tools to feed entropy to your kernel, or use for computer
  66     simulations, I think that CRC32 filter would be good enough.  You
  67     can configure NeuG device by "stty -F /dev/ttyACM0 parenb parodd"
  68     to get raw data before SHA-256 conditioning component.  With
  69     high speed hub, you'll get more than 240 Ki-byte/second .
  70
  71
  72 Targets
  73 =======
  74
  75 FST-01, STBee Mini, Olimex STM32-H103, CQ-STARM, and STBee are
  76 supported.
  77
  78
  79 Souce code
  80 ==========
  81
  82 NeuG source code is under src/ directory.
  83
  84
  85 License
  86 =======
  87
  88 It is distributed under GNU General Public Licence version 3 or later
  89 (GPLv3+).  Please see src/COPYING.
  90
  91
  92 External source code
  93 ====================
  94
  95 To build NeuG device, you need external source code.
  96
  97 * chibios/  -- ChibiOS/RT 2.4.x
  98
  99   Please get it from http://chibios.sourceforge.net/
 100   We use ChibiOS/RT as the kernel for NeuG device.
 101
 102
 103 USB vendor ID and product ID (USB device ID)
 104 ============================================
 105
 106 When you have a vender ID and assign a product ID for NeuG, edit the
 107 file NEUG_USB_DEVICE_ID and add an entry for yours.  In this case,
 108 please contact Niibe, so that it is listed to the file in the official
 109 release of the source code.
 110
 111 When you are modifing NeuG and installing the binary to device, you
 112 should replace the vendor string to yours, so that users can see it's
 113 not by original vendor, and it is modified version.
 114
 115 FSIJ allows you to use USB device ID of FSIJ (234b:0001) for devices
 116 with standalone NeuG under one of following conditions:
 117
 118   * For everyone for experimental purpose:
 119
 120     - You must not distribute a binary with FSIJ's USB device ID, but
 121       must use the binary by yourself only for your experiment.  Note
 122       that "Distributing binary" includes distributing a device which
 123       holds the binary.
 124
 125   * For general individuals:
 126
 127     - No additional conditions.
 128
 129   * For individuals with explicit permission from FSIJ.
 130
 131     - No additional conditions.
 132
 133 FSIJ could give companies or business entities "second source
 134 manufacturer" license to use USB device ID of FSIJ for devices with
 135 unmodified version of NeuG, provided they support Free Software and
 136 respect users' freedom for computing.  Please ask FSIJ for the
 137 license.
 138
 139 Otherwise, companies which want to distribute NeuG devices, please use
 140 your own USB vendor ID and product ID.  Please replace vendor string
 141 and possibly product string to yours, when you modify NeuG.
 142
 143
 144 How to compile
 145 ==============
 146
 147 You need GNU toolchain and newlib for 'arm-none-eabi' target.
 148
 149 See https://launchpad.net/gcc-arm-embedded for preparation
 150 of GNU Toolchain for 'arm-none-eabi' target.
 151
 152 Change directory to `src':
 153
 154   $ cd neug-VERSION/src
 155
 156 Then, run `configure':
 157
 158   $ ./configure
 159
 160 Type:
 161
 162   $ make
 163
 164 Then, we will have "neug.elf".
 165
 166
 167 How to install
 168 ==============
 169
 170 STBee Mini and STBee
 171 --------------------
 172
 173 Reset the board with "USER" switch pushed.  Type following to write
 174 to flash:
 175
 176   # cd ../tool
 177   # ./dfuse.py ../src/neug.hex
 178
 179 Then, reset the board.
 180
 181
 182 Olimex STM32-H103 board
 183 -----------------------
 184
 185 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
 186
 187   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
 188
 189 Then, with another terminal, type following to write "neug.elf" to Flash ROM:
 190
 191   $ telnet localhost 4444
 192   > reset halt
 193   > flash write_image erase neug.elf
 194   > reset
 195   > exit
 196   $
 197
 198
 199
 200 Use of NeuG device
 201 ==================
 202
 203 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
 204 Before using /dev/ttyACM0, you need to configure its TTY discipline.
 205
 206   $ stty -F /dev/ttyACM0 -echo raw
 207
 208 Then, you can use output of /dev/ttyACM0.
 209
 210 When you want to get raw output (not conditioned), you can configure:
 211
 212   $ stty -F /dev/ttyACM0 parenb parodd
 213
 214 for raw data after filter.  For direct raw data of ADC samples,
 215 configure:
 216
 217   $ stty -F /dev/ttyACM0 parenb -parodd
 218
 219 And you can get conditioned output by configuring:
 220
 221   $ stty -F /dev/ttyACM0 -parenb
 222
 223
 224 Structure of NeuG
 225 =================
 226
 227 Here is a figure of the circuit.
 228
 229                                          Noise sources
 230
 231                               /|<---+--- [ Analog input Vref ]
 232                 16           | |<-+-|--- [ Analog input Temperature Sensor ]
 233              +---/-[ADC1] <==| |  | |
 234              |               | |<-+ |
 235       +-+    |                \|<---+
 236       | |<---+                |
 237  +----| |          MUX CTL >--+
 238  |    | |<---+
 239  |    +-+    |                /|
 240  |           |  16           | |<------- [ Analog input 0 ] (pull up to Vdd)
 241  |           +---/-[ADC2] <==| |
 242  |                           | |<------- [ Analog input 1 ] (pull up to Vdd)
 243  |                            \|
 244  |                            |
 245  |                 MUX CTL >--+
 246  |
 247  +------------------+         <============ (*1)
 248                     |
 249                     / 32
 250                     |
 251                     | Put 4 times to output 32-bit
 252                     V
 253             [ CRC-32 filter ]
 254                     |
 255                     |           Put 35 times to output 1120-bit
 256                     +---------------------------------+         <====== (*2)
 257                                                       |
 258                                                       / 32
 259                                                       |
 260                                                       V
 261                                               [ Entropy Buffer ]
 262                                                       |
 263             +--------------+                          |
 264             |              |                          |
 265             | Conditioning |            1120          |
 266             | Component    |<------------/------------+
 267             |              |
 268       +-----|  Hash_df     |
 269       |     |    by        |
 270       |     |  SHA-256     |
 271       |     |              |  128
 272       |     |              |<--/--+
 273       |     +--------------+      |
 274       |                           |
 275       +---------------------------+
 276       |
 277       / 256
 278       |
 279       v
 280  Random Number Output <========== (*3)
 281
 282
 283
 284 Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
 285 parodd, and (*1) with parenb -parodd.
 286
 287 STM32F103 has two built-in A/D converters.  NeuG uses A/D converters'
 288 outputs as entropy sources.  It is considered noise of quantization
 289 error, plus noise from power supply, etc.
 290
 291 We chose four analog input sources of: built-in voltage reference,
 292 temperature sensor and two analog inputs which are pull-up to Vdd.
 293
 294 By a single sampling of two channels, we get 32-bit (not all 32-bit is
 295 valid, as a A/D converter resolution is 12-bit only).  We take four
 296 sampling of combinations: (Vref, IN0), (Temp, IN1), (Vref, IN1), and
 297 (Temp, IN0).  Those 32-bit * 4 is fed into CRC32 filter.
 298
 299 We use STM32F103's CRC32 calculation unit as a kind of filter.  We put
 300 output of A/D converters into CRC32 calculation unit, four times, to
 301 get 4-byte output.
 302
 303 Output of CRC32 filter is collected 35 times, and it becomes 1120-bit
 304 (32 * 35).  This is the noise source bits.
 305
 306 We put this 1120-bit and half of previous output (128-bit) to
 307 conditioning component.
 308
 309 Conditioning Component is implemented by Hash_df function which is
 310 composed by SHA-256.  Since the noise source is not "white", signal is
 311 whiten by this Conditioning Component.
 312
 313 My experience with STM32F103 and NeuG shows that noise source is
 314 stable at least for a year.
 315
 316
 317 Test results
 318 ============
 319
 320 See files under the directory test-results, for test result of
 321 "rngtest" in rng-tools, NIST STS 2.1.1, and Dieharder.
 322
 323 I collect 110 files of 125MB (= 13750MB), and use scripts to invoke
 324 dieharder and rngtest.  Collecting 110 files, it took three days.
 325
 326 For NIST STS 2.1.1, I used only 10 files of size 125MB.
 327
 328
 329 Read-only Git Repository
 330 ========================
 331
 332 You can browse at http://www.gniibe.org/gitweb?p=neug.git
 333
 334 You can get it by:
 335
 336   $ git clone git://www.gniibe.org/neug.git/
 337
 338 or
 339
 340   $ git clone http://www.gniibe.org/git/neug.git/
 341
 342
 343 I put ChibiOS/RT as a submodule of Git.  Please do this:
 344
 345   $ git submodule init
 346   $ git submodule update
 347
 348
 349
 350 Information on the Web
 351 ======================
 352
 353 Please use FST-01 Q&A Forum at: http://no-passwd.net/askbot/questions/
 354
 355
 356
 357 Your Contributions
 358 ==================
 359
 360 FSIJ welcomes your contributions.  Please assign your copyright
 361 to FSIJ (if possible).
 362 --