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