Home | History | Annotate | Download | only in crypto 
      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_
    106