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