third_party/npapi/npspy/extern/nspr/prrng.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /*
   3  * The contents of this file are subject to the Mozilla Public
   4  * License Version 1.1 (the "License"); you may not use this file
   5  * except in compliance with the License. You may obtain a copy of
   6  * the License at http://www.mozilla.org/MPL/
   7  *
   8  * Software distributed under the License is distributed on an "AS
   9  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  10  * implied. See the License for the specific language governing
  11  * rights and limitations under the License.
  12  *
  13  * The Original Code is the Netscape Portable Runtime (NSPR).
  14  *
  15  * The Initial Developer of the Original Code is Netscape
  16  * Communications Corporation.  Portions created by Netscape are
  17  * Copyright (C) 1999-2000 Netscape Communications Corporation.  All
  18  * Rights Reserved.
  19  *
  20  * Contributor(s):
  21  *
  22  * Alternatively, the contents of this file may be used under the
  23  * terms of the GNU General Public License Version 2 or later (the
  24  * "GPL"), in which case the provisions of the GPL are applicable
  25  * instead of those above.  If you wish to allow use of your
  26  * version of this file only under the terms of the GPL and not to
  27  * allow others to use your version of this file under the MPL,
  28  * indicate your decision by deleting the provisions above and
  29  * replace them with the notice and other provisions required by
  30  * the GPL.  If you do not delete the provisions above, a recipient
  31  * may use your version of this file under either the MPL or the
  32  * GPL.
  33  */
  34
  35
  36 /*
  37 ** prrng.h -- NSPR Random Number Generator
  38 **
  39 **
  40 ** lth. 29-Oct-1999.
  41 */
  42
  43 #ifndef prrng_h___
  44 #define prrng_h___
  45
  46 #include "prtypes.h"
  47
  48 PR_BEGIN_EXTERN_C
  49
  50 /*
  51 ** PR_GetRandomNoise() -- Get random noise from the host platform
  52 **
  53 ** Description:
  54 ** PR_GetRandomNoise() provides, depending on platform, a random value.
  55 ** The length of the random value is dependent on platform and the
  56 ** platform's ability to provide a random value at that moment.
  57 **
  58 ** The intent of PR_GetRandomNoise() is to provide a "seed" value for a
  59 ** another random number generator that may be suitable for
  60 ** cryptographic operations. This implies that the random value
  61 ** provided may not be, by itself, cryptographically secure. The value
  62 ** generated by PR_GetRandomNoise() is at best, extremely difficult to
  63 ** predict and is as non-deterministic as the underlying platfrom can
  64 ** provide.
  65 **
  66 ** Inputs:
  67 **   buf -- pointer to a caller supplied buffer to contain the
  68 **          generated random number. buf must be at least as large as
  69 **          is specified in the 'size' argument.
  70 **
  71 **   size -- the requested size of the generated random number
  72 **
  73 ** Outputs:
  74 **   a random number provided in 'buf'.
  75 **
  76 ** Returns:
  77 **   PRSize value equal to the size of the random number actually
  78 **   generated, or zero. The generated size may be less than the size
  79 **   requested. A return value of zero means that PR_GetRandomNoise() is
  80 **   not implemented on this platform, or there is no available noise
  81 **   available to be returned at the time of the call.
  82 **
  83 ** Restrictions:
  84 **   Calls to PR_GetRandomNoise() may use a lot of CPU on some platforms.
  85 **   Some platforms may block for up to a few seconds while they
  86 **   accumulate some noise. Busy machines generate lots of noise, but
  87 **   care is advised when using PR_GetRandomNoise() frequently in your
  88 **   application.
  89 **
  90 ** History:
  91 **   Parts of the model dependent implementation for PR_GetRandomNoise()
  92 **   were taken in whole or part from code previously in Netscape's NSS
  93 **   component.
  94 **
  95 */
  96 NSPR_API(PRSize) PR_GetRandomNoise(
  97     void    *buf,
  98     PRSize  size
  99 );
 100
 101 PR_END_EXTERN_C
 102
 103 #endif /* prrng_h___ */
 104 /* end prrng.h */