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