CCCommonKeyDerivation.3cc   [plain text]

.Dd January 21, 2011
.Dt CCCommonKeyDerivation.3cc
.Os
.Sh NAME
.Nm CCKeyDerivationPBKDF ,
.Nm CCCalibratePBKDF
.Nd Common Key Derivation Interfaces
.Sh LIBRARY
These functions are found in libSystem.
.Sh SYNOPSIS
.In CommonCrypto/CommonKeyDerivation.h
.Ft int
.Fn CCKeyDerivationPBKDF "CCPBKDFAlgorithm algorithm" "const char *password" \
"size_t passwordLen" "const uint8_t *salt""size_t saltLen" "CCPseudoRandomAlgorithm prf" \
"uint rounds" "uint8_t *derivedKey""size_t derivedKeyLen"
.Ft uint
.Fn CCCalibratePBKDF "CCPBKDFAlgorithm algorithm" "size_t passwordLen" "size_t saltLen" \
"CCPseudoRandomAlgorithm prf" "size_t derivedKeyLen" "uint32_t msec" 
.Sh DESCRIPTION
.Ss Function  
.Nm CCKeyDerivationPBKDF
.Ss Abstract  
Derive a key from a text password/passphrase
.Ss Parameters
.Bl -tag
.It algorithm       
Currently only PBKDF2 is available via kCCPBKDF2
.It password              
The text password used as input to the derivation function.  The actual octets present in \
this string will be used with no additional processing.  It's extremely important that the \
same encoding and normalization be used each time this routine is called if the same key \
is  expected to be derived.
.It passwordLen           
The length of the text password in bytes.
.It salt             
The salt byte values used as input to the derivation function.
.It saltLen          
The length of the salt in bytes.
.It prf          
The Pseudo Random Algorithm to use for the derivation iterations.
.It rounds       
The number of rounds of the Pseudo Random Algorithm to use.
.It derivedKey      
The resulting derived key produced by the function.  The space for this must be provided \
by the caller.
.It derivedKeyLen   
The length of the derived key in bytes.
.El
.Pp 
.Ss Discussion 
The following values are used to designate the PRF:
.br
.sp 
\fB * kCCPRFHmacAlgSHA1
.br
 * kCCPRFHmacAlgSHA224
.br
 * kCCPRFHmacAlgSHA256
.br
 * kCCPRFHmacAlgSHA384
.br
 * kCCPRFHmacAlgSHA512\fR
.br
.Pp
.Ss Result    
.Er kCCParamError 
- can result from bad values for the password, salt, and unwrapped key pointers as \
well as a bad value for the prf function.
.Ss Function  
.Nm CCCalibratePBKDF
.Ss Abstract  
Determine the number of PRF rounds to use for a specific delay on the current platform.
.Ss Parameters
.Bl -tag
.It algorithm       
Currently only PBKDF2 is available via kCCPBKDF2
.It passwordLen              
The length of the text password in bytes.
.It saltLen           
The length of the salt in bytes.
.It prf          
The Pseudo Random Algorithm to use for the derivation iterations.
.It derivedKeyLen      
The expected length of the derived key in bytes.
.It msec   
The targetted duration we want to achieve for a key derivation with these parameters.
.El
.Pp 
.Ss Result    
The number of iterations to use for the desired processing time.
.Sh EXAMPLE	
.nf
int main (int argc, const char * argv[]) {
	uint rounds;
	size_t	passwordLen = 10, saltLen = 10;
	char *password = "ThePasswrd";
	uint8_t salt[10] = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09 };
	CCPseudoRandomAlgorithm prf = kCCPRFHmacAlgSHA256;
	size_t derivedKeyLen = 16;
	uint8_t derivedKey[16];
	uint32_t msec = 10;
	int retval;
.sp
	rounds = CCCalibratePBKDF(kCCPBKDF2, strlen(password), saltLen, prf, derivedKeyLen, msec);
.sp
	retval =  CCKeyDerivationPBKDF(kCCPBKDF2, password, strlen(password), salt, saltLen,
                       prf, rounds, derivedKey, derivedKeyLen);
 	/* At this point the key is produced in "derivedKey" for "derivedKeyLen" bytes and could
	   be used as the key for AES encryption.
.sp
	   The "Salt" must be remembered somehow by the calling program as well as the rounds value 
	   and prf that was used.  These values, along with the original password will result in the
	   same 16 byte key being produced each time.
	*/
    	return 0;
}
.fi
.Sh HISTORY
These functions are available in OS X 10.7 and IOS 5.0 and later.
.Sh SEE ALSO
.Xr CCCryptor 3cc ,
.Xr CCHmac 3cc ,
.Xr CC_MD5 3cc ,
.Xr CC_SHA 3cc ,
.Xr CC_crypto 3cc ,
.Xr CCDigest 3cc
.Sh STANDARDS
.Bl -tag
.It AES:
Federal Information Processing Standard \s-1FIPS\s0 \s-1PUB\s0 197 (Advanced Encryption Standard),
.It DES:
Federal Information Processing Standard \s-1FIPS\s0 \s-1PUB\s0 46\-3 (Data Encryption Standard)
.It 3DES:
NIST Special Publication\s-1PUB\s0 800\-67 (Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher)
.El