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