doc/crypto/rand.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 rand - Psdeudo-random number generator
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/rand.h>
  10
  11  int  RAND_bytes(unsigned char *buf,int num);
  12  int  RAND_pseudo_bytes(unsigned char *buf,int num);
  13
  14  void RAND_seed(const void *buf,int num);
  15  void RAND_add(const void *buf,int num,int entropy);
  16  void RAND_screen(void);
  17
  18  int  RAND_load_file(const char *file,long max_bytes);
  19  int  RAND_write_file(const char *file);
  20  char *RAND_file_name(char *file,int num);
  21
  22  void RAND_set_rand_method(RAND_METHOD *meth);
  23  RAND_METHOD *RAND_get_rand_method(void);
  24  RAND_METHOD *RAND_SSLeay(void);
  25
  26  void RAND_cleanup(void);
  27
  28 =head1 DESCRIPTION
  29
  30 These functions implement a cryptographically secure pseudo-random
  31 number generator (PRNG). It is used by other library functions for
  32 example to generate random keys, and applications can use it when they
  33 need randomness.
  34
  35 A cryptographic PRNG must be seeded with unpredictable data such as
  36 mouse movements or keys pressed at random by the user. This is
  37 described in L<RAND_add(3)>. Its state can be saved in a seed file
  38 (see L<RAND_load_file(3)>) to avoid having to go through the seeding
  39 process whenever the application is started.
  40
  41 L<RAND_bytes(3)> describes how to obtain random data from the PRNG.
  42
  43 =head1 INTERNALS
  44
  45 The RAND_SSLeay() method implements a PRNG based on a cryptographic
  46 hash function.
  47
  48 The following description of its design is based on the SSLeay
  49 documentation:
  50
  51 First up I will state the things I believe I need for a good RNG.
  52
  53 =over 4
  54
  55 =item 1
  56
  57 A good hashing algorithm to mix things up and to convert the RNG 'state'
  58 to random numbers.
  59
  60 =item 2
  61
  62 An initial source of random 'state'.
  63
  64 =item 3
  65
  66 The state should be very large.  If the RNG is being used to generate
  67 4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum).
  68 If your RNG state only has 128 bits, you are obviously limiting the
  69 search space to 128 bits, not 2048.  I'm probably getting a little
  70 carried away on this last point but it does indicate that it may not be
  71 a bad idea to keep quite a lot of RNG state.  It should be easier to
  72 break a cipher than guess the RNG seed data.
  73
  74 =item 4
  75
  76 Any RNG seed data should influence all subsequent random numbers
  77 generated.  This implies that any random seed data entered will have
  78 an influence on all subsequent random numbers generated.
  79
  80 =item 5
  81
  82 When using data to seed the RNG state, the data used should not be
  83 extractable from the RNG state.  I believe this should be a
  84 requirement because one possible source of 'secret' semi random
  85 data would be a private key or a password.  This data must
  86 not be disclosed by either subsequent random numbers or a
  87 'core' dump left by a program crash.
  88
  89 =item 6
  90
  91 Given the same initial 'state', 2 systems should deviate in their RNG state
  92 (and hence the random numbers generated) over time if at all possible.
  93
  94 =item 7
  95
  96 Given the random number output stream, it should not be possible to determine
  97 the RNG state or the next random number.
  98
  99 =back
 100
 101 The algorithm is as follows.
 102
 103 There is global state made up of a 1023 byte buffer (the 'state'), a
 104 working hash function ('md') and a counter ('count').
 105
 106 Whenever seed data is added, it is inserted into the 'state' as
 107 follows.
 108
 109 The input is chopped up into units of 16 bytes (or less for
 110 the last block).  Each of these blocks is run through the hash
 111 function as follows:  The data passed to the hash function
 112 is the current 'md', the same number of bytes from the 'state'
 113 (the location determined by in incremented looping index) as
 114 the current 'block', the new key data 'block', and 'count'
 115 (which is incremented after each use).
 116 The result of this is kept in 'md' and also xored into the
 117 'state' at the same locations that were used as input into the
 118 hash function. I
 119 believe this system addresses points 1 (hash function; currently
 120 SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash
 121 function and xor).
 122
 123 When bytes are extracted from the RNG, the following process is used.
 124 For each group of 8 bytes (or less), we do the following,
 125
 126 Input into the hash function the top 8 bytes from 'md', the bytes that
 127 are to be overwritten by the random bytes, and bytes from the 'state'
 128 (incrementing looping index).  From this hash function output (which
 129 is kept in 'md'), the top (upto) 8 bytes are returned to the caller
 130 and the bottom (upto) 8 bytes are xored into the 'state'.
 131
 132 Finally, after we have finished 'num' random bytes for the caller,
 133 'count' (which is incremented) and the local and global 'md' are fed
 134 into the hash function and the results are kept in the global 'md'.
 135
 136 I believe the above addressed points 1 (use of SHA-1), 6 (by hashing
 137 into the 'state' the 'old' data from the caller that is about to be
 138 overwritten) and 7 (by not using the 8 bytes given to the caller to
 139 update the 'state', but they are used to update 'md').
 140
 141 So of the points raised, only 2 is not addressed (but see
 142 L<RAND_add()>).
 143
 144 =head1 SEE ALSO
 145
 146 BN_rand(3), RAND_add(3), RAND_load_file(3), RAND_bytes(3),
 147 RAND_set_rand_method(3), RAND_cleanup(3)
 148
 149 =cut