1 # Key Derivation 2 3 4 A key derivation function (KDF) is a cryptographic algorithm that derives one or more secrete keys from a secret value (such as a master key) by using a pseudorandom function. It can be used to stretch keys into longer keys or to obtain keys in the required format. 5 6 7 For example, you can use a KDF to convert the passwords entered by users to the specified length. 8 9 10 ## Supported Algorithms and Specifications 11 12 Currently, only the PBKDF Function 2 (PBKDF2) algorithm is supported. 13 14 Password-Based Key Derivation Function (PBKDF) is a key derivation function with a sliding computational cost. PBKDF2 is part of the PKCS series. 15 16 PBKDF2 applies a pseudorandom function (PRF), such as [HMAC](crypto-compute-mac.md), to an input password together with a salt value, and repeats the process multiple times to generate a derived key. 17 18 When creating a **kDF** instance, you need to specify the algorithm specifications in a string parameter. The string parameter consists of the KDF algorithm and HMAC algorithm with a vertical bar (|) in between. 19 | KDF Algorithm| HMAC Algorithm| String Parameter| API Version| 20 | -------- | -------- | -------- | -------- | 21 | PBKDF2 | SHA1 | PBKDF2\|SHA1 | 11+ | 22 | PBKDF2 | SHA224 | PBKDF2\|SHA224 | 11+ | 23 | PBKDF2 | SHA256 | PBKDF2\|SHA256 | 11+ | 24 | PBKDF2 | SHA384 | PBKDF2\|SHA384 | 11+ | 25 | PBKDF2 | SHA512 | PBKDF2\|SHA512 | 11+ | 26 | PBKDF2 | SM3 | PBKDF2\|SM3 | 11+ | 27 28 29 ## How to Develop 30 31 1. Create a [PBKDF2Spec](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#pbkdf2spec11) object and use it as a parameter for key derivation. 32 33 **PBKDF2Spec** is a child class of **KdfSpec**. You need to specify the following: 34 35 - **algName**: algorithm to used, which is **'PBKDF2'**. 36 - **password**: original password used to generate the derived key. 37 If the password is of the string type, pass in the data used for key derivation instead of the string type such as HexString or base64. In addition, ensure that the string is encoded in UTF-8 format. Otherwise, the derived key may be different from what you expected. 38 - **salt**: salt value. 39 - **iterations**: number of iterations. The value must be a positive integer. 40 - **keySize**: length of the derived key, in bytes. The value must be a positive integer. 41 42 2. Use [cryptoFramework.createKdf](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatekdf11) with the string parameter **'PBKDF2|SHA256'** to create a **Kdf** object. 43 44 3. Use [Kdf.generateSecret](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#generatesecret-2) with the **PBKDF2Spec** object to generate a derived key. 45 46 The following table lists how **Kdf.generateSecret** delivers the return value. 47 48 | API| Return Mode| 49 | -------- | -------- | 50 | generateSecret(params: KdfSpec, callback: AsyncCallback<DataBlob>): void | This API uses an asynchronous callback to return the result.| 51 | generateSecret(params: KdfSpec): Promise<DataBlob> | This API uses a promise to return the result.| 52 53 - Return the result using **await**: 54 ```ts 55 import cryptoFramework from '@ohos.security.cryptoFramework'; 56 57 async function kdfAwait() { 58 let spec: cryptoFramework.PBKDF2Spec = { 59 algName: 'PBKDF2', 60 password: '123456', 61 salt: new Uint8Array(16), 62 iterations: 10000, 63 keySize: 32 64 }; 65 let kdf = cryptoFramework.createKdf('PBKDF2|SHA256'); 66 let secret = await kdf.generateSecret(spec); 67 console.info("key derivation output is " + secret.data); 68 } 69 ``` 70 71 - Return the result using a promise: 72 ```ts 73 import cryptoFramework from '@ohos.security.cryptoFramework'; 74 import { BusinessError } from '@ohos.base'; 75 76 function kdfPromise() { 77 let spec: cryptoFramework.PBKDF2Spec = { 78 algName: 'PBKDF2', 79 password: '123456', 80 salt: new Uint8Array(16), 81 iterations: 10000, 82 keySize: 32 83 }; 84 let kdf = cryptoFramework.createKdf('PBKDF2|SHA256'); 85 let kdfPromise = kdf.generateSecret(spec); 86 kdfPromise.then((secret) => { 87 console.info("key derivation output is " + secret.data); 88 }).catch((error: BusinessError) => { 89 console.error("key derivation error."); 90 }); 91 } 92 ``` 93