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