1 /* Copyright (c) (2014,2015,2017-2020) Apple Inc. All rights reserved. 2 * 3 * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which 4 * is contained in the License.txt file distributed with corecrypto) and only to 5 * people who accept that license. IMPORTANT: Any license rights granted to you by 6 * Apple Inc. (if any) are limited to internal use within your organization only on 7 * devices and computers you own or control, for the sole purpose of verifying the 8 * security characteristics and correct functioning of the Apple Software. You may 9 * not, directly or indirectly, redistribute the Apple Software or any portions thereof. 10 */ 11 12 #ifndef _CORECRYPTO_CCHKDF_H_ 13 #define _CORECRYPTO_CCHKDF_H_ 14 15 #include <corecrypto/ccdigest.h> 16 17 /*! 18 @function cchkdf 19 @abstract Perform a RFC5869-compliant HKDF. 20 https://tools.ietf.org/html/rfc5869 21 @discussion Derives output key data from input key data, optional salt, and info. 22 23 @param di Hash function to use. 24 @param ikm_nbytes Input key material length in bytes 25 @param ikm Input key material used to derive the new key 26 @param salt_nbytes Salt length length 27 @param salt Salt data 28 @param info_nbytes Info string length 29 @param info Info string 30 @param dk_nbytes Derived Key Length in bytes. 31 @param dk Derived key buffer to receive results of KDF 32 33 @return 0 on success, non-zero on failure. See cc_error.h for more details. 34 */ 35 36 int cchkdf(const struct ccdigest_info *di, 37 size_t ikm_nbytes, 38 const void *ikm, 39 size_t salt_nbytes, 40 const void *salt, 41 size_t info_nbytes, 42 const void *info, 43 size_t dk_nbytes, 44 void *dk); 45 46 /*! 47 @function cchkdf_extract 48 @abstract Perform a RFC5869-compliant HKDF-Extract 49 https://tools.ietf.org/html/rfc5869 50 @discussion Extract a pseudorandom key (PRK) from input keying material and a salt. 51 52 Note: In most cases, clients should use `cchkdf`. This function 53 is only exposed for specific use cases. 54 55 @param di Hash function to use. 56 @param salt_nbytes Salt length length 57 @param salt Salt data 58 @param ikm_nbytes Input key material length in bytes 59 @param ikm Input key material used to derive the new key 60 @param prk Pseudorandom Key (PRK) buffer to receive results of KDF, which must be equal 61 to the size of the hash function (di). 62 63 @return 0 on success, non-zero on failure. See cc_error.h for more details. 64 */ 65 66 int cchkdf_extract(const struct ccdigest_info *di, 67 size_t salt_nbytes, 68 const void *salt, 69 size_t ikm_nbytes, 70 const void *ikm, 71 void *prk); 72 73 /*! 74 @function cchkdf_expand 75 @abstract Perform a RFC5869-compliant HKDF-Expand 76 https://tools.ietf.org/html/rfc5869 77 @discussion Expands a pseudo-random key to the desired length, using the according 78 info. 79 80 Note: In most cases, clients should use `cchkdf`. This function 81 is only exposed for specific use cases. 82 83 @param di Hash function to use. 84 @param prk_nbytes Pseudo-random key length in bytes 85 @param prk Pseudo-random key used to derive the new key 86 @param info_nbytes Info string length 87 @param info Info string 88 @param dk_nbytes Derived Key Length in bytes. 89 @param dk Derived key buffer to receive results of KDF 90 91 @return 0 on success, non-zero on failure. See cc_error.h for more details. 92 */ 93 94 int cchkdf_expand(const struct ccdigest_info *di, 95 size_t prk_nbytes, 96 const void *prk, 97 size_t info_nbytes, 98 const void *info, 99 size_t dk_nbytes, 100 void *dk); 101 102 #endif /* _CORECRYPTO_CCHKDF_H_ */ 103