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 the last
 110 block).  Each of these blocks is run through the hash function.  The
 111 data passed to the hash function is the current 'md', the same number
 112 of bytes from the 'state' (the location determined by in incremented
 113 looping index) as the current 'block' and the new key data 'block'.
 114 The result of this is kept in 'md' and also xored into the 'state' at
 115 the same locations that were used as input into the hash function.  I
 116 believe this system addresses points 1 (hash function; currently
 117 SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash
 118 function and xor).
 119
 120 When bytes are extracted from the RNG, the following process is used.
 121 For each group of 8 bytes (or less), we do the following,
 122
 123 Input into the hash function, the top 8 bytes from 'md', the byte that
 124 are to be overwritten by the random bytes and bytes from the 'state'
 125 (incrementing looping index).  From this hash function output (which
 126 is kept in 'md'), the top (upto) 8 bytes are returned to the caller
 127 and the bottom (upto) 8 bytes are xored into the 'state'.
 128
 129 Finally, after we have finished 'generation' random bytes for the
 130 called, 'count' (which is incremented) and 'md' are fed into the hash
 131 function and the results are kept in 'md'.  I believe the above
 132 addressed points 1 (use of SHA-1), 6 (by hashing into the 'state' the
 133 'old' data from the caller that is about to be overwritten) and 7 (by
 134 not using the 8 bytes given to the caller to update the 'state', but
 135 they are used to update 'md').
 136
 137 So of the points raised, only 2 is not addressed (but see
 138 L<RAND_add()>).
 139
 140 =head1 SEE ALSO
 141
 142 BN_rand(3), RAND_add(3), RAND_load_file(3), RAND_bytes(3),
 143 RAND_set_rand_method(3), RAND_cleanup(3)
 144
 145 =cut