qemu/roms/ipxe/src/crypto/hmac_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
  20 FILE_LICENCE ( GPL2_OR_LATER );
  21
  22 /** @file
  23  *
  24  * HMAC_DRBG algorithm
  25  *
  26  * This algorithm is designed to comply with ANS X9.82 Part 3-2007
  27  * Section 10.2.2.2.  This standard is not freely available, but most
  28  * of the text appears to be shared with NIST SP 800-90, which can be
  29  * downloaded from
  30  *
  31  *     http://csrc.nist.gov/publications/nistpubs/800-90/SP800-90revised_March2007.pdf
  32  *
  33  * Where possible, references are given to both documents.  In the
  34  * case of any disagreement, ANS X9.82 takes priority over NIST SP
  35  * 800-90.  (In particular, note that some algorithms that are
  36  * Approved by NIST SP 800-90 are not Approved by ANS X9.82.)
  37  */
  38
  39 #include <stdint.h>
  40 #include <string.h>
  41 #include <errno.h>
  42 #include <assert.h>
  43 #include <ipxe/crypto.h>
  44 #include <ipxe/hmac.h>
  45 #include <ipxe/hmac_drbg.h>
  46
  47 /**
  48  * Update the HMAC_DRBG key
  49  *
  50  * @v hash              Underlying hash algorithm
  51  * @v state             HMAC_DRBG internal state
  52  * @v data              Provided data
  53  * @v len               Length of provided data
  54  * @v single            Single byte used in concatenation
  55  *
  56  * This function carries out the operation
  57  *
  58  *     K = HMAC ( K, V || single || provided_data )
  59  *
  60  * as used by hmac_drbg_update()
  61  */
  62 static void hmac_drbg_update_key ( struct digest_algorithm *hash,
  63                                    struct hmac_drbg_state *state,
  64                                    const void *data, size_t len,
  65                                    const uint8_t single ) {
  66         uint8_t context[ hash->ctxsize ];
  67         size_t out_len = hash->digestsize;
  68
  69         DBGC ( state, "HMAC_DRBG_%s %p provided data :\n", hash->name, state );
  70         DBGC_HDA ( state, 0, data, len );
  71
  72         /* Sanity checks */
  73         assert ( hash != NULL );
  74         assert ( state != NULL );
  75         assert ( ( data != NULL ) || ( len == 0 ) );
  76         assert ( ( single == 0x00 ) || ( single == 0x01 ) );
  77
  78         /* K = HMAC ( K, V || single || provided_data ) */
  79         hmac_init ( hash, context, state->key, &out_len );
  80         assert ( out_len == hash->digestsize );
  81         hmac_update ( hash, context, state->value, out_len );
  82         hmac_update ( hash, context, &single, sizeof ( single ) );
  83         hmac_update ( hash, context, data, len );
  84         hmac_final ( hash, context, state->key, &out_len, state->key );
  85         assert ( out_len == hash->digestsize );
  86
  87         DBGC ( state, "HMAC_DRBG_%s %p K = HMAC ( K, V || %#02x || "
  88                "provided_data ) :\n", hash->name, state, single );
  89         DBGC_HDA ( state, 0, state->key, out_len );
  90 }
  91
  92 /**
  93  * Update the HMAC_DRBG value
  94  *
  95  * @v hash              Underlying hash algorithm
  96  * @v state             HMAC_DRBG internal state
  97  * @v data              Provided data
  98  * @v len               Length of provided data
  99  * @v single            Single byte used in concatenation
 100  *
 101  * This function carries out the operation
 102  *
 103  *     V = HMAC ( K, V )
 104  *
 105  * as used by hmac_drbg_update() and hmac_drbg_generate()
 106  */
 107 static void hmac_drbg_update_value ( struct digest_algorithm *hash,
 108                                      struct hmac_drbg_state *state ) {
 109         uint8_t context[ hash->ctxsize ];
 110         size_t out_len = hash->digestsize;
 111
 112         /* Sanity checks */
 113         assert ( hash != NULL );
 114         assert ( state != NULL );
 115
 116         /* V = HMAC ( K, V ) */
 117         hmac_init ( hash, context, state->key, &out_len );
 118         assert ( out_len == hash->digestsize );
 119         hmac_update ( hash, context, state->value, out_len );
 120         hmac_final ( hash, context, state->key, &out_len, state->value );
 121         assert ( out_len == hash->digestsize );
 122
 123         DBGC ( state, "HMAC_DRBG_%s %p V = HMAC ( K, V ) :\n",
 124                hash->name, state );
 125         DBGC_HDA ( state, 0, state->value, out_len );
 126 }
 127
 128 /**
 129  * Update HMAC_DRBG internal state
 130  *
 131  * @v hash              Underlying hash algorithm
 132  * @v state             HMAC_DRBG internal state
 133  * @v data              Provided data
 134  * @v len               Length of provided data
 135  *
 136  * This is the HMAC_DRBG_Update function defined in ANS X9.82 Part
 137  * 3-2007 Section 10.2.2.2.2 (NIST SP 800-90 Section 10.1.2.2).
 138  *
 139  * The key and value are updated in-place within the HMAC_DRBG
 140  * internal state.
 141  */
 142 static void hmac_drbg_update ( struct digest_algorithm *hash,
 143                                struct hmac_drbg_state *state,
 144                                const void *data, size_t len ) {
 145
 146         DBGC ( state, "HMAC_DRBG_%s %p update\n", hash->name, state );
 147
 148         /* Sanity checks */
 149         assert ( hash != NULL );
 150         assert ( state != NULL );
 151         assert ( ( data != NULL ) || ( len == 0 ) );
 152
 153         /* 1.  K = HMAC ( K, V || 0x00 || provided_data ) */
 154         hmac_drbg_update_key ( hash, state, data, len, 0x00 );
 155
 156         /* 2.  V = HMAC ( K, V ) */
 157         hmac_drbg_update_value ( hash, state );
 158
 159         /* 3.  If ( provided_data = Null ), then return K and V */
 160         if ( ! len )
 161                 return;
 162
 163         /* 4.  K = HMAC ( K, V || 0x01 || provided_data ) */
 164         hmac_drbg_update_key ( hash, state, data, len, 0x01 );
 165
 166         /* 5.  V = HMAC ( K, V ) */
 167         hmac_drbg_update_value ( hash, state );
 168
 169         /* 6.  Return K and V */
 170 }
 171
 172 /**
 173  * Instantiate HMAC_DRBG
 174  *
 175  * @v hash              Underlying hash algorithm
 176  * @v state             HMAC_DRBG internal state to be initialised
 177  * @v entropy           Entropy input
 178  * @v entropy_len       Length of entropy input
 179  * @v personal          Personalisation string
 180  * @v personal_len      Length of personalisation string
 181  *
 182  * This is the HMAC_DRBG_Instantiate_algorithm function defined in ANS
 183  * X9.82 Part 3-2007 Section 10.2.2.2.3 (NIST SP 800-90 Section
 184  * 10.1.2.3).
 185  *
 186  * The nonce must be included within the entropy input (i.e. the
 187  * entropy input must contain at least 3/2 * security_strength bits of
 188  * entropy, as per ANS X9.82 Part 3-2007 Section 8.4.2 (NIST SP 800-90
 189  * Section 8.6.7).
 190  *
 191  * The key, value and reseed counter are updated in-place within the
 192  * HMAC_DRBG internal state.
 193  */
 194 void hmac_drbg_instantiate ( struct digest_algorithm *hash,
 195                              struct hmac_drbg_state *state,
 196                              const void *entropy, size_t entropy_len,
 197                              const void *personal, size_t personal_len ){
 198         size_t out_len = hash->digestsize;
 199
 200         DBGC ( state, "HMAC_DRBG_%s %p instantiate\n", hash->name, state );
 201
 202         /* Sanity checks */
 203         assert ( hash != NULL );
 204         assert ( state != NULL );
 205         assert ( entropy != NULL );
 206         assert ( ( personal != NULL ) || ( personal_len == 0 ) );
 207
 208         /* 1.  seed_material = entropy_input || nonce ||
 209          *     personalisation_string
 210          */
 211
 212         /* 2.  Key = 0x00 00..00 */
 213         memset ( state->key, 0x00, out_len );
 214
 215         /* 3.  V = 0x01 01...01 */
 216         memset ( state->value, 0x01, out_len );
 217
 218         /* 4.  ( Key, V ) = HMAC_DBRG_Update ( seed_material, Key, V )
 219          * 5.  reseed_counter = 1
 220          * 6.  Return V, Key and reseed_counter as the
 221          *     initial_working_state
 222          */
 223         hmac_drbg_reseed ( hash, state, entropy, entropy_len,
 224                            personal, personal_len );
 225 }
 226
 227 /**
 228  * Reseed HMAC_DRBG
 229  *
 230  * @v hash              Underlying hash algorithm
 231  * @v state             HMAC_DRBG internal state
 232  * @v entropy           Entropy input
 233  * @v entropy_len       Length of entropy input
 234  * @v additional        Additional input
 235  * @v additional_len    Length of additional input
 236  *
 237  * This is the HMAC_DRBG_Reseed_algorithm function defined in ANS X9.82
 238  * Part 3-2007 Section 10.2.2.2.4 (NIST SP 800-90 Section 10.1.2.4).
 239  *
 240  * The key, value and reseed counter are updated in-place within the
 241  * HMAC_DRBG internal state.
 242  */
 243 void hmac_drbg_reseed ( struct digest_algorithm *hash,
 244                         struct hmac_drbg_state *state,
 245                         const void *entropy, size_t entropy_len,
 246                         const void *additional, size_t additional_len ) {
 247         uint8_t seed_material[ entropy_len + additional_len ];
 248
 249         DBGC ( state, "HMAC_DRBG_%s %p (re)seed\n", hash->name, state );
 250
 251         /* Sanity checks */
 252         assert ( hash != NULL );
 253         assert ( state != NULL );
 254         assert ( entropy != NULL );
 255         assert ( ( additional != NULL ) || ( additional_len == 0 ) );
 256
 257         /* 1.  seed_material = entropy_input || additional_input */
 258         memcpy ( seed_material, entropy, entropy_len );
 259         memcpy ( ( seed_material + entropy_len ), additional, additional_len );
 260         DBGC ( state, "HMAC_DRBG_%s %p seed material :\n", hash->name, state );
 261         DBGC_HDA ( state, 0, seed_material, sizeof ( seed_material ) );
 262
 263         /* 2.  ( Key, V ) = HMAC_DBRG_Update ( seed_material, Key, V ) */
 264         hmac_drbg_update ( hash, state, seed_material,
 265                            sizeof ( seed_material ) );
 266
 267         /* 3.  reseed_counter = 1 */
 268         state->reseed_counter = 1;
 269
 270         /* 4.  Return V, Key and reseed_counter as the new_working_state */
 271 }
 272
 273 /**
 274  * Generate pseudorandom bits using HMAC_DRBG
 275  *
 276  * @v hash              Underlying hash algorithm
 277  * @v state             HMAC_DRBG internal state
 278  * @v additional        Additional input
 279  * @v additional_len    Length of additional input
 280  * @v data              Output buffer
 281  * @v len               Length of output buffer
 282  * @ret rc              Return status code
 283  *
 284  * This is the HMAC_DRBG_Generate_algorithm function defined in ANS X9.82
 285  * Part 3-2007 Section 10.2.2.2.5 (NIST SP 800-90 Section 10.1.2.5).
 286  *
 287  * Requests must be for an integral number of bytes.
 288  *
 289  * The key, value and reseed counter are updated in-place within the
 290  * HMAC_DRBG internal state.
 291  *
 292  * Note that the only permitted error is "reseed required".
 293  */
 294 int hmac_drbg_generate ( struct digest_algorithm *hash,
 295                          struct hmac_drbg_state *state,
 296                          const void *additional, size_t additional_len,
 297                          void *data, size_t len ) {
 298         size_t out_len = hash->digestsize;
 299         void *orig_data = data;
 300         size_t orig_len = len;
 301         size_t frag_len;
 302
 303         DBGC ( state, "HMAC_DRBG_%s %p generate\n", hash->name, state );
 304
 305         /* Sanity checks */
 306         assert ( hash != NULL );
 307         assert ( state != NULL );
 308         assert ( data != NULL );
 309         assert ( ( additional != NULL ) || ( additional_len == 0 ) );
 310
 311         /* 1.  If reseed_counter > reseed_interval, then return an
 312          *     indication that a reseed is required
 313          */
 314         if ( state->reseed_counter > HMAC_DRBG_RESEED_INTERVAL ) {
 315                 DBGC ( state, "HMAC_DRBG_%s %p reseed interval exceeded\n",
 316                        hash->name, state );
 317                 return -ESTALE;
 318         }
 319
 320         /* 2.  If additional_input != Null, then
 321          *     ( Key, V ) = HMAC_DRBG_Update ( additional_input, Key, V )
 322          */
 323         if ( additional_len )
 324                 hmac_drbg_update ( hash, state, additional, additional_len );
 325
 326         /* 3.  temp = Null
 327          * 4.  While ( len ( temp ) < requested_number_of_bits ) do:
 328          */
 329         while ( len ) {
 330
 331                 /* 4.1  V = HMAC ( Key, V ) */
 332                 hmac_drbg_update_value ( hash, state );
 333
 334                 /* 4.2.  temp = temp || V
 335                  * 5.    returned_bits = Leftmost requested_number_of_bits
 336                  *       of temp
 337                  */
 338                 frag_len = len;
 339                 if ( frag_len > out_len )
 340                         frag_len = out_len;
 341                 memcpy ( data, state->value, frag_len );
 342                 data += frag_len;
 343                 len -= frag_len;
 344         }
 345
 346         /* 6.  ( Key, V ) = HMAC_DRBG_Update ( additional_input, Key, V ) */
 347         hmac_drbg_update ( hash, state, additional, additional_len );
 348
 349         /* 7.  reseed_counter = reseed_counter + 1 */
 350         state->reseed_counter++;
 351
 352         DBGC ( state, "HMAC_DRBG_%s %p generated :\n", hash->name, state );
 353         DBGC_HDA ( state, 0, orig_data, orig_len );
 354
 355         /* 8.  Return SUCCESS, returned_bits, and the new values of
 356          *     Key, V and reseed_counter as the new_working_state
 357          */
 358         return 0;
 359 }