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