Gnuk->NeuG
[gnuk/neug.git] / README
1 NeuG - a random number generator implementation (for STM32F103)
2
3                                                            Version 0.03
4                                                              2012-09-27
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 something around 30 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 How to compile
98 ==============
99
100 You need GNU toolchain and newlib for 'arm-none-eabi' target.
101
102 See http://github.com/uwehermann/summon-arm-toolchain/ for preparation
103 of GNU Toolchain for 'arm-none-eabi' target.
104
105 Change directory to `src':
106
107   $ cd neug-VERSION/src
108
109 Then, run `configure':
110
111   $ ./configure
112
113 Type:
114
115   $ make
116
117 Then, we will have "neug.elf".
118
119
120 How to install
121 ==============
122
123 STBee Mini and STBee
124 --------------------
125
126 Reset the board with "USER" switch pushed.  Type following to write
127 to flash:
128
129   # cd ../tool
130   # ./dfuse.py ../src/neug.hex
131
132 Then, reset the board.
133
134
135 Olimex STM32-H103 board
136 -----------------------
137
138 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
139
140   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
141
142 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
143
144   $ telnet localhost 4444
145   > reset halt
146   > flash write_image erase neug.elf
147   > reset
148   > exit
149   $ 
150
151
152
153 Use of NeuG device
154 ==================
155
156 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
157 Before using /dev/ttyACM0, you need to configure its TTY discipline.
158
159   $ stty -F /dev/ttyACM0 -echo raw
160
161 Then, you can use output of /dev/ttyACM0.
162
163 When you want to get raw output (not conditioned), you can configure:
164
165   $ stty -F /dev/ttyACM0 parenb parodd
166
167 for raw data of LSBs.  For raw data of samples, configure:
168
169   $ stty -F /dev/ttyACM0 parenb -parodd
170
171 And you can get conditioned output by configuring:
172
173   $ stty -F /dev/ttyACM0 -parenb
174
175
176 Structure of the NeuG
177 =====================
178
179 Here is a figure of the circuit.
180
181
182            Physical-based RNG
183            
184             +--------------+              Noise sources 
185             |              |
186             | Conditioning |   1112 ||<-- LSB of result of [ IN10 ]
187             | Component    |<---/---||
188             |              |        ||<-- LSB of result of [ IN11 ]
189       +-----|  Hash_df     |
190       |     |    by        |
191       |     |  SHA-256     |
192       |     |              |
193       |     |              |   128
194       |     |              |<---/---+
195       |     +--------------+        |
196       |                             |
197       +-----------------------------+
198       |
199       / 256
200       |
201       v
202  Random Number Output
203
204
205 STM32F103 has two built-in A/D converters of 12-bit resolution.  NeuG
206 uses LSBs of A/D converters' outputs as entropy sources.  It is
207 considered noise of quantization error, plus noise from power supply,
208 etc.
209
210 We chose analog inputs of IN10 and IN11, which is not connected to
211 external pin (for the version of 36-pin or 48-pin STM32F103).  The
212 input is configured as digital output 50MHz to get maximum noise of
213 environment.
214
215 By 556 samplings of two channels, we can get 1112-bit, as we can get
216 two bits (LSB of IN10 and LSB of IN11) from one sampling.  We put this
217 1112-bit and half of previous output to conditioning component.
218
219 Conditioning component is implemented by Hash_df function by SHA-256.
220 Since the noise source is not "white", signal is whiten by this
221 Conditioning component.
222
223 Experiments show that raw noise source of LSBs has more than 6.0
224 bit/byte entropy when it is no computation but just to take samples.
225 The entropy varies among different boards.  It seems that a board with
226 good power supply and capacitor has smaller entropy (6.2 or so), and
227 the one with poor power supply and capacitor has bigger entropy (7.3
228 or so).  That is considered noise of quantization error.
229
230 When there is some activities of MCU, it's more than 7.0 bit/byte
231 entropy for a board even with good power supply and capacitor.
232
233 My experience with STM32F103 and NeuG shows that noise source is
234 stable at least for a year.
235
236
237 Test results
238 ============
239
240 See files under the directory test-results, for test result of
241 "rngtest" in rng-tools, NIST STS 2.1.1, and Dieharder.
242
243 For Dieharder, I correct 13GiB (it took five days and six hours
244 and more), and use scripts to invoke dieharder.
245
246
247 Read-only Git Repository
248 ========================
249
250 You can browse at http://www.gniibe.org/gitweb?p=neug.git;a=summary
251
252 You can get it by:
253
254   $ git clone git://www.gniibe.org/neug.git/
255
256 or
257
258   $ git clone http://www.gniibe.org/git/neug.git/
259
260
261 I put ChibiOS/RT as a submodule of Git.  Please do this:
262
263   $ git submodule init
264   $ git submodule update
265
266
267
268 Information on the Web
269 ======================
270
271 Not yet.
272
273
274 Known Problem(s)
275 ================
276
277 On STBee (high-density device of STM32), sometimes, I observed stall
278 of generation of random number, after two hours, two hours and half,
279 etc.
280
281 Identified somehow.  When it stalls, status is like this (by OpenOCD, GDB):
282
283         adcp->state = ADC_ACTIVE
284         main thread: wait on condition variable at neug_get
285         rng thread: holding rb->m, event wait at rng_gen for ADC_DATA_AVAILABLE
286         idle thread: running
287         LED thread: event wait
288
289 Kicking DMA controller again (note: ADC is continuous mode, no need to
290 kick), by doing following:
291
292   (gdb) set ADCD1.dmastp->channel->CCR = 0
293   (gdb) set ADCD1.dmastp->channel->CNDTR = 8
294   (gdb) set ADCD1.dmastp->channel->CCR = 0x258f
295   (gdb) x/x 0x40020000          # DMA interrupt status register (DMA_ISR)
296   0x40020000:   0x00000007
297
298 Then, it goes again.
299
300 Lost DMA finish interrupt?
301
302
303 Your Contributions
304 ==================
305
306 FSIJ welcomes your contributions.  Please assign your copyright
307 to FSIJ (if possible).
308 --