kdf.h (4018B)
1 // Copyright 2022 The BoringSSL Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef OPENSSL_HEADER_KDF_H 16 #define OPENSSL_HEADER_KDF_H 17 18 #include <openssl/base.h> // IWYU pragma: export 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 25 // KDF support for EVP. 26 27 28 // HKDF-specific functions. 29 // 30 // The following functions are provided for OpenSSL compatibility. Prefer the 31 // HKDF functions in <openssl/hkdf.h>. In each, |ctx| must be created with 32 // |EVP_PKEY_CTX_new_id| with |EVP_PKEY_HKDF| and then initialized with 33 // |EVP_PKEY_derive_init|. 34 35 // EVP_PKEY_HKDEF_MODE_* define "modes" for use with |EVP_PKEY_CTX_hkdf_mode|. 36 // The mispelling of "HKDF" as "HKDEF" is intentional for OpenSSL compatibility. 37 #define EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND 0 38 #define EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY 1 39 #define EVP_PKEY_HKDEF_MODE_EXPAND_ONLY 2 40 41 // EVP_PKEY_CTX_hkdf_mode configures which HKDF operation to run. It returns one 42 // on success and zero on error. |mode| must be one of |EVP_PKEY_HKDEF_MODE_*|. 43 // By default, the mode is |EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND|. 44 // 45 // If |mode| is |EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND| or 46 // |EVP_PKEY_HKDEF_MODE_EXPAND_ONLY|, the output is variable-length. 47 // |EVP_PKEY_derive| uses the size of the output buffer as the output length for 48 // HKDF-Expand. 49 // 50 // WARNING: Although this API calls it a "mode", HKDF-Extract and HKDF-Expand 51 // are distinct operations with distinct inputs and distinct kinds of keys. 52 // Callers should not pass input secrets for one operation into the other. 53 OPENSSL_EXPORT int EVP_PKEY_CTX_hkdf_mode(EVP_PKEY_CTX *ctx, int mode); 54 55 // EVP_PKEY_CTX_set_hkdf_md sets |md| as the digest to use with HKDF. It returns 56 // one on success and zero on error. 57 OPENSSL_EXPORT int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *ctx, 58 const EVP_MD *md); 59 60 // EVP_PKEY_CTX_set1_hkdf_key configures HKDF to use |key_len| bytes from |key| 61 // as the "key", described below. It returns one on success and zero on error. 62 // 63 // Which input is the key depends on the "mode" (see |EVP_PKEY_CTX_hkdf_mode|). 64 // If |EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND| or 65 // |EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY|, this function specifies the input keying 66 // material (IKM) for HKDF-Extract. If |EVP_PKEY_HKDEF_MODE_EXPAND_ONLY|, it 67 // instead specifies the pseudorandom key (PRK) for HKDF-Expand. 68 OPENSSL_EXPORT int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *ctx, 69 const uint8_t *key, 70 size_t key_len); 71 72 // EVP_PKEY_CTX_set1_hkdf_salt configures HKDF to use |salt_len| bytes from 73 // |salt| as the salt parameter to HKDF-Extract. It returns one on success and 74 // zero on error. If performing HKDF-Expand only, this parameter is ignored. 75 OPENSSL_EXPORT int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *ctx, 76 const uint8_t *salt, 77 size_t salt_len); 78 79 // EVP_PKEY_CTX_add1_hkdf_info appends |info_len| bytes from |info| to the info 80 // parameter used with HKDF-Expand. It returns one on success and zero on error. 81 // If performing HKDF-Extract only, this parameter is ignored. 82 OPENSSL_EXPORT int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *ctx, 83 const uint8_t *info, 84 size_t info_len); 85 86 87 #if defined(__cplusplus) 88 } // extern C 89 #endif 90 91 #endif // OPENSSL_HEADER_KDF_H