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 <string.h>
 28#include <limits.h>
 29#include <stdlib.h>
 30#include <CommonCrypto/CommonDigest.h>
 31#include <CommonCrypto/CommonHMAC.h>
 32
 33
 34#ifdef __cplusplus
 35extern "C" {
 36#endif
 37
 38enum {
 39    kCCPBKDF2 = 2,
 40};
 41
 42
 43typedef uint32_t CCPBKDFAlgorithm;
 44
 45
 46enum {
 47    kCCPRFHmacAlgSHA1 = 1,
 48    kCCPRFHmacAlgSHA224 = 2,
 49    kCCPRFHmacAlgSHA256 = 3,
 50    kCCPRFHmacAlgSHA384 = 4,
 51    kCCPRFHmacAlgSHA512 = 5,
 52};
 53
 54
 55typedef uint32_t CCPseudoRandomAlgorithm;
 56
 57/*
 58
 59 @function  CCKeyDerivationPBKDF
 60 @abstract  Derive a key from a text password/passphrase
 61
 62 @param algorithm       Currently only PBKDF2 is available via kCCPBKDF2
 63 @param password        The text password used as input to the derivation
 64                        function.  The actual octets present in this string
 65                        will be used with no additional processing.  It's
 66                        extremely important that the same encoding and
 67                        normalization be used each time this routine is
 68                        called if the same key is  expected to be derived.
 69 @param passwordLen     The length of the text password in bytes.
 70 @param salt            The salt byte values used as input to the derivation
 71                        function. The pointer can be NULL, only when saltLen is zero.
 72 @param saltLen         The length of the salt in bytes. It can be zero.
 73 @param prf             The Pseudo Random Algorithm to use for the derivation
 74                        iterations.
 75 @param rounds          The number of rounds of the Pseudo Random Algorithm
 76                        to use. It cannot be zero.
 77 @param derivedKey      The resulting derived key produced by the function.
 78                        The space for this must be provided by the caller.
 79 @param derivedKeyLen   The expected length of the derived key in bytes. It cannot be zero.
 80
 81 @discussion The following values are used to designate the PRF:
 82
 83 * kCCPRFHmacAlgSHA1
 84 * kCCPRFHmacAlgSHA224
 85 * kCCPRFHmacAlgSHA256
 86 * kCCPRFHmacAlgSHA384
 87 * kCCPRFHmacAlgSHA512
 88
 89 @result     kCCParamError can result from bad values for the password, salt,
 90 	     and unwrapped key pointers as well as a bad value for the prf
 91	     function.
 92
 93 */
 94
 95int
 96CCKeyDerivationPBKDF( CCPBKDFAlgorithm algorithm, const char *password, size_t passwordLen,
 97                      const uint8_t *salt, size_t saltLen,
 98                      CCPseudoRandomAlgorithm prf, unsigned rounds,
 99                      uint8_t *derivedKey, size_t derivedKeyLen)
100                      API_AVAILABLE(macos(10.7), ios(5.0));
101
102/*
103 * All lengths are in bytes - not bits.
104 */
105
106/*
107
108 @function  CCCalibratePBKDF
109 @abstract  Determine the number of PRF rounds to use for a specific delay on
110            the current platform.
111 @param algorithm       Currently only PBKDF2 is available via kCCPBKDF2
112 @param passwordLen     The length of the text password in bytes.
113 @param saltLen         The length of the salt in bytes. saltlen must be smaller than 133.
114 @param prf             The Pseudo Random Algorithm to use for the derivation
115                        iterations.
116 @param derivedKeyLen   The expected length of the derived key in bytes.
117 @param msec            The targetted duration we want to achieve for a key
118                        derivation with these parameters.
119
120 @result the number of iterations to use for the desired processing time.
121        Returns a minimum of 10000 iterations (safety net, not a particularly recommended value)
122            The number of iterations is a trade-off of usability and security. If there is an error
123            the function returns (unsigned)(-1). The minimum return value is set to 10000.
124
125 */
126
127unsigned
128CCCalibratePBKDF(CCPBKDFAlgorithm algorithm, size_t passwordLen, size_t saltLen,
129                 CCPseudoRandomAlgorithm prf, size_t derivedKeyLen, uint32_t msec)
130                 API_AVAILABLE(macos(10.7), ios(5.0));
131
132#ifdef __cplusplus
133}
134#endif
135
136#endif  /* _CC_PBKDF_H_ */