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