1/* 2 * Copyright (c) 2010 Apple Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24#ifndef _CC_PBKDF_H_ 25#define _CC_PBKDF_H_ 26 27#include <sys/param.h> 28#include <string.h> 29#include <Availability.h> 30#ifdef KERNEL 31#include <machine/limits.h> 32#else 33#include <limits.h> 34#include <stdlib.h> 35#endif /* KERNEL */ 36#include <CommonCrypto/CommonDigest.h> 37#include <CommonCrypto/CommonHMAC.h> 38 39 40#ifdef __cplusplus 41extern "C" { 42#endif 43 44enum { 45 kCCPBKDF2 = 2, 46}; 47 48 49typedef uint32_t CCPBKDFAlgorithm; 50 51 52enum { 53 kCCPRFHmacAlgSHA1 = 1, 54 kCCPRFHmacAlgSHA224 = 2, 55 kCCPRFHmacAlgSHA256 = 3, 56 kCCPRFHmacAlgSHA384 = 4, 57 kCCPRFHmacAlgSHA512 = 5, 58}; 59 60 61typedef uint32_t CCPseudoRandomAlgorithm; 62 63/* 64 65 @function CCKeyDerivationPBKDF 66 @abstract Derive a key from a text password/passphrase 67 68 @param algorithm Currently only PBKDF2 is available via kCCPBKDF2 69 @param password The text password used as input to the derivation 70 function. The actual octets present in this string 71 will be used with no additional processing. It's 72 extremely important that the same encoding and 73 normalization be used each time this routine is 74 called if the same key is expected to be derived. 75 @param passwordLen The length of the text password in bytes. 76 @param salt The salt byte values used as input to the derivation 77 function. 78 @param saltLen The length of the salt in bytes. 79 @param prf The Pseudo Random Algorithm to use for the derivation 80 iterations. 81 @param rounds The number of rounds of the Pseudo Random Algorithm 82 to use. 83 @param derivedKey The resulting derived key produced by the function. 84 The space for this must be provided by the caller. 85 @param derivedKeyLen The expected length of the derived key in bytes. 86 87 @discussion The following values are used to designate the PRF: 88 89 * kCCPRFHmacAlgSHA1 90 * kCCPRFHmacAlgSHA224 91 * kCCPRFHmacAlgSHA256 92 * kCCPRFHmacAlgSHA384 93 * kCCPRFHmacAlgSHA512 94 95 @result kCCParamError can result from bad values for the password, salt, 96 and unwrapped key pointers as well as a bad value for the prf 97 function. 98 99 */ 100 101int 102CCKeyDerivationPBKDF( CCPBKDFAlgorithm algorithm, const char *password, size_t passwordLen, 103 const uint8_t *salt, size_t saltLen, 104 CCPseudoRandomAlgorithm prf, uint rounds, 105 uint8_t *derivedKey, size_t derivedKeyLen) 106 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 107 108/* 109 * All lengths are in bytes - not bits. 110 */ 111 112/* 113 114 @function CCCalibratePBKDF 115 @abstract Determine the number of PRF rounds to use for a specific delay on 116 the current platform. 117 @param algorithm Currently only PBKDF2 is available via kCCPBKDF2 118 @param passwordLen The length of the text password in bytes. 119 @param saltLen The length of the salt in bytes. 120 @param prf The Pseudo Random Algorithm to use for the derivation 121 iterations. 122 @param derivedKeyLen The expected length of the derived key in bytes. 123 @param msec The targetted duration we want to achieve for a key 124 derivation with these parameters. 125 126 @result the number of iterations to use for the desired processing time. 127 128 */ 129 130uint 131CCCalibratePBKDF(CCPBKDFAlgorithm algorithm, size_t passwordLen, size_t saltLen, 132 CCPseudoRandomAlgorithm prf, size_t derivedKeyLen, uint32_t msec) 133 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 134 135#ifdef __cplusplus 136} 137#endif 138 139#endif /* _CC_PBKDF_H_ */ 140