doc/crypto/RAND_add.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 RAND_add, RAND_seed, RAND_status, RAND_event - add
   6 entropy to the PRNG
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/rand.h>
  11
  12  void RAND_seed(const void *buf, int num);
  13
  14  void RAND_add(const void *buf, int num, double entropy);
  15
  16  int  RAND_status(void);
  17
  18  int  RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
  19
  20 =head1 DESCRIPTION
  21
  22 RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus,
  23 if the data at B<buf> are unpredictable to an adversary, this
  24 increases the uncertainty about the state and makes the PRNG output
  25 less predictable. Suitable input comes from user interaction (random
  26 key presses, mouse movements) and certain hardware events. The
  27 B<entropy> argument is (the lower bound of) an estimate of how much
  28 randomness is contained in B<buf>, measured in bytes. Details about
  29 sources of randomness and how to estimate their entropy can be found
  30 in the literature, e.g. RFC 1750.
  31
  32 RAND_add() may be called with sensitive data such as user entered
  33 passwords. The seed values cannot be recovered from the PRNG output.
  34
  35 OpenSSL makes sure that the PRNG state is unique for each thread. On
  36 systems that provide C</dev/urandom>, the randomness device is used
  37 to seed the PRNG transparently. However, on all other systems, the
  38 application is responsible for seeding the PRNG by calling RAND_add(),
  39 L<RAND_egd(3)>
  40 or L<RAND_load_file(3)>.
  41
  42 RAND_seed() is equivalent to RAND_add() when B<num == entropy>.
  43
  44 RAND_event() collects the entropy from Windows events such as mouse
  45 movements and other user interaction. It should be called with the
  46 B<iMsg>, B<wParam> and B<lParam> arguments of I<all> messages sent to
  47 the window procedure. It will estimate the entropy contained in the
  48 event message (if any), and add it to the PRNG. The program can then
  49 process the messages as usual.
  50
  51 =head1 RETURN VALUES
  52
  53 RAND_status() and RAND_event() return 1 if the PRNG has been seeded
  54 with enough data, 0 otherwise.
  55
  56 The other functions do not return values.
  57
  58 =head1 SEE ALSO
  59
  60 L<rand(3)>, L<RAND_egd(3)>,
  61 L<RAND_load_file(3)>, L<RAND_cleanup(3)>
  62
  63 =head1 COPYRIGHT
  64
  65 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
  66
  67 Licensed under the OpenSSL license (the "License").  You may not use
  68 this file except in compliance with the License.  You can obtain a copy
  69 in the file LICENSE in the source distribution or at
  70 L<https://www.openssl.org/source/license.html>.
  71
  72 =cut