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