6279ebd6eb7ee05c45985296cef8396b0abc264e
[gnuk/neug.git] / README
1 NeuG - a random number generator implementation (for STM32F103)
2
3                                                            Version 0.03
4                                                              2012-10-19
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 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 after filter.  For direct 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                                          Noise sources
182
183                               /|<---+--- [ Analog input Vref ]
184                 16           | |<-+-|--- [ Analog input Temperature Sensor ]
185              +---/-[ADC1] <==| |  | |
186              |               | |<-+ |
187       +-+    |                \|<---+
188       | |<---+                |
189  +----| |          MUX CTL >--+
190  |    | |<---+
191  |    +-+    |                /|
192  |           |  16           | |<------- [ Analog input 0 ] (pull up to Vdd)
193  |           +---/-[ADC2] <==| |
194  |                           | |<------- [ Analog input 1 ] (pull up to Vdd)
195  |                            \|
196  |                            |
197  |                 MUX CTL >--+
198  |
199  +------------------+         <============ (*1)
200                     |
201                     / 32
202                     |
203                     | Put 4 times to output 32-bit
204                     V
205             [ CRC-32 filter ]
206                     |
207                     |           Put 35 times to output 1120-bit
208                     +---------------------------------+         <====== (*2)
209                                                       |
210                                                       / 32
211                                                       |
212                                               [ Entropy Buffer ]
213                                                       |          
214             +--------------+                          |
215             |              |                          |
216             | Conditioning |            1120          |
217             | Component    |<------------/------------+
218             |              |
219       +-----|  Hash_df     |
220       |     |    by        |
221       |     |  SHA-256     |
222       |     |              |
223       |     |              |  128
224       |     |              |<--/--+
225       |     +--------------+      |
226       |                           |
227       +---------------------------+
228       |
229       / 256
230       |
231       v
232  Random Number Output <========== (*3)
233
234
235
236 Specifying by "stty", you can get (*3) with -parenb, (*2) with parenb
237 parodd, and (*1) with parenb 0parodd.
238
239 STM32F103 has two built-in A/D converters.  NeuG uses A/D converters'
240 outputs as entropy sources.  It is considered noise of quantization
241 error, plus noise from power supply, etc.
242
243 We chose four analog input sources of: built-in voltage reference,
244 temperature sensor and two analog inputs which are pull-up to Vdd.
245
246 By a single sampling of two channel, we get 32-bit (not all 32-bit is
247 valid, as a A/D converter resolution is 12-bit only).  We take four
248 sampling of different combinations: (Vref, IN0), (Temp, IN1), (Vref,
249 IN1), and (Temp, IN0).  Those 32-bit * 4 is fed into CRC32 filter.
250
251 We use STM32F103's CRC32 calculation unit as a kind of filter.  We put
252 output of A/D converters into CRC32 calculation unit, four times, to
253 get 4-byte output.
254
255 Output of CRC32 filter is collected 35 times, and it becomes 1120-bit
256 (32 * 35).  This is the noise source bits.
257
258 We put this 1120-bit and half of previous output (128-bit) to
259 conditioning component.
260
261 Conditioning Component is implemented by Hash_df function which is
262 composed by SHA-256.  Since the noise source is not "white", signal is
263 whiten by this Conditioning Component.
264
265 My experience with STM32F103 and NeuG shows that noise source is
266 stable at least for a year.
267
268
269 Test results
270 ============
271
272 See files under the directory test-results, for test result of
273 "rngtest" in rng-tools, NIST STS 2.1.1, and Dieharder.
274
275 For Dieharder, I correct 13GiB (it took five days and six hours
276 and more), and use scripts to invoke dieharder.
277
278
279 Read-only Git Repository
280 ========================
281
282 You can browse at http://www.gniibe.org/gitweb?p=neug.git;a=summary
283
284 You can get it by:
285
286   $ git clone git://www.gniibe.org/neug.git/
287
288 or
289
290   $ git clone http://www.gniibe.org/git/neug.git/
291
292
293 I put ChibiOS/RT as a submodule of Git.  Please do this:
294
295   $ git submodule init
296   $ git submodule update
297
298
299
300 Information on the Web
301 ======================
302
303 Not yet.
304
305
306
307 Your Contributions
308 ==================
309
310 FSIJ welcomes your contributions.  Please assign your copyright
311 to FSIJ (if possible).
312 --