version 0.11
[gnuk/neug.git] / README
1 NeuG - a true random number generator implementation (for STM32F103)
2
3                                                            Version 0.11
4                                                              2013-08-22
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 new release of NeuG with Chopstx, version number bumped to
32 0.11.  Basic features (generating random numbers) are stable, but
33 newly added things like reGNUal support should be considered unstable.
34
35 Note that you need Chopstx (the thread library) as external source
36 code (instead of ChibiOS/RT).
37
38 The "boards" directory is obsolete one for old versions of NeuG with
39 ChibiOS/RT.  We leave it to port new NeuG to other boards.
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 50 Ki-byte/sec for conditioned output (by SHA-256),
57     and more than 140 Ki-byte/sec for CRC-32 filtered output.
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 CRC32 filtered output would be good
72     enough.  You can configure NeuG device by "stty -F /dev/ttyACM0
73     parenb parodd" to get raw data before SHA-256 conditioning
74     component.  With high speed hub, you'll get more than 240
75     Ki-byte/second .
76
77
78 Targets
79 =======
80
81 FST-01, Olimex STM32-H103, and STM32 part of STM8S Discovery Kit are
82 supported.  Porting to CQ-STARM, STBee Mini, and STBee is not that
83 hard.
84
85
86 Souce code
87 ==========
88
89 NeuG source code is under src/ directory.
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 To build NeuG device, you need external source code.
103
104 * chopstx/ -- Chopstx, the RT Thread Library
105
106 It is available at:
107
108   http://gitorious.org/chopstx/chopstx
109
110
111 USB vendor ID and product ID (USB device ID)
112 ============================================
113
114 When you have a vender ID and assign a product ID for NeuG, edit the
115 file NEUG_USB_DEVICE_ID and add an entry for yours.  In this case,
116 please contact Niibe, so that it is listed to the file in the official
117 release of the source code.
118
119 When you are modifing NeuG and installing the binary to device, you
120 should replace the vendor string to yours, so that users can see it's
121 not by original vendor, and it is modified version.
122
123 FSIJ allows you to use USB device ID of FSIJ (234b:0001) for devices
124 with standalone NeuG under one of following conditions:
125
126   * For everyone for experimental purpose:
127
128     - You must not distribute a binary with FSIJ's USB device ID, but
129       must use the binary by yourself only for your experiment.  Note
130       that "Distributing binary" includes distributing a device which
131       holds the binary.
132
133   * For individuals:
134
135     - No additional conditions.
136
137 FSIJ could give companies or business entities "second source
138 manufacturer" license to use USB device ID of FSIJ for devices with
139 unmodified version of NeuG, provided they support Free Software and
140 respect users' freedom for computing.  Please ask FSIJ for the
141 license.
142
143 Otherwise, companies which want to distribute NeuG devices, please use
144 your own USB vendor ID and product ID.  Please replace vendor string
145 and possibly product string to yours, when you modify NeuG.
146
147
148 How to compile
149 ==============
150
151 You need GNU toolchain and newlib for 'arm-none-eabi' target.
152
153 See https://launchpad.net/gcc-arm-embedded for preparation
154 of GNU Toolchain for 'arm-none-eabi' target.
155
156 Change directory to `src':
157
158   $ cd neug-VERSION/src
159
160 Then, run `configure':
161
162   $ ./configure --vidpid=<VID:PID>
163
164 Here, you need to specify USB vendor ID and product ID.  For FSIJ's,
165 it's: --vidpid=234b:0001 .  Please read section 'USB vendor ID and
166 product ID' above.
167
168
169 Type:
170
171   $ make
172
173 Then, we will have "neug.elf" under the "build" directory.
174
175
176 How to install
177 ==============
178
179 Olimex STM32-H103 board
180 -----------------------
181
182 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
183
184   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
185
186 Then, with another terminal, type following to write "neug.elf" to Flash ROM:
187
188   $ telnet localhost 4444
189   > reset halt
190   > flash write_image erase neug.elf
191   > reset
192   > exit
193   $ 
194
195
196 Flying Stone Tiny 01 and STM8S Discovery Kit
197 --------------------------------------------
198
199 If you are using Flying Stone Tiny 01, you need a SWD writer.
200
201 OpenOCD 0.6.1 or newer supports ST-Link/V2.  With that we can do:
202
203   $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x_stlink.cfg
204
205 Then, with another terminal, type following to write "neug.elf" to Flash ROM:
206
207   $ telnet localhost 4444
208   > reset halt
209   > flash write_image erase neug.elf
210   > reset
211   > exit
212   $ 
213
214 Note that OpenOCD (as of 0.7.0) doesn't support option bytes handling yet.
215
216 You can also use tool/stlinkv2.py in Gnuk.
217
218
219 Use of NeuG device
220 ==================
221
222 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
223 Before using /dev/ttyACM0, you need to configure its TTY discipline.
224
225   $ stty -F /dev/ttyACM0 -echo raw
226
227 Then, you can use output of /dev/ttyACM0.
228
229 When you want to get raw output (not conditioned), you can configure:
230
231   $ stty -F /dev/ttyACM0 parenb parodd
232
233 for raw data after filter.  For direct raw data of ADC samples,
234 configure:
235
236   $ stty -F /dev/ttyACM0 parenb -parodd
237
238 And you can get conditioned output by configuring:
239
240   $ stty -F /dev/ttyACM0 -parenb
241
242
243 Structure of NeuG
244 =================
245
246 Here is a figure of the circuit.
247
248                                          Noise sources
249
250                               /|<---+--- [ Analog input Vref ]
251                 16           | |<-+-|--- [ Analog input Temperature Sensor ]
252              +---/-[ADC1] <==| |  | |
253              |               | |<-+ |
254       +-+    |                \|<---+
255       | |<---+                |
256  +----| |          MUX CTL >--+
257  |    | |<---+
258  |    +-+    |                /|
259  |           |  16           | |<------- [ Analog input 0 ] (pull up to Vdd)
260  |           +---/-[ADC2] <==| |
261  |                           | |<------- [ Analog input 1 ] (pull up to Vdd)
262  |                            \|
263  |                            |
264  |                 MUX CTL >--+
265  |
266  +------------------+         <============ (*1)
267                     |
268                     / 32
269                     |
270                     | Put 4 times to output 32-bit
271                     V
272             [ CRC-32 filter ]
273                     |
274                     |           Put 35 times to output 1120-bit
275                     +---------------------------------+         <====== (*2)
276                                                       |
277                                                       / 32
278                                                       |
279                                                       V
280                                               [ Entropy Buffer ]
281                                                       |          
282             +--------------+                          |
283             |              |                          |
284             | Conditioning |            1120          |
285             | Component    |<------------/------------+
286             |              |
287       +-----|  Hash_df     |
288       |     |    by        |
289       |     |  SHA-256     |
290       |     |              |  128
291       |     |              |<--/--+
292       |     +--------------+      |
293       |                           |
294       +---------------------------+
295       |
296       / 256
297       |
298       v
299  Random Number Output <========== (*3)
300
301
302
303 Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
304 parodd, and (*1) with parenb -parodd.
305
306 STM32F103 has two built-in A/D converters.  NeuG uses A/D converters'
307 outputs as entropy sources.  It is considered noise of quantization
308 error, plus noise from power supply, etc.
309
310 We chose four analog input sources of: built-in voltage reference,
311 temperature sensor and two analog inputs which are pull-up to Vdd.
312
313 By a single sampling of two channels, we get 32-bit (not all 32-bit is
314 valid, as a A/D converter resolution is 12-bit only).  We take four
315 sampling of combinations: (Vref, IN0), (Temp, IN1), (Vref, IN1), and
316 (Temp, IN0).  Those 32-bit * 4 is fed into CRC32 filter.
317
318 We use STM32F103's CRC32 calculation unit as a kind of filter.  We put
319 output of A/D converters into CRC32 calculation unit, four times, to
320 get 4-byte output.
321
322 Output of CRC32 filter is collected 35 times, and it becomes 1120-bit
323 (32 * 35).  This is the noise source bits.
324
325 We put this 1120-bit and half of previous output (128-bit) to
326 conditioning component.
327
328 Conditioning Component is implemented by Hash_df function which is
329 composed by SHA-256.  Since the noise source is not "white", signal is
330 whiten by this Conditioning Component.
331
332 My experience with STM32F103 and NeuG shows that noise source is
333 stable at least for a year.
334
335
336 Test results
337 ============
338
339 See files under the directory test-results, for test result of
340 "rngtest" in rng-tools, NIST STS 2.1.1, and Dieharder.
341
342 I collect 110 files of 125MB (= 13750MB), and use scripts to invoke
343 dieharder and rngtest.  Collecting 110 files, it took three days.
344
345 For NIST STS 2.1.1, I used only 10 files of size 125MB.
346
347
348 Git Repository
349 ==============
350
351 NeuG is available in the Gnuk repository at Gitorious.org:
352
353     http://gitorious.org/gnuk/neug
354
355 You can get it by:
356
357     $ git clone git://gitorious.org/gnuk/neug.git
358
359
360 I put Chopstx as a submodule of Git.  Please do this:
361
362   $ git submodule init
363   $ git submodule update
364
365
366
367 Information on the Web
368 ======================
369
370 Please use FST-01 Q&A Forum at: http://no-passwd.net/askbot/questions/
371
372
373
374 Your Contributions
375 ==================
376
377 FSIJ welcomes your contributions.  Please assign your copyright
378 to FSIJ (if possible).
379 --