README

   1 NeuG - a random number generator implementation (for STM32F103)
   2
   3                                                            Version 0.03
   4                                                              2012-10-19
   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 fourth release of NeuG, which is still experimental.
  32 Basic features (generating random numbers) are stable, but newly added
  33 things like reGNUal support should be considered unstable.  Note that
  34 you need the snapshot of ChibiOS/RT (from trunk).  This means that it
  35 is covered by GNU GPL.  No "linking exception" option is available for
  36 the snapshot.
  37
  38
  39 FAQ
  40 ===
  41
  42 Q0: How NeuG device is good?
  43 A0: I believe it's good enough if we compare to other hardware RNGs.
  44     If its usage is as an entropy source for RNG-tools, or use for
  45     computer simulations, I think that it's good enough.  I evaluated
  46     it with rngtest of RNG-tools, NIST STS test suite and Dieharder.
  47     See the directory neug/test-results/.
  48 A0-dash: For better entropy device with embedded test, you could get
  49          EntropyKey.  See http://www.entropykey.co.uk/
  50 A0-double-dash: STM32F2xx and STM32F4xx have built-in TRNG, it would
  51                 be better for you (although the quality of randomness
  52                 looks not that good).
  53
  54 Q1: How fast is NeuG device?
  55 A1: It's more than 50 Ki-byte/second.
  56
  57 Q2: Should we check condition of noise sources?
  58 A2: Yes, we should.  Three continuous tests are implemented, following
  59     (Draft of) NIST SP 800-90B.  Those are Repetition Count Test,
  60     Adaptive Proportion Test (for 64 samples), and another Adaptive
  61     Proportion Test (for 4096 samples).  When it detect an error (it
  62     is really rare, but it could occur even for normal condition), the
  63     generation of random bits restart again.
  64
  65
  66 Targets
  67 =======
  68
  69 FST-01, STBee Mini, Olimex STM32-H103, CQ-STARM, and STBee are
  70 supported.
  71
  72
  73 Souce code
  74 ==========
  75
  76 NeuG source code is under src/ directory.
  77
  78
  79 License
  80 =======
  81
  82 It is distributed under GNU General Public Licence version 3 or later
  83 (GPLv3+).  Please see src/COPYING.
  84
  85
  86 External source code
  87 ====================
  88
  89 To build NeuG device, we need external source code.
  90
  91 * chibios/  -- ChibiOS/RT 2.3.x snapshot
  92
  93   Please get it from http://chibios.sourceforge.net/
  94   We use ChibiOS/RT as the kernel for NeuG device.
  95
  96
  97 How to compile
  98 ==============
  99
 100 You need GNU toolchain and newlib for 'arm-none-eabi' target.
 101
 102 See http://github.com/uwehermann/summon-arm-toolchain/ for preparation
 103 of GNU Toolchain for 'arm-none-eabi' target.
 104
 105 Change directory to `src':
 106
 107   $ cd neug-VERSION/src
 108
 109 Then, run `configure':
 110
 111   $ ./configure
 112
 113 Type:
 114
 115   $ make
 116
 117 Then, we will have "neug.elf".
 118
 119
 120 How to install
 121 ==============
 122
 123 STBee Mini and STBee
 124 --------------------
 125
 126 Reset the board with "USER" switch pushed.  Type following to write
 127 to flash:
 128
 129   # cd ../tool
 130   # ./dfuse.py ../src/neug.hex
 131
 132 Then, reset the board.
 133
 134
 135 Olimex STM32-H103 board
 136 -----------------------
 137
 138 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
 139
 140   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
 141
 142 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
 143
 144   $ telnet localhost 4444
 145   > reset halt
 146   > flash write_image erase neug.elf
 147   > reset
 148   > exit
 149   $
 150
 151
 152
 153 Use of NeuG device
 154 ==================
 155
 156 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
 157 Before using /dev/ttyACM0, you need to configure its TTY discipline.
 158
 159   $ stty -F /dev/ttyACM0 -echo raw
 160
 161 Then, you can use output of /dev/ttyACM0.
 162
 163 When you want to get raw output (not conditioned), you can configure:
 164
 165   $ stty -F /dev/ttyACM0 parenb parodd
 166
 167 for raw data after filter.  For direct raw data of samples, configure:
 168
 169   $ stty -F /dev/ttyACM0 parenb -parodd
 170
 171 And you can get conditioned output by configuring:
 172
 173   $ stty -F /dev/ttyACM0 -parenb
 174
 175
 176 Structure of the NeuG
 177 =====================
 178
 179 Here is a figure of the circuit.
 180
 181                                          Noise sources
 182
 183                               /|<---+--- [ Analog input Vref ]
 184                 16           | |<-+-|--- [ Analog input Temperature Sensor ]
 185              +---/-[ADC1] <==| |  | |
 186              |               | |<-+ |
 187       +-+    |                \|<---+
 188       | |<---+                |
 189  +----| |          MUX CTL >--+
 190  |    | |<---+
 191  |    +-+    |                /|
 192  |           |  16           | |<------- [ Analog input 0 ] (pull up to Vdd)
 193  |           +---/-[ADC2] <==| |
 194  |                           | |<------- [ Analog input 1 ] (pull up to Vdd)
 195  |                            \|
 196  |                            |
 197  |                 MUX CTL >--+
 198  |
 199  +------------------+         <============ (*1)
 200                     |
 201                     / 32
 202                     |
 203                     | Put 4 times to output 32-bit
 204                     V
 205             [ CRC-32 filter ]
 206                     |
 207                     |           Put 35 times to output 1120-bit
 208                     +---------------------------------+         <====== (*2)
 209                                                       |
 210                                                       / 32
 211                                                       |
 212                                               [ Entropy Buffer ]
 213                                                       |
 214             +--------------+                          |
 215             |              |                          |
 216             | Conditioning |            1120          |
 217             | Component    |<------------/------------+
 218             |              |
 219       +-----|  Hash_df     |
 220       |     |    by        |
 221       |     |  SHA-256     |
 222       |     |              |
 223       |     |              |  128
 224       |     |              |<--/--+
 225       |     +--------------+      |
 226       |                           |
 227       +---------------------------+
 228       |
 229       / 256
 230       |
 231       v
 232  Random Number Output <========== (*3)
 233
 234
 235
 236 Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
 237 parodd, and (*1) with parenb 0parodd.
 238
 239 STM32F103 has two built-in A/D converters.  NeuG uses A/D converters'
 240 outputs as entropy sources.  It is considered noise of quantization
 241 error, plus noise from power supply, etc.
 242
 243 We chose four analog input sources of: built-in voltage reference,
 244 temperature sensor and two analog inputs which are pull-up to Vdd.
 245
 246 By a single sampling of two channel, we get 32-bit (not all 32-bit is
 247 valid, as a A/D converter resolution is 12-bit only).  We take four
 248 sampling of different combinations: (Vref, IN0), (Temp, IN1), (Vref,
 249 IN1), and (Temp, IN0).  Those 32-bit * 4 is fed into CRC32 filter.
 250
 251 We use STM32F103's CRC32 calculation unit as a kind of filter.  We put
 252 output of A/D converters into CRC32 calculation unit, four times, to
 253 get 4-byte output.
 254
 255 Output of CRC32 filter is collected 35 times, and it becomes 1120-bit
 256 (32 * 35).  This is the noise source bits.
 257
 258 We put this 1120-bit and half of previous output (128-bit) to
 259 conditioning component.
 260
 261 Conditioning Component is implemented by Hash_df function which is
 262 composed by SHA-256.  Since the noise source is not "white", signal is
 263 whiten by this Conditioning Component.
 264
 265 My experience with STM32F103 and NeuG shows that noise source is
 266 stable at least for a year.
 267
 268
 269 Test results
 270 ============
 271
 272 See files under the directory test-results, for test result of
 273 "rngtest" in rng-tools, NIST STS 2.1.1, and Dieharder.
 274
 275 For Dieharder, I correct 13GiB (it took five days and six hours
 276 and more), and use scripts to invoke dieharder.
 277
 278
 279 Read-only Git Repository
 280 ========================
 281
 282 You can browse at http://www.gniibe.org/gitweb?p=neug.git;a=summary
 283
 284 You can get it by:
 285
 286   $ git clone git://www.gniibe.org/neug.git/
 287
 288 or
 289
 290   $ git clone http://www.gniibe.org/git/neug.git/
 291
 292
 293 I put ChibiOS/RT as a submodule of Git.  Please do this:
 294
 295   $ git submodule init
 296   $ git submodule update
 297
 298
 299
 300 Information on the Web
 301 ======================
 302
 303 Not yet.
 304
 305
 306
 307 Your Contributions
 308 ==================
 309
 310 FSIJ welcomes your contributions.  Please assign your copyright
 311 to FSIJ (if possible).
 312 --