1 // Copyright 2012 The Chromium Authors 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/containers/span.h" 14 #include "build/build_config.h" 15 #include "crypto/crypto_export.h" 16 17 namespace crypto { 18 19 // A SymmetricKey is an array of bytes which is used for symmetric cryptography 20 // (encryption or MACs). 21 // 22 // This whole type is deprecated: prefer to use raw std::array<uint8_t>, 23 // std::vector<uint8_t>, or base::span<uint8_t> instead. This type has no 24 // behavior or particular meaning. 25 // 26 // TODO(https://issues.chromium.org/issues/370724578): get rid of this. 27 class CRYPTO_EXPORT SymmetricKey { 28 public: 29 // Defines the algorithm that a key will be used with. See also 30 // class Encryptor. 31 enum Algorithm { 32 AES, 33 HMAC_SHA1, 34 }; 35 36 SymmetricKey() = delete; 37 38 // Wrap the given span of bytes as a SymmetricKey. 39 explicit SymmetricKey(base::span<const uint8_t> key_bytes); 40 virtual ~SymmetricKey(); 41 42 SymmetricKey(const SymmetricKey&); 43 SymmetricKey& operator=(const SymmetricKey&); 44 45 // Generates a random key suitable to be used with |algorithm| and of 46 // |key_size_in_bits| bits. |key_size_in_bits| must be a multiple of 8. 47 // The caller is responsible for deleting the returned SymmetricKey. 48 // 49 // Deprecated: use the value version below that does not take an algorithm. 50 static std::unique_ptr<SymmetricKey> GenerateRandomKey( 51 Algorithm algorithm, 52 size_t key_size_in_bits); 53 54 static SymmetricKey RandomKey(size_t key_size_in_bits); 55 56 // Derives a key from the supplied password and salt using PBKDF2, suitable 57 // for use with specified |algorithm|. Note |algorithm| is not the algorithm 58 // used to derive the key from the password. |key_size_in_bits| must be a 59 // multiple of 8. The caller is responsible for deleting the returned 60 // SymmetricKey. 61 // 62 // Deprecated: use crypto::kdf::DeriveKeyPBKDF2() instead. 63 static std::unique_ptr<SymmetricKey> DeriveKeyFromPasswordUsingPbkdf2( 64 Algorithm algorithm, 65 const std::string& password, 66 const std::string& salt, 67 size_t iterations, 68 size_t key_size_in_bits); 69 70 // Derives a key from the supplied password and salt using scrypt, suitable 71 // for use with specified |algorithm|. Note |algorithm| is not the algorithm 72 // used to derive the key from the password. |cost_parameter|, |block_size|, 73 // and |parallelization_parameter| correspond to the parameters |N|, |r|, and 74 // |p| from the scrypt specification (see RFC 7914). |key_size_in_bits| must 75 // be a multiple of 8. The caller is responsible for deleting the returned 76 // SymmetricKey. 77 // 78 // Deprecated: use crypto::kdf::DeriveKeyScrypt() instead. 79 // Warning: this function will CHECK() that the passed in parameters are 80 // valid, and the definition of 'valid' is subtle. Be careful using it. 81 static std::unique_ptr<SymmetricKey> DeriveKeyFromPasswordUsingScrypt( 82 Algorithm algorithm, 83 const std::string& password, 84 const std::string& salt, 85 size_t cost_parameter, 86 size_t block_size, 87 size_t parallelization_parameter, 88 size_t max_memory_bytes, 89 size_t key_size_in_bits); 90 91 // Imports an array of key bytes in |raw_key|. This key may have been 92 // generated by GenerateRandomKey or DeriveKeyFromPassword{Pbkdf2,Scrypt} and 93 // exported with key(). The key must be of suitable size for use with 94 // |algorithm|. The caller owns the returned SymmetricKey. 95 // 96 // Deprecated: use the regular constructor that accepts a span of bytes, 97 // or use the Import() override that returns an optional if you need to 98 // tolerate failures. 99 static std::unique_ptr<SymmetricKey> Import(Algorithm algorithm, 100 const std::string& raw_key); 101 102 // Returns the raw platform specific key data. key()103 const std::string& key() const { return key_; } 104 105 private: 106 std::string key_; 107 }; 108 109 } // namespace crypto 110 111 #endif // CRYPTO_SYMMETRIC_KEY_H_ 112