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 <stddef.h>
9
10#include <memory>
11#include <string>
12
13#include "base/macros.h"
14#include "build/build_config.h"
15#include "crypto/crypto_export.h"
16
17namespace crypto {
18
19// Wraps a platform-specific symmetric key and allows it to be held in a
20// scoped_ptr.
21class CRYPTO_EXPORT SymmetricKey {
22 public:
23  // Defines the algorithm that a key will be used with. See also
24  // classs Encrptor.
25  enum Algorithm {
26    AES,
27    HMAC_SHA1,
28  };
29
30  virtual ~SymmetricKey();
31
32  // Generates a random key suitable to be used with |algorithm| and of
33  // |key_size_in_bits| bits. |key_size_in_bits| must be a multiple of 8.
34  // The caller is responsible for deleting the returned SymmetricKey.
35  static std::unique_ptr<SymmetricKey> GenerateRandomKey(
36      Algorithm algorithm,
37      size_t key_size_in_bits);
38
39  // Derives a key from the supplied password and salt using PBKDF2, suitable
40  // for use with specified |algorithm|. Note |algorithm| is not the algorithm
41  // used to derive the key from the password. |key_size_in_bits| must be a
42  // multiple of 8. The caller is responsible for deleting the returned
43  // SymmetricKey.
44  static std::unique_ptr<SymmetricKey> DeriveKeyFromPassword(
45      Algorithm algorithm,
46      const std::string& password,
47      const std::string& salt,
48      size_t iterations,
49      size_t key_size_in_bits);
50
51  // Imports an array of key bytes in |raw_key|. This key may have been
52  // generated by GenerateRandomKey or DeriveKeyFromPassword and exported with
53  // GetRawKey, or via another compatible method. The key must be of suitable
54  // size for use with |algorithm|. The caller owns the returned SymmetricKey.
55  static std::unique_ptr<SymmetricKey> Import(Algorithm algorithm,
56                                              const std::string& raw_key);
57
58  const std::string& key() { return key_; }
59
60  // Extracts the raw key from the platform specific data.
61  // Warning: |raw_key| holds the raw key as bytes and thus must be handled
62  // carefully.
63  bool GetRawKey(std::string* raw_key);
64
65 private:
66  SymmetricKey();
67
68  std::string key_;
69
70  DISALLOW_COPY_AND_ASSIGN(SymmetricKey);
71};
72
73}  // namespace crypto
74
75#endif  // CRYPTO_SYMMETRIC_KEY_H_
76