new boards tested
[gnuk/neug.git] / README
1 NeuG - a true random number generator implementation (for STM32F103)
2
3                                                           Version 1.0.3
4                                                              2015-0X-XX
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 third minor release of NeuG, after 1.0.
32
33 Basic features (generating random numbers) are stable, but newly added
34 things like Fraucheky (USB Mass Storage Class) support and reGNUal
35 (firmware upgrad) support should be considered experimental.
36
37 Note that you need Chopstx (the thread library) as external source
38 code (instead of ChibiOS/RT).  If you get the source code by Git,
39 Chopstx is submodule of neug.
40
41
42 FAQ
43 ===
44
45 Q0: How NeuG device is good?
46 A0: I believe it's good enough if we compare to other hardware RNGs.
47     I evaluated it with rngtest of RNG-tools, NIST STS test suite and
48     Dieharder.  See the directory neug/test-results/.
49 A0-dash: For better entropy device with embedded test, you could get
50          EntropyKey.  See http://www.entropykey.co.uk/
51 A0-double-dash: STM32F2xx and STM32F4xx have built-in TRNG, it would
52                 be better for you (although the quality of randomness
53                 looks not that good).
54
55 Q1: How fast is NeuG device?
56 A1: It's more than 80 kB/sec for conditioned output (by SHA-256), and
57     more than 280 kB/sec for CRC-32 filtered output (kB = 1000 byte).
58
59 Q2: Should we check condition of noise sources?
60 A2: Yes, we should.  Three continuous tests are implemented, following
61     (Draft of) NIST SP 800-90B.  Those are Repetition Count Test,
62     Adaptive Proportion Test (for 64 samples), and another Adaptive
63     Proportion Test (for 4096 samples).  When it detects an error (it
64     is really rare, but it could occur even for normal condition), the
65     generation of random bits restart again.
66
67 Q3: Conditioning with SHA-256 sounds over-kill.  Why not simpler?
68 A3: It is because NIST SP 800-90B mandates something like that for
69     "full entropy source".  If your usage is as an entropy source for
70     RNG-tools to feed entropy to your kernel, or use for computer
71     simulations, I think that CRC-32 filtered output would be good
72     enough.
73
74
75 Targets
76 =======
77
78 FST-01, Olimex STM32-H103, and STM32 part of STM8S Discovery Kit,
79 STBee Mini, and STBee are supported.
80
81
82 Build system and Host system
83 ============================
84
85 Makefile is written for GNU make.  You need Bash 4.x for configure.
86
87 If your bash is not installed as /bin/bash, you need to run configure
88 script prepending 'bash' before './configure'.
89
90 Some tools are written in Python.  If your Python is not installed as
91 /usr/bin/python, please prepend 'python' for your command invocation.
92 Python 2.7 and PyUSB 0.4.3 is assumed.
93
94
95 Souce code
96 ==========
97
98 NeuG source code is under src/ directory.
99
100 Note that SHA-256 hash function implementation, src/sha256.c, is based
101 on the original implementation by Dr. Brian Gladman.  See:
102
103   http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php
104
105
106 License
107 =======
108
109 It is distributed under GNU General Public Licence version 3 or later
110 (GPLv3+).  Please see src/COPYING.
111
112
113 External source code
114 ====================
115
116 NeuG is distributed with external source code.
117
118 * chopstx/ -- Chopstx, the RT Thread Library
119
120 * [optional] fraucheky/ -- Fraucheky, the GPL container
121
122 Those are available at:
123
124   https://anonscm.debian.org/cgit/gnuk/chopstx/
125
126
127 USB vendor ID and product ID (USB device ID)
128 ============================================
129
130 When you have a vender ID and assign a product ID for NeuG, edit the
131 file NEUG_USB_DEVICE_ID and add an entry for yours.  In this case,
132 please contact Niibe, so that it is listed to the file in the official
133 release of the source code.
134
135 When you are modifing NeuG and installing the binary to device, you
136 should replace the vendor string to yours, so that users can see it's
137 not by original vendor, and it is modified version.
138
139 FSIJ allows you to use USB device ID of FSIJ (234b:0001) for devices
140 with standalone NeuG under one of following conditions:
141
142   * For everyone for experimental purpose:
143
144     - You must not distribute a binary with FSIJ's USB device ID, but
145       must use the binary by yourself only for your experiment.  Note
146       that "Distributing binary" includes distributing a device which
147       holds the binary.
148
149   * For individuals:
150
151     - No additional conditions.
152
153 FSIJ could give companies or business entities "second source
154 manufacturer" license to use USB device ID of FSIJ for devices with
155 unmodified version of NeuG, provided they support Free Software and
156 respect users' freedom for computing.  Please ask FSIJ for the
157 license.
158
159 Otherwise, companies which want to distribute NeuG devices, please use
160 your own USB vendor ID and product ID.  Please replace vendor string
161 and possibly product string to yours, when you modify NeuG.
162
163
164 How to compile
165 ==============
166
167 You need GNU toolchain and newlib for 'arm-none-eabi' target.
168
169 See https://launchpad.net/gcc-arm-embedded for preparation
170 of GNU Toolchain for 'arm-none-eabi' target.
171
172 Change directory to `src':
173
174   $ cd neug-VERSION/src
175
176 Then, run `configure':
177
178   $ ./configure --vidpid=<VID:PID>
179
180 Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
181 it's: --vidpid=234b:0001 .  Please read section 'USB vendor ID and
182 product ID' above.
183
184
185 Type:
186
187   $ make
188
189 Then, we will have "neug.elf" under the "build" directory.
190
191
192 How to install
193 ==============
194
195 Olimex STM32-H103 board
196 -----------------------
197
198 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
199
200   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
201
202 Then, with another terminal, type following to write "neug.elf" to Flash ROM:
203
204   $ telnet localhost 4444
205   > reset halt
206   > flash write_image erase neug.elf
207   > reset
208   > exit
209   $ 
210
211
212 Flying Stone Tiny 01 and STM8S Discovery Kit
213 --------------------------------------------
214
215 If you are using Flying Stone Tiny 01, you need a SWD writer.
216
217 OpenOCD 0.6.1 or newer supports ST-Link/V2.  With that we can do:
218
219   $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
220
221 Then, with another terminal, type following to write "neug.elf" to Flash ROM:
222
223   $ telnet localhost 4444
224   > reset halt
225   > flash write_image erase neug.elf
226   > reset
227   > exit
228   $ 
229
230 Note that OpenOCD (as of 0.7.0) doesn't support option bytes handling yet.
231
232 You can also use tool/stlinkv2.py in Gnuk.
233
234
235 Use of NeuG device
236 ==================
237
238 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
239 Before using /dev/ttyACM0, you need to configure its TTY discipline.
240
241   $ stty -F /dev/ttyACM0 -echo raw
242
243 Then, you can use output of /dev/ttyACM0.
244
245 When you want to get CRC-32 filtered output, you can configure:
246
247   $ stty -F /dev/ttyACM0 parenb parodd
248
249 for raw data after filter.  For direct raw data of ADC samples,
250 configure:
251
252   $ stty -F /dev/ttyACM0 parenb -parodd
253
254 And you can get SHA-256 conditioned output by configuring:
255
256   $ stty -F /dev/ttyACM0 -parenb
257
258
259 Structure of NeuG
260 =================
261
262 Here is a figure of the circuit.
263
264                                          Noise sources
265
266                               /|<---+--- [ Analog input Vref ]
267                 16           | |<-+-|--- [ Analog input Temperature Sensor ]
268              +---/-[ADC1] <==| |  | |
269              |               | |<-+ |
270       +-+    |                \|<---+
271       | |<---+                |
272  +----| |          MUX CTL >--+
273  |    | |<---+
274  |    +-+    |                /|
275  |           |  16           | |<------- [ Analog input 0 ] (pull up to Vdd)
276  |           +---/-[ADC2] <==| |
277  |                           | |<------- [ Analog input 1 ] (pull up to Vdd)
278  |                            \|
279  |                            |
280  |                 MUX CTL >--+
281  |
282  +------------------+         <============ (*1)
283                     |
284                     / 32
285                     |
286                     | Put 4 times to output 32-bit
287                     V
288             [ CRC-32 filter ]
289                     |
290                     |           Put 35 times to output 1120-bit
291                     +---------------------------------+         <====== (*2)
292                                                       |
293                                                       / 32
294                                                       |
295                                                       V
296                                               [ Entropy Buffer ]
297                                                       |          
298             +--------------+                          |
299             |              |                          |
300             | Conditioning |            1120          |
301             | Component    |<------------/------------+
302             |              |
303       +-----|  Hash_df     |
304       |     |    by        |
305       |     |  SHA-256     |
306       |     |              |  128
307       |     |              |<--/--+
308       |     +--------------+      |
309       |                           |
310       +---------------------------+
311       |
312       / 256
313       |
314       v
315  Random Number Output <========== (*3)
316
317
318
319 Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
320 parodd, and (*1) with parenb -parodd.
321
322 STM32F103 has two built-in A/D converters.  NeuG uses A/D converters'
323 outputs as entropy sources.  It is considered noise of quantization
324 error, plus noise from power supply, etc.
325
326 We chose four analog input sources of: built-in voltage reference,
327 temperature sensor and two analog inputs which are pull-up to Vdd.
328
329 By a single sampling of two channels, we get 32-bit (not all 32-bit is
330 valid, as a A/D converter resolution is 12-bit only).  We take four
331 sampling of combinations: (Vref, IN0), (Temp, IN1), (Vref, IN1), and
332 (Temp, IN0).  Those 32-bit * 4 is fed into CRC32 filter.
333
334 We use STM32F103's CRC32 calculation unit as a kind of filter.  We put
335 output of A/D converters into CRC32 calculation unit, four times, to
336 get 4-byte output.
337
338 Output of CRC32 filter is collected 35 times, and it becomes 1120-bit
339 (32 * 35).  This is the noise source bits.
340
341 We put this 1120-bit and half of previous output (128-bit) to
342 conditioning component.
343
344 Conditioning Component is implemented by Hash_df function which is
345 composed by SHA-256.  Since the noise source is not "white", signal is
346 whiten by this Conditioning Component.
347
348 My experience with STM32F103 and NeuG shows that noise source is
349 stable at least for a year.
350
351
352 Test results
353 ============
354
355 See files under the directory test-results, for test result of
356 "rngtest" in rng-tools, NIST STS 2.1.1, Dieharder, and PractRand 0.92.
357
358 I collect 110 files of 125MB (= 13750MB), and use scripts to invoke
359 dieharder and rngtest.  Collecting 110 files, it took more than two
360 days.
361
362 For NIST STS 2.1.1, I used only 10 files of size 125MB.
363
364
365 Git Repository
366 ==============
367
368 NeuG is available in the Gnuk repository at:
369
370     https://anonscm.debian.org/cgit/gnuk/gnuk/
371
372 You can get it by:
373
374     $ git clone git://anonscm.debian.org/gnuk/gnuk/neug.git
375
376
377 I put Chopstx and Fraucheky as a submodules of Git.  Please do this:
378
379   $ git submodule init
380   $ git submodule update
381
382
383
384 Information on the Web
385 ======================
386
387 Please see the FST-01 support pages:
388
389     http://www.gniibe.org/category/fst-01.html
390
391 Please consider to join Gnuk-users mailing list:
392
393     https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
394
395
396
397 Your Contributions
398 ==================
399
400 FSIJ welcomes your contributions.  Please assign your copyright
401 to FSIJ (if possible).
402
403
404 Foot note
405 ==========
406
407 If NeuG had a family name, it must be Kunisada.
408 --