Version 0.02
[gnuk/neug.git] / README
1 NeuG - a random number generator implementation (for STM32F103)
2
3                                                            Version 0.02
4                                                              2012-08-30
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
25 Release notes
26 =============
27
28 This is the third release of NeuG, which is still experimental.  You
29 can enjoy NeuG device, but I'm not sure how it is good yet.  Note that
30 you need the snapshot of ChibiOS/RT (from trunk).  This means that it
31 is covered by GNU GPL.  No "linking exception" option is available for
32 the snapshot.
33
34
35 FAQ
36 ===
37
38 Q0: How NeuG device is good?
39 A0: I believe it's good enough if we compare to other hardware RNGs.
40     If its usage is as an entropy source for RNG-tools, or use for
41     computer simulations, I think that it's good enough.  I evaluated
42     it with rngtest of RNG-tools, NIST STS test suite and Dieharder.
43     See the directory neug/test-results/.
44     For important cryptographic usage, such as generating keys or use
45     for ECC, I think that we need more evaluations under severe
46     condition (e.g., lower ALPHA (say, 0.001) in NIST STS test suite
47     and more number of streams (say, 10000)).
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.  It's not implemented yet, and I don't have an
59     good idea how to implement such a feature with limited resource
60     of STM32F103.  Please let me know your idea.
61
62
63 Targets
64 =======
65
66 FST-01, STBee Mini, Olimex STM32-H103, CQ-STARM, and STBee are
67 supported.
68
69
70 Souce code
71 ==========
72
73 NeuG source code is under src/ directory.
74
75
76 License
77 =======
78
79 It is distributed under GNU General Public Licence version 3 or later
80 (GPLv3+).  Please see src/COPYING.
81
82
83 External source code
84 ====================
85
86 To build NeuG device, we need external source code.
87
88 * chibios/  -- ChibiOS/RT 2.3.x snapshot
89
90   Please get it from http://chibios.sourceforge.net/
91   We use ChibiOS/RT as the kernel for NeuG device.
92
93
94 How to compile
95 ==============
96
97 You need GNU toolchain and newlib for 'arm-none-eabi' target.
98
99 See http://github.com/uwehermann/summon-arm-toolchain/ for preparation
100 of GNU Toolchain for 'arm-none-eabi' target.
101
102 Change directory to `src':
103
104   $ cd neug-VERSION/src
105
106 Then, run `configure':
107
108   $ ./configure
109
110 Type:
111
112   $ make
113
114 Then, we will have "neug.elf".
115
116
117 How to install
118 ==============
119
120 STBee Mini and STBee
121 --------------------
122
123 Reset the board with "USER" switch pushed.  Type following to write
124 to flash:
125
126   # cd ../tool
127   # ./dfuse.py ../src/neug.hex
128
129 Then, reset the board.
130
131
132 Olimex STM32-H103 board
133 -----------------------
134
135 If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD:
136
137   $ openocd -f interface/olimex-jtag-tiny.cfg -f board/olimex_stm32_h103.cfg
138
139 Then, with another terminal, type following to write "gnuk.elf" to Flash ROM:
140
141   $ telnet localhost 4444
142   > reset halt
143   > flash write_image erase neug.elf
144   > reset
145   > exit
146   $ 
147
148
149
150 Use of NeuG device
151 ==================
152
153 It is USB CDC ACM device.  On GNU/Linux, it can be /dev/ttyACM0 or like.
154 Before using /dev/ttyACM0, you need to configure its TTY discipline.
155
156   $ stty -F /dev/ttyACM0 -echo raw
157
158 Then, you can use output of /dev/ttyACM0.
159
160
161
162 Structure of the NeuG
163 =====================
164
165 Here is a figure of the circuit.
166
167
168              Entropy Pool (64-byte)
169             +----------------+
170             |                |
171             | 16-word        |        8  ||<-- [ Vref ]
172       +---- | registers      |    |<--/--||
173       |     |   in           | 32 |      ||<-- [ Temperature Sensor ]
174       |     | WELL512a       |<-/-|
175       |     |  structure     |    |<----/------ SysTick
176       |     +----------------+          1
177       |     Physical-based RNG
178       |
179       / 32
180       |
181       v
182  Random Number Output
183
184
185 STM32F103 has built-in Vref (voltage reference) and Temperature Sensor
186 which are connected to A/D converter of 12-bit resolution.  NeuG uses
187 LSBs of A/D converter's outputs as entropy sources.
188
189 By four samplings of two channels, we can get 8-bit, as we can get two
190 bits (LSB of Vref and LSB of Temperature Sensor) from one sampling.
191 We put this 8-bit noise and SysTick to entropy pool.  Entropy pool
192 consist of 16-word buffer, which has WELL 512a structure.
193
194 Since the noise source is not "white", signal is whiten by this WELL
195 512a structure.  An experiment shows that raw noise source of LSBs has
196 more than 6 bit/byte entropy.  So, we put 6-byte (36-bit) to get
197 4-byte (32-bit) output.
198
199 I don't know how stable the noise source is.  My experience with
200 STM32F103 and NeuG shows that it's stable at least for a year.
201
202 For WELL Random Number Generator, please visit:
203
204    http://www.iro.umontreal.ca/~panneton/WELLRNG.html
205
206
207 Test results
208 ============
209
210 See files under the directory test-results, for test result of
211 "rngtest" in rng-tools, NIST STS 2.1.1, and Dieharder.
212
213 For Dieharder, I correct 13GiB (it took five days and six hours
214 and more), and use scripts to invoke dieharder.
215
216
217 Read-only Git Repository
218 ========================
219
220 You can browse at http://www.gniibe.org/gitweb?p=neug.git;a=summary
221
222 You can get it by:
223
224   $ git clone git://www.gniibe.org/neug.git/
225
226 or
227
228   $ git clone http://www.gniibe.org/git/neug.git/
229
230
231 I put ChibiOS/RT as a submodule of Git.  Please do this:
232
233   $ git submodule init
234   $ git submodule update
235
236
237
238 Information on the Web
239 ======================
240
241 Not yet.
242
243
244 Known Problem(s)
245 ================
246
247 On STBee (high-density device of STM32), sometimes, I observed stall
248 of generation of random number, after two hours, two hours and half,
249 etc.
250
251 Identified somehow.  When it stalls, status is like this (by OpenOCD, GDB):
252
253         adcp->state = ADC_ACTIVE
254         main thread: wait on condition variable at neug_get
255         rng thread: holding rb->m, event wait at rng_gen for ADC_DATA_AVAILABLE
256         idle thread: running
257         LED thread: event wait
258
259 Kicking DMA controller again (note: ADC is continuous mode, no need to
260 kick), by doing following:
261
262   (gdb) set ADCD1.dmastp->channel->CCR = 0
263   (gdb) set ADCD1.dmastp->channel->CNDTR = 8
264   (gdb) set ADCD1.dmastp->channel->CCR = 0x258f
265   (gdb) x/x 0x40020000          # DMA interrupt status register (DMA_ISR)
266   0x40020000:   0x00000007
267
268 Then, it goes again.
269
270 Lost DMA finish interrupt?
271
272
273 Your Contributions
274 ==================
275
276 FSIJ welcomes your contributions.  Please assign your copyright
277 to FSIJ (if possible).
278 --