minor fix for flash_page_size.
[gnuk/neug.git] / README
1 NeuG - a true random number generator implementation (for STM32F103)
2
3                                                           Version 1.0.5
4                                                              2015-10-17
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 fifth 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 about 80 kB/sec for conditioned output (by SHA-256), and 
57     about 270 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 Q4: Configuring by 'stty' doesn't work, what's up?
75 A4: Common problem on GNU/Linux is the "modemmanager" try to control
76     /dev/ttyACM0, which interferes.  Please consider removing
77     modemmanager from your system or configure it to ignore NeuG
78     device.  For detail, please see the FST-01 support pages on the
79     web.
80
81
82 Targets
83 =======
84
85 FST-01, Nitrokey-Start, Olimex STM32-H103, STM32 part of STM8S
86 Discovery Kit, STBee Mini, STBee, STM32 Primer 2, CQ STARM, ST Dongle
87 and STM32 Nucleo F103 are supported.
88
89
90 Build system and Host system
91 ============================
92
93 Makefile is written for GNU make.  You need Bash 4.x for configure.
94
95 If your bash is not installed as /bin/bash, you need to run configure
96 script prepending 'bash' before './configure'.
97
98 Some tools are written in Python.  If your Python is not installed as
99 /usr/bin/python, please prepend 'python' for your command invocation.
100 Python 2.7 and PyUSB 0.4.3 is assumed.  I also use Python 3.5 and
101 PyUSB 1.0.0.
102
103
104 Souce code
105 ==========
106
107 NeuG source code is under src/ directory.
108
109 Note that SHA-256 hash function implementation, src/sha256.c, is based
110 on the original implementation by Dr. Brian Gladman.  See:
111
112   http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php
113
114
115 License
116 =======
117
118 It is distributed under GNU General Public Licence version 3 or later
119 (GPLv3+).  Please see src/COPYING.
120
121
122 External source code
123 ====================
124
125 NeuG is distributed with external source code.
126
127 * chopstx/ -- Chopstx, the RT Thread Library
128
129 * [optional] fraucheky/ -- Fraucheky, the GPL container
130
131 Those are available at:
132
133   https://anonscm.debian.org/cgit/gnuk/chopstx/
134
135
136 USB vendor ID and product ID (USB device ID)
137 ============================================
138
139 When you have a vender ID and assign a product ID for NeuG, edit the
140 file NEUG_USB_DEVICE_ID and add an entry for yours.  In this case,
141 please contact Niibe, so that it is listed to the file in the official
142 release of the source code.
143
144 When you are modifing NeuG and installing the binary to device, you
145 should replace the vendor string to yours, so that users can see it's
146 not by original vendor, and it is modified version.
147
148 FSIJ allows you to use USB device ID of FSIJ (234b:0001) for devices
149 with standalone NeuG under one of following conditions:
150
151   * For everyone for experimental purpose:
152
153     - You must not distribute a binary with FSIJ's USB device ID, but
154       must use the binary by yourself only for your experiment.  Note
155       that "Distributing binary" includes distributing a device which
156       holds the binary.
157
158   * For individuals:
159
160     - No additional conditions.
161
162 FSIJ could give companies or business entities "second source
163 manufacturer" license to use USB device ID of FSIJ for devices with
164 unmodified version of NeuG, provided they support Free Software and
165 respect users' freedom for computing.  Please ask FSIJ for the
166 license.
167
168 Otherwise, companies which want to distribute NeuG devices, please use
169 your own USB vendor ID and product ID.  Please replace vendor string
170 and possibly product string to yours, when you modify NeuG.
171
172
173 How to compile
174 ==============
175
176 You need GNU toolchain and newlib for 'arm-none-eabi' target.
177
178 On Debian we can install the packages of gcc-arm-none-eabi,
179 gdb-arm-none-eabi and its friends.  I'm using:
180
181         binutils-arm-none-eabi  2.26-4+8
182         gcc-arm-none-eabi       15:4.9.3+svn231177-1
183         gdb-arm-none-eabi       7.10-1+9
184         libnewlib-arm-none-eabi 2.2.0+git20150830.5a3d536-1
185
186 Or else, see https://launchpad.net/gcc-arm-embedded for preparation of
187 GNU Toolchain for 'arm-none-eabi' target.
188
189 Change directory to `src':
190
191   $ cd neug-VERSION/src
192
193 Then, run `configure':
194
195   $ ./configure --vidpid=<VID:PID>
196
197 Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
198 it's: --vidpid=234b:0001 .  Please read section 'USB vendor ID and
199 product ID' above.
200
201
202 Type:
203
204   $ make
205
206 Then, we will have "neug.elf" under the "build" directory.
207
208
209 How to install
210 ==============
211
212 Olimex STM32-H103 board
213 -----------------------
214
215 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
216
217   $ openocd -f interface/ftdi/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
218
219 Then, with another terminal, type following to write "neug.elf" to Flash ROM:
220
221   $ telnet localhost 4444
222   > reset halt
223   > flash write_image erase neug.elf
224   > reset
225   > exit
226   $ 
227
228
229 Flying Stone Tiny 01 and STM8S Discovery Kit
230 --------------------------------------------
231
232 If you are using Flying Stone Tiny 01, you need a SWD writer.
233
234 OpenOCD 0.6.1 or newer supports ST-Link/V2.  With that we can do:
235
236   $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
237
238 Then, with another terminal, type following to write "neug.elf" to Flash ROM:
239
240   $ telnet localhost 4444
241   > reset halt
242   > flash write_image erase neug.elf
243   > reset
244   > exit
245   $ 
246
247 Note that OpenOCD (as of 0.7.0) doesn't support option bytes handling yet.
248
249 You can also use tool/stlinkv2.py in Gnuk.
250
251
252 Use of NeuG device
253 ==================
254
255 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
256 Before using /dev/ttyACM0, you need to configure its TTY discipline.
257
258   $ stty -F /dev/ttyACM0 -echo raw
259
260 Then, you can use output of /dev/ttyACM0.
261
262 When you want to get CRC-32 filtered output, you can configure:
263
264   $ stty -F /dev/ttyACM0 parenb parodd
265
266 for raw data after filter.  For direct raw data of ADC samples,
267 configure:
268
269   $ stty -F /dev/ttyACM0 parenb -parodd
270
271 And you can get SHA-256 conditioned output by configuring:
272
273   $ stty -F /dev/ttyACM0 -parenb
274
275
276 If your device is configured with Fraucheky, you can invoke Fraucheky
277 from NeuG by setting the unusual sequence of configurations:
278
279   $ stty -F /dev/ttyACM0 ispeed 110 ospeed 110
280   $ stty -F /dev/ttyACM0 ispeed 115200 ospeed 115200
281
282
283 Structure of NeuG
284 =================
285
286 Here is a figure of the circuit.
287
288                                          Noise sources
289
290                               /|<---+--- [ Analog input Vref ]
291                 16           | |<-+-|--- [ Analog input Temperature Sensor ]
292              +---/-[ADC1] <==| |  | |
293              |               | |<-+ |
294       +-+    |                \|<---+
295       | |<---+                |
296  +----| |          MUX CTL >--+
297  |    | |<---+
298  |    +-+    |                /|
299  |           |  16           | |<------- [ Analog input 0 ] (pull up to Vdd)
300  |           +---/-[ADC2] <==| |
301  |                           | |<------- [ Analog input 1 ] (pull up to Vdd)
302  |                            \|
303  |                            |
304  |                 MUX CTL >--+
305  |
306  +------------------+         <============ (*1)
307                     |
308                     / 32
309                     |
310                     | Put 4 times to output 32-bit
311                     V
312             [ CRC-32 filter ]
313                     |
314                     |           Put 35 times to output 1120-bit
315                     +---------------------------------+         <====== (*2)
316                                                       |
317                                                       / 32
318                                                       |
319                                                       V
320                                               [ Entropy Buffer ]
321                                                       |          
322             +--------------+                          |
323             |              |                          |
324             | Conditioning |            1120          |
325             | Component    |<------------/------------+
326             |              |
327       +-----|  Hash_df     |
328       |     |    by        |
329       |     |  SHA-256     |
330       |     |              |  128
331       |     |              |<--/--+
332       |     +--------------+      |
333       |                           |
334       +---------------------------+
335       |
336       / 256
337       |
338       v
339  Random Number Output <========== (*3)
340
341
342
343 Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
344 parodd, and (*1) with parenb -parodd.
345
346 STM32F103 has two built-in A/D converters.  NeuG uses A/D converters'
347 outputs as entropy sources.  It is considered noise of quantization
348 error, plus noise from power supply, etc.
349
350 We chose four analog input sources of: built-in voltage reference,
351 temperature sensor and two analog inputs which are pull-up to Vdd.
352
353 By a single sampling of two channels, we get 32-bit (not all 32-bit is
354 valid, as a A/D converter resolution is 12-bit only).  We take four
355 sampling of combinations: (Vref, IN0), (Temp, IN1), (Vref, IN1), and
356 (Temp, IN0).  Those 32-bit * 4 is fed into CRC32 filter.
357
358 We use STM32F103's CRC32 calculation unit as a kind of filter.  We put
359 output of A/D converters into CRC32 calculation unit, four times, to
360 get 4-byte output.
361
362 Output of CRC32 filter is collected 35 times, and it becomes 1120-bit
363 (32 * 35).  This is the noise source bits.
364
365 We put this 1120-bit and half of previous output (128-bit) to
366 conditioning component.
367
368 Conditioning Component is implemented by Hash_df function which is
369 composed by SHA-256.  Since the noise source is not "white", signal is
370 whiten by this Conditioning Component.
371
372 My experience with STM32F103 and NeuG shows that noise source is
373 stable at least for a year.
374
375
376 Test results
377 ============
378
379 See files under the directory test-results, for test result of
380 PractRand 0.92.
381
382 I collect 140 files of 125MB (>= 16GiB), and run the test suite of
383 PractRand 0.92.  Collecting 140 files, it took two days and a half.
384
385
386 Git Repository
387 ==============
388
389 NeuG is available in the Gnuk repository at:
390
391     https://anonscm.debian.org/cgit/gnuk/gnuk/
392
393 You can get it by:
394
395     $ git clone git://anonscm.debian.org/gnuk/gnuk/neug.git
396
397
398 I put Chopstx and Fraucheky as a submodules of Git.  Please do this:
399
400   $ git submodule init
401   $ git submodule update
402
403
404
405 Information on the Web
406 ======================
407
408 Please see the FST-01 support pages:
409
410     http://www.gniibe.org/category/fst-01.html
411
412 Please consider to join Gnuk-users mailing list:
413
414     https://lists.alioth.debian.org/mailman/listinfo/gnuk-users
415
416
417
418 Your Contributions
419 ==================
420
421 FSIJ welcomes your contributions.  Please assign your copyright
422 to FSIJ (if possible).
423
424
425 Foot note
426 ==========
427
428 If NeuG had a family name, it must be Kunisada.
429 --