Home | History | Annotate | Download | only in crypto 
      1 // Copyright (c) 2011 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 #pragma once
      8 
      9 #include <string>
     10 
     11 #include "base/basictypes.h"
     12 
     13 #if defined(USE_NSS)
     14 #include "crypto/scoped_nss_types.h"
     15 #elif defined(OS_MACOSX)
     16 #include <Security/cssmtype.h>
     17 #elif defined(OS_WIN)
     18 #include "crypto/scoped_capi_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 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.
     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. The caller is responsible for
     45   // deleting the returned SymmetricKey.
     46   static SymmetricKey* DeriveKeyFromPassword(Algorithm algorithm,
     47                                              const std::string& password,
     48                                              const std::string& salt,
     49                                              size_t iterations,
     50                                              size_t key_size_in_bits);
     51 
     52   // Imports an array of key bytes in |raw_key|. This key may have been
     53   // generated by GenerateRandomKey or DeriveKeyFromPassword and exported with
     54   // GetRawKey, or via another compatible method. The key must be of suitable
     55   // size for use with |algorithm|. The caller owns the returned SymmetricKey.
     56   static SymmetricKey* Import(Algorithm algorithm, const std::string& raw_key);
     57 
     58 #if defined(USE_OPENSSL)
     59   const std::string& key() { return key_; }
     60 #elif defined(USE_NSS)
     61   PK11SymKey* key() const { return key_.get(); }
     62 #elif defined(OS_MACOSX)
     63   CSSM_DATA cssm_data() const;
     64 #elif defined(OS_WIN)
     65   HCRYPTKEY key() const { return key_.get(); }
     66 #endif
     67 
     68   // Extracts the raw key from the platform specific data.
     69   // Warning: |raw_key| holds the raw key as bytes and thus must be handled
     70   // carefully.
     71   bool GetRawKey(std::string* raw_key);
     72 
     73  private:
     74 #if defined(USE_OPENSSL)
     75   SymmetricKey() {}
     76   std::string key_;
     77 #elif defined(USE_NSS)
     78   explicit SymmetricKey(PK11SymKey* key);
     79   ScopedPK11SymKey key_;
     80 #elif defined(OS_MACOSX)
     81   SymmetricKey(const void* key_data, size_t key_size_in_bits);
     82   std::string key_;
     83 #elif defined(OS_WIN)
     84   SymmetricKey(HCRYPTPROV provider, HCRYPTKEY key,
     85                const void* key_data, size_t key_size_in_bytes);
     86 
     87   ScopedHCRYPTPROV provider_;
     88   ScopedHCRYPTKEY key_;
     89 
     90   // Contains the raw key, if it is known during initialization and when it
     91   // is likely that the associated |provider_| will be unable to export the
     92   // |key_|. This is the case of HMAC keys when the key size exceeds 16 bytes
     93   // when using the default RSA provider.
     94   // TODO(rsleevi): See if KP_EFFECTIVE_KEYLEN is the reason why CryptExportKey
     95   // fails with NTE_BAD_KEY/NTE_BAD_LEN
     96   std::string raw_key_;
     97 #endif
     98 
     99   DISALLOW_COPY_AND_ASSIGN(SymmetricKey);
    100 };
    101 
    102 }  // namespace crypto
    103 
    104 #endif  // CRYPTO_SYMMETRIC_KEY_H_
    105