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