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