annotate notes/tech0001.txt @ 380:d5faf4814ddb libtomcrypt-orig libtomcrypt-1.16

Update to LibTomCrypt 1.16
author Matt Johnston <matt@ucc.asn.au>
date Thu, 11 Jan 2007 02:22:00 +0000
parents 59400faa4b44
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
280
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1 Tech Note 0001
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2 How to Gather Entropy on Embedded Systems
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
3 Tom St Denis
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
4
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
5 Introduction
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
6 ------------
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
7
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
8 This tech note explains a relatively simple way to gather entropy for a PRNG (Yarrow in this case) in embedded systems
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
9 where there are few sources of entropy or physical sources.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
10
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
11 When trying to setup a secure random number generator a fresh source of random data (entropy) is required to ensure the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
12 deterministic state of the PRNG is not known or predetermined with respect to an attacker.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
13
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
14 At the very least the system requires one timer and one source of un-timed interrupts. by "un-timed" I mean interrupts
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
15 that do not occur at regular intervals [e.g. joypad/keypad input, network packets, etc...].
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
16
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
17 First we shall begin by taking an overview of how the Yarrow PRNG works within libtomcrypt. At the heart of all
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
18 PRNGs is the "prng_state" data type. This is a union of structures that hold the PRNG state for the various prngs. The
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
19 first thing we require is a state...
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
20
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
21 prng_state myPrng;
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
22
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
23 Next we must initialize the state once to get the ball rolling
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
24
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
25 if (yarrow_start(&myPrng) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
26 // error should never happen!
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
27 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
28
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
29 At this point the PRNG is ready to accept fresh entropy which is added with
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
30
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
31 int yarrow_add_entropy(const unsigned char *buf, unsigned long len, prng_state *prng)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
32
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
33 This function is **NOT** thread safe which will come under consideration later. To add entropy to our PRNG we must
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
34 call this function with fresh data as its sampled. Lets say we have a timer counter called "uTimer" which is a 32-bit
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
35 long and say a 32-bit joyPad state called "uPad". An example interrupt handler would look like
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
36
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
37 void joypad_interrupt(...) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
38 unsigned char buf[8];
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
39
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
40 STORE32L(uTimer, buf);
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
41 STORE32L(uPad, buf+4)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
42 if (yarrow_add_entropy(buf, 8, &myPrng) != CRYPT_OK) {
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
43 // this should never occur either unless you didn't call yarrow_start
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
44 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
45
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
46 // handle interrupt
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
47 }
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
48
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
49 In this snippet the timer count and state of the joypad are added together into the entropy pool. The timer is important
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
50 because with respect to the joypad it is a good source of entropy (on its own its not). For example, the probability of
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
51 the user pushing the up arrow is fairly high, but at a specific time is not.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
52
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
53 This method doesn't gather alot of entropy and has to be used to for quite a while. One way to speed it up is to tap
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
54 multiple sources. If you have a network adapter and other sources of events (keyboard, mouse, etc...) trapping their
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
55 data is ideal as well. Its important to gather the timer along with the event data.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
56
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
57 As mentioned the "yarrow_add_entropy()" function is not thread safe. If your system allows interrupt handlers to be
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
58 interrupted themselves then you could have trouble. One simple way is to detect when an interrupt is in progress and
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
59 simply not add entropy during the call (jump over the yarrow_add_entropy() call)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
60
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
61 Once you feel that there has been enough entropy added to the pool then within a single thread you can call
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
62
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
63 int yarrow_ready(prng_state *prng)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
64
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
65 Now the PRNG is ready to read via the
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
66
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
67 unsigned long yarrow_read(unsigned char *buf, unsigned long len, prng_state *prng)
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
68
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
69 It is a very good idea that once you call the yarrow_ready() function that you stop harvesting entropy in your interrupt
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
70 functions. This will free up alot of CPU time. Also one more final note. The yarrow_read() function is not thread
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
71 safe either. This means if you have multiple threads or processes that read from it you will have to add your own semaphores
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
72 around calls to it.
59400faa4b44 Re-import libtomcrypt 1.05 for cleaner propagating.
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
73