Skip to content

Commit 7cb6113

Browse files
admkopecadmkopec
authored
New API Proposal: Password based KDF (#98)
Motivation: I've added a proposed implementation of PBKDF2, as per proposal in issue #59 to allow easy creation of SymmetricKey from relatively low entropy data sets, such as user provided passwords. Importance: This API change is attempting to simplify the creation of SymmetricKeys from user entered passwords. It uses an ageing algorithm – PBKDF2, but it is still widely supported and popular. A newer algorithm – scrypt is added as a better, more secure alternative. Modifications: I've proposed a new API: KDF namespace with Scrypt struct and an Insecure namespace with PBKDF2 struct with associated hash function and a single static method which takes a passphrase and salt, the size of the resulting key in bytes and optionally the number of rounds to use in the PBKDF2 algorithm. In the case of scrypt algorithm there is no associated hash function due to the nature of the algorithm, the single static method takes passphrase and salt, the size of the resulting key in bytes and optionally: the number of rounds, block size and parallelism factor. I implemented this functions using both CommonCrypto and BoringSSL where available. The function names and parameters are heavily influenced by current HKDF implementation. Additionally, I've added test cases to test the proposed API. I've decided to use test vectors described in RFC6070 for PBKDF2 and test vectors described in RFC7914 for scrypt. Result: This will add a new API to _CryptoKitExtras. It follows the naming conventions from CryptoKit's HKDF implementation.
1 parent 4518e5e commit 7cb6113

File tree

13 files changed

+719
-1
lines changed

13 files changed

+719
-1
lines changed

‎Sources/_CryptoExtras/CMakeLists.txt

+6
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@
1515
add_library(_CryptoExtras
1616
"ChaCha20CTR/BoringSSL/ChaCha20CTR_boring.swift"
1717
"ChaCha20CTR/ChaCha20CTR.swift"
18+
"Key Derivation/KDF.swift"
19+
"Key Derivation/PBKDF2/BoringSSL/PBKDF2_boring.swift"
20+
"Key Derivation/PBKDF2/BoringSSL/PBKDF2_commoncrypto.swift"
21+
"Key Derivation/PBKDF2/PBKDF2.swift"
22+
"Key Derivation/Scrypt/BoringSSL/Scrypt_boring.swift"
23+
"Key Derivation/Scrypt/Scrypt.swift"
1824
"RSA/RSA+BlindSigning.swift"
1925
"RSA/RSA.swift"
2026
"RSA/RSA_boring.swift"

‎Sources/_CryptoExtras/Key Derivation/KDF.swift

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// This source file is part of the SwiftCrypto open source project
4+
//
5+
// Copyright (c) 2024 Apple Inc. and the SwiftCrypto project authors
6+
// Licensed under Apache License v2.0
7+
//
8+
// See LICENSE.txt for license information
9+
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
10+
//
11+
// SPDX-License-Identifier: Apache-2.0
12+
//
13+
//===----------------------------------------------------------------------===//
14+
import Crypto
15+
#if canImport(Darwin) || swift(>=5.9.1)
16+
import Foundation
17+
#else
18+
@preconcurrency import Foundation
19+
#endif
20+
21+
/// A container for Key Detivation Function algorithms.
22+
public enum KDF: Sendable {
23+
/// A container for older, cryptographically insecure algorithms.
24+
///
25+
/// - Important: These algorithms aren’t considered cryptographically secure,
26+
/// but the framework provides them for backward compatibility with older
27+
/// services that require them. For new services, avoid these algorithms.
28+
public enum Insecure: Sendable {}
29+
}

‎Sources/_CryptoExtras/Key Derivation/PBKDF2/BoringSSL/PBKDF2_boring.swift

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// This source file is part of the SwiftCrypto open source project
4+
//
5+
// Copyright (c) 2021-2024 Apple Inc. and the SwiftCrypto project authors
6+
// Licensed under Apache License v2.0
7+
//
8+
// See LICENSE.txt for license information
9+
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
10+
//
11+
// SPDX-License-Identifier: Apache-2.0
12+
//
13+
//===----------------------------------------------------------------------===//
14+
import Crypto
15+
#if canImport(Darwin) || swift(>=5.9.1)
16+
import Foundation
17+
#else
18+
@preconcurrency import Foundation
19+
#endif
20+
21+
#if !canImport(CommonCrypto)
22+
@_implementationOnly import CCryptoBoringSSL
23+
@_implementationOnly import CCryptoBoringSSLShims
24+
25+
internal struct BoringSSLPBKDF2 {
26+
/// Derives a secure key using the provided hash function, passphrase and salt.
27+
///
28+
/// - Parameters:
29+
/// - password: The passphrase, which should be used as a basis for the key. This can be any type that conforms to `DataProtocol`, like `Data` or an array of `UInt8` instances.
30+
/// - salt: The salt to use for key derivation.
31+
/// - outputByteCount: The length in bytes of resulting symmetric key.
32+
/// - rounds: The number of rounds which should be used to perform key derivation.
33+
/// - Returns: The derived symmetric key.
34+
static func deriveKey<Passphrase: DataProtocol, Salt: DataProtocol>(from password: Passphrase, salt: Salt, using hashFunction: KDF.Insecure.PBKDF2.HashFunction, outputByteCount: Int, rounds: Int) throws -> SymmetricKey {
35+
// This should be SecureBytes, but we can't use that here.
36+
var derivedKeyData = Data(count: outputByteCount)
37+
38+
let rc = derivedKeyData.withUnsafeMutableBytes { derivedKeyBytes -> Int32 in
39+
let saltBytes: ContiguousBytes = salt.regions.count == 1 ? salt.regions.first! : Array(salt)
40+
return saltBytes.withUnsafeBytes { saltBytes -> Int32 in
41+
let passwordBytes: ContiguousBytes = password.regions.count == 1 ? password.regions.first! : Array(password)
42+
return passwordBytes.withUnsafeBytes { passwordBytes -> Int32 in
43+
return CCryptoBoringSSL_PKCS5_PBKDF2_HMAC(passwordBytes.baseAddress!, passwordBytes.count,
44+
saltBytes.baseAddress!, saltBytes.count,
45+
UInt32(rounds), hashFunction.digest,
46+
derivedKeyBytes.count, derivedKeyBytes.baseAddress!)
47+
}
48+
}
49+
}
50+
51+
guard rc == 1 else {
52+
throw CryptoKitError.internalBoringSSLError()
53+
}
54+
55+
return SymmetricKey(data: derivedKeyData)
56+
}
57+
}
58+
59+
extension KDF.Insecure.PBKDF2.HashFunction {
60+
var digest: OpaquePointer {
61+
switch self {
62+
case .insecureMD5:
63+
return CCryptoBoringSSL_EVP_md5()
64+
case .insecureSHA1:
65+
return CCryptoBoringSSL_EVP_sha1()
66+
case .insecureSHA224:
67+
return CCryptoBoringSSL_EVP_sha224()
68+
case .sha256:
69+
return CCryptoBoringSSL_EVP_sha256()
70+
case .sha384:
71+
return CCryptoBoringSSL_EVP_sha384()
72+
case .sha512:
73+
return CCryptoBoringSSL_EVP_sha512()
74+
default:
75+
preconditionFailure("Unsupported hash function: \(self.rawValue)")
76+
}
77+
}
78+
}
79+
80+
#endif

‎Sources/_CryptoExtras/Key Derivation/PBKDF2/BoringSSL/PBKDF2_commoncrypto.swift

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// This source file is part of the SwiftCrypto open source project
4+
//
5+
// Copyright (c) 2021-2024 Apple Inc. and the SwiftCrypto project authors
6+
// Licensed under Apache License v2.0
7+
//
8+
// See LICENSE.txt for license information
9+
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
10+
//
11+
// SPDX-License-Identifier: Apache-2.0
12+
//
13+
//===----------------------------------------------------------------------===//
14+
import Crypto
15+
#if canImport(Darwin) || swift(>=5.9.1)
16+
import Foundation
17+
#else
18+
@preconcurrency import Foundation
19+
#endif
20+
21+
#if canImport(CommonCrypto)
22+
@_implementationOnly import CommonCrypto
23+
24+
internal struct CommonCryptoPBKDF2 {
25+
/// Derives a secure key using the provided hash function, passphrase and salt.
26+
///
27+
/// - Parameters:
28+
/// - password: The passphrase, which should be used as a basis for the key. This can be any type that conforms to `DataProtocol`, like `Data` or an array of `UInt8` instances.
29+
/// - salt: The salt to use for key derivation.
30+
/// - outputByteCount: The length in bytes of resulting symmetric key.
31+
/// - rounds: The number of rounds which should be used to perform key derivation.
32+
/// - Returns: The derived symmetric key.
33+
static func deriveKey<Passphrase: DataProtocol, Salt: DataProtocol>(from password: Passphrase, salt: Salt, using hashFunction: KDF.Insecure.PBKDF2.HashFunction, outputByteCount: Int, rounds: Int) throws -> SymmetricKey {
34+
// This should be SecureBytes, but we can't use that here.
35+
var derivedKeyData = Data(count: outputByteCount)
36+
37+
let derivationStatus = derivedKeyData.withUnsafeMutableBytes { derivedKeyBytes -> Int32 in
38+
let saltBytes: ContiguousBytes = salt.regions.count == 1 ? salt.regions.first! : Array(salt)
39+
return saltBytes.withUnsafeBytes { saltBytes -> Int32 in
40+
let passwordBytes: ContiguousBytes = password.regions.count == 1 ? password.regions.first! : Array(password)
41+
return passwordBytes.withUnsafeBytes { passwordBytes -> Int32 in
42+
return CCKeyDerivationPBKDF(
43+
CCPBKDFAlgorithm(kCCPBKDF2),
44+
passwordBytes.baseAddress!,
45+
passwordBytes.count,
46+
saltBytes.baseAddress!,
47+
saltBytes.count,
48+
hashFunction.ccHash,
49+
UInt32(rounds),
50+
derivedKeyBytes.baseAddress!,
51+
derivedKeyBytes.count)
52+
}
53+
}
54+
}
55+
56+
if derivationStatus != kCCSuccess {
57+
throw CryptoKitError.underlyingCoreCryptoError(error: derivationStatus)
58+
}
59+
60+
return SymmetricKey(data: derivedKeyData)
61+
}
62+
}
63+
64+
extension KDF.Insecure.PBKDF2.HashFunction {
65+
var ccHash: CCPBKDFAlgorithm {
66+
switch self {
67+
case .insecureMD5:
68+
return CCPBKDFAlgorithm(kCCHmacAlgMD5)
69+
case .insecureSHA1:
70+
return CCPBKDFAlgorithm(kCCPRFHmacAlgSHA1)
71+
case .insecureSHA224:
72+
return CCPBKDFAlgorithm(kCCPRFHmacAlgSHA224)
73+
case .sha256:
74+
return CCPBKDFAlgorithm(kCCPRFHmacAlgSHA256)
75+
case .sha384:
76+
return CCPBKDFAlgorithm(kCCPRFHmacAlgSHA384)
77+
case .sha512:
78+
return CCPBKDFAlgorithm(kCCPRFHmacAlgSHA512)
79+
default:
80+
preconditionFailure("Unsupported hash function: \(self.rawValue)")
81+
}
82+
}
83+
}
84+
85+
#endif

‎Sources/_CryptoExtras/Key Derivation/PBKDF2/PBKDF2.swift

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// This source file is part of the SwiftCrypto open source project
4+
//
5+
// Copyright (c) 2021-2024 Apple Inc. and the SwiftCrypto project authors
6+
// Licensed under Apache License v2.0
7+
//
8+
// See LICENSE.txt for license information
9+
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
10+
//
11+
// SPDX-License-Identifier: Apache-2.0
12+
//
13+
//===----------------------------------------------------------------------===//
14+
import Crypto
15+
#if canImport(Darwin) || swift(>=5.9.1)
16+
import Foundation
17+
#else
18+
@preconcurrency import Foundation
19+
#endif
20+
21+
#if canImport(CommonCrypto)
22+
fileprivate typealias BackingPBKDF2 = CommonCryptoPBKDF2
23+
#else
24+
fileprivate typealias BackingPBKDF2 = BoringSSLPBKDF2
25+
#endif
26+
27+
extension KDF.Insecure {
28+
/// An implementation of PBKDF2 key derivation function.
29+
public struct PBKDF2: Sendable {
30+
/// Derives a symmetric key using the PBKDF2 algorithm.
31+
///
32+
/// - Parameters:
33+
/// - password: The passphrase, which should be used as a basis for the key. This can be any type that conforms to `DataProtocol`, like `Data` or an array of `UInt8` instances.
34+
/// - salt: The salt to use for key derivation.
35+
/// - hashFunction: The hash function to use for key derivation.
36+
/// - outputByteCount: The length in bytes of resulting symmetric key.
37+
/// - rounds: The number of rounds which should be used to perform key derivation. The minimum allowed number of rounds is 210,000.
38+
/// - Throws: An error if the number of rounds is less than 210,000
39+
/// - Note: The correct choice of rounds depends on a number of factors such as the hash function used, the speed of the target machine, and the intended use of the derived key. A good rule of thumb is to use rounds in the hundered of thousands or millions. For more information see OWASP's [Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html).
40+
/// - Returns: The derived symmetric key.
41+
public static func deriveKey<Passphrase: DataProtocol, Salt: DataProtocol>(from password: Passphrase, salt: Salt, using hashFunction: HashFunction, outputByteCount: Int, rounds: Int) throws -> SymmetricKey {
42+
guard rounds >= 210_000 else {
43+
throw CryptoKitError.incorrectParameterSize
44+
}
45+
return try PBKDF2.deriveKey(from: password, salt: salt, using: hashFunction, outputByteCount: outputByteCount, unsafeUncheckedRounds: rounds)
46+
}
47+
48+
/// Derives a symmetric key using the PBKDF2 algorithm.
49+
///
50+
/// - Parameters:
51+
/// - password: The passphrase, which should be used as a basis for the key. This can be any type that conforms to `DataProtocol`, like `Data` or an array of `UInt8` instances.
52+
/// - salt: The salt to use for key derivation.
53+
/// - hashFunction: The hash function to use for key derivation.
54+
/// - outputByteCount: The length in bytes of resulting symmetric key.
55+
/// - unsafeUncheckedRounds: The number of rounds which should be used to perform key derivation.
56+
/// - Warning: This method allows the use of parameters which may result in insecure keys. It is important to ensure that the used parameters do not compromise the security of the application.
57+
/// - Returns: The derived symmetric key.
58+
public static func deriveKey<Passphrase: DataProtocol, Salt: DataProtocol>(from password: Passphrase, salt: Salt, using hashFunction: HashFunction, outputByteCount: Int, unsafeUncheckedRounds: Int) throws -> SymmetricKey {
59+
return try BackingPBKDF2.deriveKey(from: password, salt: salt, using: hashFunction, outputByteCount: outputByteCount, rounds: unsafeUncheckedRounds)
60+
}
61+
62+
public struct HashFunction: Equatable, Hashable, Sendable {
63+
let rawValue: String
64+
65+
public static let insecureMD5 = HashFunction(rawValue: "insecure_md5")
66+
public static let insecureSHA1 = HashFunction(rawValue: "insecure_sha1")
67+
public static let insecureSHA224 = HashFunction(rawValue: "insecure_sha224")
68+
public static let sha256 = HashFunction(rawValue: "sha256")
69+
public static let sha384 = HashFunction(rawValue: "sha384")
70+
public static let sha512 = HashFunction(rawValue: "sha512")
71+
72+
init(rawValue: String) {
73+
self.rawValue = rawValue
74+
}
75+
}
76+
}
77+
}

‎Sources/_CryptoExtras/Key Derivation/Scrypt/BoringSSL/Scrypt_boring.swift

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// This source file is part of the SwiftCrypto open source project
4+
//
5+
// Copyright (c) 2024 Apple Inc. and the SwiftCrypto project authors
6+
// Licensed under Apache License v2.0
7+
//
8+
// See LICENSE.txt for license information
9+
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
10+
//
11+
// SPDX-License-Identifier: Apache-2.0
12+
//
13+
//===----------------------------------------------------------------------===//
14+
15+
import Crypto
16+
#if canImport(Darwin) || swift(>=5.9.1)
17+
import Foundation
18+
#else
19+
@preconcurrency import Foundation
20+
#endif
21+
@_implementationOnly import CCryptoBoringSSL
22+
@_implementationOnly import CCryptoBoringSSLShims
23+
24+
internal struct BoringSSLScrypt {
25+
/// Derives a secure key using the provided passphrase and salt.
26+
///
27+
/// - Parameters:
28+
/// - password: The passphrase, which should be used as a basis for the key. This can be any type that conforms to `DataProtocol`, like `Data` or an array of `UInt8` instances.
29+
/// - salt: The salt to use for key derivation.
30+
/// - outputByteCount: The length in bytes of resulting symmetric key.
31+
/// - rounds: The number of rounds which should be used to perform key derivation. Must be a power of 2.
32+
/// - blockSize: The block size to be used by the algorithm.
33+
/// - parallelism: The parallelism factor indicating how many threads should be run in parallel.
34+
/// - Returns: The derived symmetric key.
35+
static func deriveKey<Passphrase: DataProtocol, Salt: DataProtocol>(from password: Passphrase, salt: Salt, outputByteCount: Int, rounds: Int, blockSize: Int, parallelism: Int, maxMemory: Int? = nil) throws -> SymmetricKey {
36+
// This should be SecureBytes, but we can't use that here.
37+
var derivedKeyData = Data(count: outputByteCount)
38+
39+
// This computes the maximum amount of memory that will be used by the scrypt algorithm with an additional memory page to spare. This value will be used by the BoringSSL as the memory limit for the algorithm. An additional memory page is added to the computed value (using POSIX specification) to ensure that the memory limit is not too tight.
40+
let maxMemory = maxMemory ?? (128 * rounds * blockSize * parallelism + Int(sysconf(Int32(_SC_PAGESIZE))))
41+
42+
let result = derivedKeyData.withUnsafeMutableBytes { derivedKeyBytes -> Int32 in
43+
let saltBytes: ContiguousBytes = salt.regions.count == 1 ? salt.regions.first! : Array(salt)
44+
return saltBytes.withUnsafeBytes { saltBytes -> Int32 in
45+
let passwordBytes: ContiguousBytes = password.regions.count == 1 ? password.regions.first! : Array(password)
46+
return passwordBytes.withUnsafeBytes { passwordBytes -> Int32 in
47+
return CCryptoBoringSSL_EVP_PBE_scrypt(passwordBytes.baseAddress!, passwordBytes.count,
48+
saltBytes.baseAddress!, saltBytes.count,
49+
UInt64(rounds), UInt64(blockSize),
50+
UInt64(parallelism), maxMemory,
51+
derivedKeyBytes.baseAddress!, derivedKeyBytes.count)
52+
}
53+
}
54+
}
55+
56+
guard result == 1 else {
57+
throw CryptoKitError.internalBoringSSLError()
58+
}
59+
60+
return SymmetricKey(data: derivedKeyData)
61+
}
62+
}

‎Sources/_CryptoExtras/Key Derivation/Scrypt/Scrypt.swift

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
//===----------------------------------------------------------------------===//
2+
//
3+
// This source file is part of the SwiftCrypto open source project
4+
//
5+
// Copyright (c) 2024 Apple Inc. and the SwiftCrypto project authors
6+
// Licensed under Apache License v2.0
7+
//
8+
// See LICENSE.txt for license information
9+
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
10+
//
11+
// SPDX-License-Identifier: Apache-2.0
12+
//
13+
//===----------------------------------------------------------------------===//
14+
import Crypto
15+
#if canImport(Darwin) || swift(>=5.9.1)
16+
import Foundation
17+
#else
18+
@preconcurrency import Foundation
19+
#endif
20+
21+
fileprivate typealias BackingScrypt = BoringSSLScrypt
22+
23+
extension KDF {
24+
/// An implementation of scrypt key derivation function.
25+
public enum Scrypt: Sendable {
26+
/// Derives a symmetric key using the scrypt algorithm.
27+
///
28+
/// - Parameters:
29+
/// - password: The passphrase, which should be used as a basis for the key. This can be any type that conforms to `DataProtocol`, like `Data` or an array of `UInt8` instances.
30+
/// - salt: The salt to use for key derivation.
31+
/// - outputByteCount: The length in bytes of resulting symmetric key.
32+
/// - rounds: The number of rounds which should be used to perform key derivation. Must be a power of 2 less than `2^(128 * blockSize / 8)`.
33+
/// - blockSize: The block size to use for key derivation.
34+
/// - parallelism: The parallelism factor to use for key derivation. Must be a positive integer less than or equal to `((2^32 - 1) * 32) / (128 * blockSize)`.
35+
/// - maxMemory: The maximum amount of memory allowed to use for key derivation. If not provided, the default value is computed for the provided parameters.
36+
/// - Returns: The derived symmetric key.
37+
public static func deriveKey<Passphrase: DataProtocol, Salt: DataProtocol>(from password: Passphrase, salt: Salt, outputByteCount: Int, rounds: Int, blockSize: Int, parallelism: Int, maxMemory: Int? = nil) throws -> SymmetricKey {
38+
return try BackingScrypt.deriveKey(from: password, salt: salt, outputByteCount: outputByteCount, rounds: rounds, blockSize: blockSize, parallelism: parallelism)
39+
}
40+
}
41+
}

0 commit comments

Comments
 (0)