src/crypto/drbg.c

   1 /*
   2  * Copyright (C) 2012 Michael Brown <mbrown@fensystems.co.uk>.
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License as
   6  * published by the Free Software Foundation; either version 2 of the
   7  * License, or any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  17  * 02110-1301, USA.
  18  *
  19  * You can also choose to distribute this program under the terms of
  20  * the Unmodified Binary Distribution Licence (as given in the file
  21  * COPYING.UBDL), provided that you have satisfied its requirements.
  22  */
  23
  24 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
  25
  26 /** @file
  27  *
  28  * DRBG mechanism
  29  *
  30  * This mechanism is designed to comply with ANS X9.82 Part 3-2007
  31  * Section 9.  This standard is not freely available, but most of the
  32  * text appears to be shared with NIST SP 800-90, which can be
  33  * downloaded from
  34  *
  35  *     http://csrc.nist.gov/publications/nistpubs/800-90/SP800-90revised_March2007.pdf
  36  *
  37  * Where possible, references are given to both documents.  In the
  38  * case of any disagreement, ANS X9.82 takes priority over NIST SP
  39  * 800-90.  (In particular, note that some algorithms that are
  40  * Approved by NIST SP 800-90 are not Approved by ANS X9.82.)
  41  */
  42
  43 #include <stdint.h>
  44 #include <string.h>
  45 #include <errno.h>
  46 #include <assert.h>
  47 #include <ipxe/entropy.h>
  48 #include <ipxe/drbg.h>
  49
  50 /**
  51  * Instantiate DRBG
  52  *
  53  * @v state             Algorithm state to be initialised
  54  * @v personal          Personalisation string
  55  * @v personal_len      Length of personalisation string
  56  * @ret rc              Return status code
  57  *
  58  * This is the Instantiate_function defined in ANS X9.82 Part 3-2007
  59  * Section 9.2 (NIST SP 800-90 Section 9.1).
  60  *
  61  * Only a single security strength is supported, and prediction
  62  * resistance is always enabled.  The nonce is accounted for by
  63  * increasing the entropy input, as per ANS X9.82 Part 3-2007 Section
  64  * 8.4.2 (NIST SP 800-90 Section 8.6.7).
  65  */
  66 int drbg_instantiate ( struct drbg_state *state, const void *personal,
  67                        size_t personal_len ) {
  68         unsigned int entropy_bits = ( ( 3 * DRBG_SECURITY_STRENGTH + 1 ) / 2 );
  69         size_t min_len = DRBG_MIN_ENTROPY_LEN_BYTES;
  70         size_t max_len = DRBG_MAX_ENTROPY_LEN_BYTES;
  71         uint8_t data[max_len];
  72         int len;
  73         int rc;
  74
  75         DBGC ( state, "DRBG %p instantiate\n", state );
  76
  77         /* Sanity checks */
  78         assert ( state != NULL );
  79
  80         /* 1.  If requested_instantiation_security_strength >
  81          *     highest_supported_security_strength, then return an
  82          *     ERROR_FLAG
  83          */
  84         if ( DRBG_SECURITY_STRENGTH > DRBG_MAX_SECURITY_STRENGTH ) {
  85                 DBGC ( state, "DRBG %p cannot support security strength %d\n",
  86                        state, DRBG_SECURITY_STRENGTH );
  87                 return -ENOTSUP;
  88         }
  89
  90         /* 2.  If prediction_resistance_flag is set, and prediction
  91          *     resistance is not supported, then return an ERROR_FLAG
  92          *
  93          * (Nothing to do since prediction resistance is always
  94          * supported.)
  95          */
  96
  97         /* 3.  If the length of the personalization_string >
  98          *     max_personalization_string_length, return an ERROR_FLAG
  99          */
 100         if ( personal_len > DRBG_MAX_PERSONAL_LEN_BYTES ) {
 101                 DBGC ( state, "DRBG %p personalisation string too long (%zd "
 102                        "bytes)\n", state, personal_len );
 103                 return -ERANGE;
 104         }
 105
 106         /* 4.  Set security_strength to the nearest security strength
 107          *     greater than or equal to
 108          *     requested_instantiation_security_strength.
 109          *
 110          * (Nothing to do since we support only a single security
 111          * strength.)
 112          */
 113
 114         /* 5.  Using the security_strength, select appropriate DRBG
 115          *     mechanism parameters.
 116          *
 117          * (Nothing to do since we support only a single security
 118          * strength.)
 119          */
 120
 121         /* 6.  ( status, entropy_input ) = Get_entropy_input (
 122          *     security_strength, min_length, max_length,
 123          *     prediction_resistance_request )
 124          * 7.  If an ERROR is returned in step 6, return a
 125          *     CATASTROPHIC_ERROR_FLAG.
 126          * 8.  Obtain a nonce.
 127          */
 128         len = get_entropy_input ( entropy_bits, data, min_len,
 129                                   sizeof ( data ) );
 130         if ( len < 0 ) {
 131                 rc = len;
 132                 DBGC ( state, "DRBG %p could not get entropy input: %s\n",
 133                        state, strerror ( rc ) );
 134                 return rc;
 135         }
 136         assert ( len >= ( int ) min_len );
 137         assert ( len <= ( int ) sizeof ( data ) );
 138
 139         /* 9.  initial_working_state = Instantiate_algorithm (
 140          *     entropy_input, nonce, personalization_string ).
 141          */
 142         drbg_instantiate_algorithm ( state, data, len, personal, personal_len );
 143
 144         /* 10.  Get a state_handle for a currently empty state.  If an
 145          *      empty internal state cannot be found, return an
 146          *      ERROR_FLAG.
 147          * 11.  Set the internal state indicated by state_handle to
 148          *      the initial values for the internal state (i.e. set
 149          *      the working_state to the values returned as
 150          *      initial_working_state in step 9 and any other values
 151          *      required for the working_state, and set the
 152          *      administrative information to the appropriate values.
 153          *
 154          * (Almost nothing to do since the memory to hold the state
 155          * was passed in by the caller and has already been updated
 156          * in-situ.)
 157          */
 158         state->reseed_required = 0;
 159         state->valid = 1;
 160
 161         /* 12.  Return SUCCESS and state_handle. */
 162         return 0;
 163 }
 164
 165 /**
 166  * Reseed DRBG
 167  *
 168  * @v state             Algorithm state
 169  * @v additional        Additional input
 170  * @v additional_len    Length of additional input
 171  * @ret rc              Return status code
 172  *
 173  * This is the Reseed_function defined in ANS X9.82 Part 3-2007
 174  * Section 9.3 (NIST SP 800-90 Section 9.2).
 175  *
 176  * Prediction resistance is always enabled.
 177  */
 178 int drbg_reseed ( struct drbg_state *state, const void *additional,
 179                   size_t additional_len ) {
 180         unsigned int entropy_bits = DRBG_SECURITY_STRENGTH;
 181         size_t min_len = DRBG_MIN_ENTROPY_LEN_BYTES;
 182         size_t max_len = DRBG_MAX_ENTROPY_LEN_BYTES;
 183         uint8_t data[max_len];
 184         int len;
 185         int rc;
 186
 187         DBGC ( state, "DRBG %p reseed\n", state );
 188
 189         /* Sanity checks */
 190         assert ( state != NULL );
 191
 192         /* 1.  Using state_handle, obtain the current internal state.
 193          *     If state_handle indicates an invalid or empty internal
 194          *     state, return an ERROR_FLAG.
 195          *
 196          * (Almost nothing to do since the memory holding the internal
 197          * state was passed in by the caller.)
 198          */
 199         if ( ! state->valid ) {
 200                 DBGC ( state, "DRBG %p not valid\n", state );
 201                 return -EINVAL;
 202         }
 203
 204         /* 2.  If prediction_resistance_request is set, and
 205          *     prediction_resistance_flag is not set, then return an
 206          *     ERROR_FLAG.
 207          *
 208          * (Nothing to do since prediction resistance is always
 209          * supported.)
 210          */
 211
 212         /* 3.  If the length of the additional_input >
 213          *     max_additional_input_length, return an ERROR_FLAG.
 214          */
 215         if ( additional_len > DRBG_MAX_ADDITIONAL_LEN_BYTES ) {
 216                 DBGC ( state, "DRBG %p additional input too long (%zd bytes)\n",
 217                        state, additional_len );
 218                 return -ERANGE;
 219         }
 220
 221         /* 4.  ( status, entropy_input ) = Get_entropy_input (
 222          *     security_strength, min_length, max_length,
 223          *     prediction_resistance_request ).
 224          *
 225          * 5.  If an ERROR is returned in step 4, return a
 226          *     CATASTROPHIC_ERROR_FLAG.
 227          */
 228         len = get_entropy_input ( entropy_bits, data, min_len,
 229                                   sizeof ( data ) );
 230         if ( len < 0 ) {
 231                 rc = len;
 232                 DBGC ( state, "DRBG %p could not get entropy input: %s\n",
 233                        state, strerror ( rc ) );
 234                 return rc;
 235         }
 236
 237         /* 6.  new_working_state = Reseed_algorithm ( working_state,
 238          *     entropy_input, additional_input ).
 239          */
 240         drbg_reseed_algorithm ( state, data, len, additional, additional_len );
 241
 242         /* 7.  Replace the working_state in the internal state
 243          *     indicated by state_handle with the values of
 244          *     new_working_state obtained in step 6.
 245          *
 246          * (Nothing to do since the state has already been updated in-situ.)
 247          */
 248
 249         /* 8.  Return SUCCESS. */
 250         return 0;
 251 }
 252
 253 /**
 254  * Generate pseudorandom bits using DRBG
 255  *
 256  * @v state             Algorithm state
 257  * @v additional        Additional input
 258  * @v additional_len    Length of additional input
 259  * @v prediction_resist Prediction resistance is required
 260  * @v data              Output buffer
 261  * @v len               Length of output buffer
 262  * @ret rc              Return status code
 263  *
 264  * This is the Generate_function defined in ANS X9.82 Part 3-2007
 265  * Section 9.4 (NIST SP 800-90 Section 9.3).
 266  *
 267  * Requests must be for an integral number of bytes.  Only a single
 268  * security strength is supported.  Prediction resistance is supported
 269  * if requested.
 270  */
 271 int drbg_generate ( struct drbg_state *state, const void *additional,
 272                     size_t additional_len, int prediction_resist,
 273                     void *data, size_t len ) {
 274         int rc;
 275
 276         DBGC ( state, "DRBG %p generate\n", state );
 277
 278         /* Sanity checks */
 279         assert ( state != NULL );
 280         assert ( data != NULL );
 281
 282         /* 1.  Using state_handle, obtain the current internal state
 283          *     for the instantiation.  If state_handle indicates an
 284          *     invalid or empty internal state, then return an ERROR_FLAG.
 285          *
 286          * (Almost nothing to do since the memory holding the internal
 287          * state was passed in by the caller.)
 288          */
 289         if ( ! state->valid ) {
 290                 DBGC ( state, "DRBG %p not valid\n", state );
 291                 return -EINVAL;
 292         }
 293
 294         /* 2.  If requested_number_of_bits >
 295          *     max_number_of_bits_per_request, then return an
 296          *     ERROR_FLAG.
 297          */
 298         if ( len > DRBG_MAX_GENERATED_LEN_BYTES ) {
 299                 DBGC ( state, "DRBG %p request too long (%zd bytes)\n",
 300                        state, len );
 301                 return -ERANGE;
 302         }
 303
 304         /* 3.  If requested_security_strength > the security_strength
 305          *     indicated in the internal state, then return an
 306          *     ERROR_FLAG.
 307          *
 308          * (Nothing to do since only a single security strength is
 309          * supported.)
 310          */
 311
 312         /* 4.  If the length of the additional_input >
 313          *     max_additional_input_length, then return an ERROR_FLAG.
 314          */
 315         if ( additional_len > DRBG_MAX_ADDITIONAL_LEN_BYTES ) {
 316                 DBGC ( state, "DRBG %p additional input too long (%zd bytes)\n",
 317                        state, additional_len );
 318                 return -ERANGE;
 319         }
 320
 321         /* 5.  If prediction_resistance_request is set, and
 322          *     prediction_resistance_flag is not set, then return an
 323          *     ERROR_FLAG.
 324          *
 325          * (Nothing to do since prediction resistance is always
 326          * supported.)
 327          */
 328
 329         /* 6.  Clear the reseed_required_flag. */
 330         state->reseed_required = 0;
 331
 332  step_7:
 333         /* 7.  If reseed_required_flag is set, or if
 334          *     prediction_resistance_request is set, then
 335          */
 336         if ( state->reseed_required || prediction_resist ) {
 337
 338                 /* 7.1  status = Reseed_function ( state_handle,
 339                  *      prediction_resistance_request,
 340                  *      additional_input )
 341                  * 7.2  If status indicates an ERROR, then return
 342                  *      status.
 343                  */
 344                 if ( ( rc = drbg_reseed ( state, additional,
 345                                           additional_len ) ) != 0 ) {
 346                         DBGC ( state, "DRBG %p could not reseed: %s\n",
 347                                state, strerror ( rc ) );
 348                         return rc;
 349                 }
 350
 351                 /* 7.3  Using state_handle, obtain the new internal
 352                  *      state.
 353                  *
 354                  * (Nothing to do since the internal state has been
 355                  * updated in-situ.)
 356                  */
 357
 358                 /* 7.4  additional_input = the Null string. */
 359                 additional = NULL;
 360                 additional_len = 0;
 361
 362                 /* 7.5  Clear the reseed_required_flag. */
 363                 state->reseed_required = 0;
 364         }
 365
 366         /* 8.  ( status, pseudorandom_bits, new_working_state ) =
 367          *     Generate_algorithm ( working_state,
 368          *     requested_number_of_bits, additional_input ).
 369          */
 370         rc = drbg_generate_algorithm ( state, additional, additional_len,
 371                                        data, len );
 372
 373         /* 9.  If status indicates that a reseed is required before
 374          *     the requested bits can be generated, then
 375          */
 376         if ( rc != 0 ) {
 377
 378                 /* 9.1  Set the reseed_required_flag. */
 379                 state->reseed_required = 1;
 380
 381                 /* 9.2  If the prediction_resistance_flag is set, then
 382                  *      set the prediction_resistance_request
 383                  *      indication.
 384                  */
 385                 prediction_resist = 1;
 386
 387                 /* 9.3  Go to step 7. */
 388                 goto step_7;
 389         }
 390
 391         /* 10.  Replace the old working_state in the internal state
 392          *      indicated by state_handle with the values of
 393          *      new_working_state.
 394          *
 395          * (Nothing to do since the working state has already been
 396          * updated in-situ.)
 397          */
 398
 399         /* 11.  Return SUCCESS and pseudorandom_bits. */
 400         return 0;
 401 }
 402
 403 /**
 404  * Uninstantiate DRBG
 405  *
 406  * @v state             Algorithm state
 407  *
 408  * This is the Uninstantiate_function defined in ANS X9.82 Part 3-2007
 409  * Section 9.5 (NIST SP 800-90 Section 9.4).
 410  */
 411 void drbg_uninstantiate ( struct drbg_state *state ) {
 412
 413         DBGC ( state, "DRBG %p uninstantiate\n", state );
 414
 415         /* Sanity checks */
 416         assert ( state != NULL );
 417
 418         /* 1.  If state_handle indicates an invalid state, then return
 419          *     an ERROR_FLAG.
 420          *
 421          * (Nothing to do since the memory holding the internal state
 422          * was passed in by the caller.)
 423          */
 424
 425         /* 2.  Erase the contents of the internal state indicated by
 426          *     state_handle.
 427          */
 428         memset ( state, 0, sizeof ( *state ) );
 429
 430         /* 3.  Return SUCCESS. */
 431 }