1 // Copyright 2024 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_KDF_H_ 6 #define CRYPTO_KDF_H_ 7 8 #include "crypto/crypto_export.h" 9 #include "crypto/subtle_passkey.h" 10 #include "crypto/symmetric_key.h" 11 12 namespace crypto::kdf { 13 14 // A KDF (key derivation function) produces key material from a secret input, a 15 // salt, and a set of parameters controlling how much work the KDF should 16 // perform. They are used for: 17 // - Generating subkeys from a main key, or 18 // - Deriving keys from a cryptographically-weak secret like a password, in such 19 // a way that it is more difficult to mount a brute-force attack 20 // 21 // The KDFs themselves are free functions that take parameter structs. You will 22 // need a crypto::SubtlePassKey to call these since choosing the parameters 23 // requires some caution. 24 // 25 // TODO(https://issues.chromium.org/issues/369653192): add a sensible-default 26 // KDF that doesn't require a passkey. 27 28 struct Pbkdf2HmacSha1Params { 29 // BoringSSL uses a uint32_t for the iteration count for PBKDF2, so we match 30 // that. 31 uint32_t iterations; 32 }; 33 34 struct ScryptParams { 35 // These all match the relevant types in BoringSSL. 36 uint64_t cost; // aka 'N' in RFC 7914 37 uint64_t block_size; // aka 'r' in RFC 7914 38 uint64_t parallelization; // aka 'p' in RFC 7914 39 uint64_t max_memory_bytes = 0; // doesn't appear in the RFC 40 }; 41 42 // TODO(https://issues.chromium.org/issues/369653192): document constraints on 43 // params. 44 CRYPTO_EXPORT void DeriveKeyPbkdf2HmacSha1(const Pbkdf2HmacSha1Params& params, 45 base::span<const uint8_t> password, 46 base::span<const uint8_t> salt, 47 base::span<uint8_t> result, 48 crypto::SubtlePassKey); 49 50 // TODO(https://issues.chromium.org/issues/369653192): document constraints on 51 // params. 52 // 53 // Note: this function CHECKs that the passed-in ScryptParams are valid. If you 54 // are not sure if your params will be valid, consult a //crypto OWNER - the 55 // definition of valid is somewhat tricky. 56 CRYPTO_EXPORT void DeriveKeyScrypt(const ScryptParams& params, 57 base::span<const uint8_t> password, 58 base::span<const uint8_t> salt, 59 base::span<uint8_t> result, 60 crypto::SubtlePassKey); 61 62 } // namespace crypto::kdf 63 64 #endif // CRYPTO_KDF_H_ 65