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
21namespace crypto {
22
23// Wraps a platform-specific symmetric key and allows it to be held in a
24// scoped_ptr.
25class 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