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