crypto/symmetric_key.h

   1 // Copyright 2012 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CRYPTO_SYMMETRIC_KEY_H_
   6 #define CRYPTO_SYMMETRIC_KEY_H_
   7
   8 #include <stddef.h>
   9
  10 #include <memory>
  11 #include <string>
  12
  13 #include "build/build_config.h"
  14 #include "crypto/crypto_export.h"
  15
  16 namespace crypto {
  17
  18 // Wraps a platform-specific symmetric key and allows it to be held in a
  19 // scoped_ptr.
  20 class CRYPTO_EXPORT SymmetricKey {
  21  public:
  22   // Defines the algorithm that a key will be used with. See also
  23   // classs Encrptor.
  24   enum Algorithm {
  25     AES,
  26     HMAC_SHA1,
  27   };
  28
  29   SymmetricKey(const SymmetricKey&) = delete;
  30   SymmetricKey& operator=(const SymmetricKey&) = delete;
  31
  32   virtual ~SymmetricKey();
  33
  34   // Generates a random key suitable to be used with |algorithm| and of
  35   // |key_size_in_bits| bits. |key_size_in_bits| must be a multiple of 8.
  36   // The caller is responsible for deleting the returned SymmetricKey.
  37   static std::unique_ptr<SymmetricKey> GenerateRandomKey(
  38       Algorithm algorithm,
  39       size_t key_size_in_bits);
  40
  41   // Derives a key from the supplied password and salt using PBKDF2, suitable
  42   // for use with specified |algorithm|. Note |algorithm| is not the algorithm
  43   // used to derive the key from the password. |key_size_in_bits| must be a
  44   // multiple of 8. The caller is responsible for deleting the returned
  45   // SymmetricKey.
  46   static std::unique_ptr<SymmetricKey> DeriveKeyFromPasswordUsingPbkdf2(
  47       Algorithm algorithm,
  48       const std::string& password,
  49       const std::string& salt,
  50       size_t iterations,
  51       size_t key_size_in_bits);
  52
  53   // Derives a key from the supplied password and salt using scrypt, suitable
  54   // for use with specified |algorithm|. Note |algorithm| is not the algorithm
  55   // used to derive the key from the password. |cost_parameter|, |block_size|,
  56   // and |parallelization_parameter| correspond to the parameters |N|, |r|, and
  57   // |p| from the scrypt specification (see RFC 7914). |key_size_in_bits| must
  58   // be a multiple of 8. The caller is responsible for deleting the returned
  59   // SymmetricKey.
  60   static std::unique_ptr<SymmetricKey> DeriveKeyFromPasswordUsingScrypt(
  61       Algorithm algorithm,
  62       const std::string& password,
  63       const std::string& salt,
  64       size_t cost_parameter,
  65       size_t block_size,
  66       size_t parallelization_parameter,
  67       size_t max_memory_bytes,
  68       size_t key_size_in_bits);
  69
  70   // Imports an array of key bytes in |raw_key|. This key may have been
  71   // generated by GenerateRandomKey or DeriveKeyFromPassword{Pbkdf2,Scrypt} and
  72   // exported with key(). The key must be of suitable size for use with
  73   // |algorithm|. The caller owns the returned SymmetricKey.
  74   static std::unique_ptr<SymmetricKey> Import(Algorithm algorithm,
  75                                               const std::string& raw_key);
  76
  77   // Returns the raw platform specific key data.
  78   const std::string& key() const { return key_; }
  79
  80  private:
  81   SymmetricKey();
  82
  83   std::string key_;
  84 };
  85
  86 }  // namespace crypto
  87
  88 #endif  // CRYPTO_SYMMETRIC_KEY_H_