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