1  #+TITLE: Story 17 - PRNGs
  2  #+OPTIONS: author:nil date:nil
  3  
  4  Up until now, Pseudo-Random Number Generation has been completely ignored.  In
  5  effect, it's been treated as a function that's entirely internal to plugins.
  6  However, such randomness is important to applications as well, and they might
  7  also want to affect what randomness sources are used for things like key
  8  generation.
  9  
 10  * Information sources
 11  
 12  A lot of what is written here is inspired from [[https://csrc.nist.gov/projects/random-bit-generation][NIST's Random Bit Generation project]].
 13  
 14  * What is a reasonable core interface for applications?
 15  
 16  In [[https://csrc.nist.gov/pubs/sp/800/90/c/3pd][SP 800-90C]] section 2 (General Information), Figure 3 (General Function
 17  Calls) show us three classes of functions:
 18  
 19  - DRBG Functions
 20  - Entropy Source
 21  - RBG3 Construction
 22  
 23  The first two are the focus of this story.  The RBG3 Construction may be
 24  interesting for a future story.
 25  
 26  ** DRBG Functions
 27  
 28  [[https://csrc.nist.gov/pubs/sp/800/90/c/3pd][SP 800-90C]] describes an interface called DRBG Functions in section 2.8.1.
 29  Let's explore them:
 30  
 31  - Instantiate_function (section 2.8.1.1) ::
 32  
 33    In Le'Sec Crypto terms, this could be a combination of allocating the RBG
 34    (~LSC_new_rbg~) and calling the common Start function (~LSC_start_rbg~).
 35  
 36    The  *Instantiate_function* input parameters
 37    /requested_instantiation_security_strength/ and
 38    /prediction_resistance_flag/, if relevant, should be settable parameters, to
 39    be set before the Start function is called.
 40  
 41    The Start function must be able to take the *Instantiate_function* input
 42    parameters /personalization_string/) as function argument.
 43  
 44  - Generate_function (section 2.8.1.2) ::
 45  
 46    In Le'Sec Crypto terms, this could be calling the common Extract function
 47    (~LSC_extract_rbg_output~).
 48  
 49    It must be able to take the parameters /requested_number_of_bits/,
 50    /requested_security_strength/, /prediction_resistance_request/ and
 51    /additional_input/ as extra arguments.
 52  
 53  - Reseed_function (section 2.8.1.3) ::
 54  
 55    In Le'Sec Crypto terms, this would be a special option function reserved for
 56    DRBG implementaions (~LSC_reseed_rbg~).
 57  
 58    It must be able to take the parameter /additional_input/ as argument.
 59  
 60  - Get_randomness-source_input (section 2.8.1.4) :: 
 61  
 62    This one seems to be intended for internal purposes (called by
 63    *Instantiate_function* and *Reseed_function*), so it's currently
 64    uninteresting for the purpose of the Le'Sec Crypto API.
 65  
 66  In addition, an implementation may choose to make provide some of the
 67  instantiation input parameters as gettable parameters:
 68  
 69  - /instantiation_security_strength/
 70  - /prediction_resistance_flag/
 71  
 72  *** Entropy sources for RBGs
 73  
 74  An RBG implementation may also choose to allow the caller to specify an
 75  Entropy Source.  This could be done as a settable parameter that passes an
 76  entropy implementation, or the name of an entropy implementation.
 77  
 78  Exactly how this is will be done is a matter of experimentation for the time
 79  being.  A future story may tell what the experimentation resulted in.
 80  
 81  ** Entropy Source
 82  
 83  [[https://csrc.nist.gov/pubs/sp/800/90/c/3pd][SP 800-90C]] describes an interface for Entropy Source in section 2.8.2.
 84  Let's explore them:
 85  
 86  - GetEntropy ::
 87  
 88    This function extracts an entropy bitstring from one validated entropy
 89    source.
 90  
 91    In Le'Sec Crypto terms, this could be calling the common Extract function
 92    (~LSC_extract_entropy_output~).  This function would take the input
 93    parameter /bits_of_entropy/ as an extra argument for minimum extracted
 94    output.
 95  
 96  - Get_ES_Bitstring ::
 97  
 98    This function extracts a combined entropy bitstring from multiple validated
 99    entropy sources, implemented as multiple *GetEntropy* calls.
100  
101    In Le'Sec Crypto terms, this is implemented using the exact same interface
102    as *GetEntropy*.
103  
104  For Le'Sec Crypto purposes, entropy source would be instantiated the exact
105  same way as RBGs (as described in [[*DRBG Functions][DRBG Functions]] above), but without
106  instantiation parameters.  The DRBG Function *Get_randomness-source_input* is
107  in fact *GetEntropy* / *Get_ES_Bitstring*, which more or less brings the API
108  for Entropy Sources to be implemented almost exactly like the API for RBGs.
109  
110  Furthermore, *Get_ES_Bitstring* implies that an Entropy Source could have
111  other underlying Entropy Sources.  It could be feasible to have functionality
112  to add such underlying Entropy Sources, in the same way as described for RBGs
113  in [[*Entropy sources for RBGs][Entropy sources for RBGs]] above.
114  
115  * Nomenclature
116  
117  Because both =rbg= and =entropy= are nouns with no corresponding verb or
118  adjective, they should be used as they are in all types and functions, no
119  inflections.
120  
121  * In summary
122  
123  While much of the deliberations above are based on SP 800-90, the interface
124  that's formulated here doesn't enforce DRBG according to spec, but rather
125  allows it.  This leaves it to the implementors to decide how they want to do
126  things under the hood.
127  
128  ** Two new operator types
129  
130  - =OPERATOR::rbg::=
131  - =OPERATOR::entropy::=
132  
133  ** Both operator types use common function names for most things
134  
135  - ~LSC_new_{rbg,entropy}~
136  - ~LSC_start_{rbg,entropy}~
137  - ~LSC_extract_{rbg,entropy}_output~
138  - ~LSC_stop_{rbg,entropy}~
139  - ~LSC_free_{rbg,entropy}~
140  
141  And of course, the usual parameter getters and setters:
142  
143  - ~LSC_get_settable_{rbg,entropy}_param_desc~
144  - ~LSC_set_{rbg,entropy}_param~
145  - ~LSC_get_gettable_{rbg,entropy}_param_desc~
146  - ~LSC_get_{rbg,entropy}_param~
147  
148  *** For RBGs (not Entropy Sources)
149  
150  - ~LSC_set_rbg_entropy_source~ ::
151  
152    This allows setting a single entropy source.
153  
154  *** For Entropy Sources
155  
156  - ~LSC_add_entropy_source~ ::
157  
158    This allows adding an entropy source.  This should only be possible with
159    Entropy Sources that support the *Get_ES_Bitstring* functionality, and
160    actually serves as an indicator that it does.