crypto/symmetric_key.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   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 <string>
   9
  10 #include "base/basictypes.h"
  11 #include "crypto/crypto_export.h"
  12
  13 #if defined(NACL_WIN64)
  14 // See comments for crypto_nacl_win64 in crypto.gyp.
  15 // Must test for NACL_WIN64 before OS_WIN since former is a subset of latter.
  16 #include "crypto/scoped_capi_types.h"
  17 #elif defined(USE_NSS) || defined(OS_WIN) || defined(OS_MACOSX)
  18 #include "crypto/scoped_nss_types.h"
  19 #endif
  20
  21 namespace crypto {
  22
  23 // Wraps a platform-specific symmetric key and allows it to be held in a
  24 // scoped_ptr.
  25 class CRYPTO_EXPORT SymmetricKey {
  26  public:
  27   // Defines the algorithm that a key will be used with. See also
  28   // classs Encrptor.
  29   enum Algorithm {
  30     AES,
  31     HMAC_SHA1,
  32   };
  33
  34   virtual ~SymmetricKey();
  35
  36   // Generates a random key suitable to be used with |algorithm| and of
  37   // |key_size_in_bits| bits. |key_size_in_bits| must be a multiple of 8.
  38   // The caller is responsible for deleting the returned SymmetricKey.
  39   static SymmetricKey* GenerateRandomKey(Algorithm algorithm,
  40                                          size_t key_size_in_bits);
  41
  42   // Derives a key from the supplied password and salt using PBKDF2, suitable
  43   // for use with specified |algorithm|. Note |algorithm| is not the algorithm
  44   // used to derive the key from the password. |key_size_in_bits| must be a
  45   // multiple of 8. The caller is responsible for deleting the returned
  46   // SymmetricKey.
  47   static SymmetricKey* DeriveKeyFromPassword(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   // Imports an array of key bytes in |raw_key|. This key may have been
  54   // generated by GenerateRandomKey or DeriveKeyFromPassword and exported with
  55   // GetRawKey, or via another compatible method. The key must be of suitable
  56   // size for use with |algorithm|. The caller owns the returned SymmetricKey.
  57   static SymmetricKey* Import(Algorithm algorithm, const std::string& raw_key);
  58
  59 #if defined(USE_OPENSSL)
  60   const std::string& key() { return key_; }
  61 #elif defined(NACL_WIN64)
  62   HCRYPTKEY key() const { return key_.get(); }
  63 #elif defined(USE_NSS) || defined(OS_WIN) || defined(OS_MACOSX)
  64   PK11SymKey* key() const { return key_.get(); }
  65 #endif
  66
  67   // Extracts the raw key from the platform specific data.
  68   // Warning: |raw_key| holds the raw key as bytes and thus must be handled
  69   // carefully.
  70   bool GetRawKey(std::string* raw_key);
  71
  72 #if defined(OS_CHROMEOS)
  73   // Creates symmetric key from NSS key. Takes over the ownership of |key|.
  74   static SymmetricKey* CreateFromKey(PK11SymKey* key);
  75 #endif
  76
  77  private:
  78 #if defined(USE_OPENSSL)
  79   SymmetricKey() {}
  80   std::string key_;
  81 #elif defined(NACL_WIN64)
  82   SymmetricKey(HCRYPTPROV provider, HCRYPTKEY key,
  83                const void* key_data, size_t key_size_in_bytes);
  84
  85   ScopedHCRYPTPROV provider_;
  86   ScopedHCRYPTKEY key_;
  87
  88   // Contains the raw key, if it is known during initialization and when it
  89   // is likely that the associated |provider_| will be unable to export the
  90   // |key_|. This is the case of HMAC keys when the key size exceeds 16 bytes
  91   // when using the default RSA provider.
  92   // TODO(rsleevi): See if KP_EFFECTIVE_KEYLEN is the reason why CryptExportKey
  93   // fails with NTE_BAD_KEY/NTE_BAD_LEN
  94   std::string raw_key_;
  95 #elif defined(USE_NSS) || defined(OS_WIN) || defined(OS_MACOSX)
  96   explicit SymmetricKey(PK11SymKey* key);
  97   ScopedPK11SymKey key_;
  98 #endif
  99
 100   DISALLOW_COPY_AND_ASSIGN(SymmetricKey);
 101 };
 102
 103 }  // namespace crypto
 104
 105 #endif  // CRYPTO_SYMMETRIC_KEY_H_