CCSymmetricKeyWrap.3cc   [plain text]

.Dd January 20, 2011
.Dt CCSymmetricKeyWrap 3cc
.Os
.Sh NAME
.Nm CCSymmetricKeyWrap ,
.Nm CCSymmetricKeyUnwrap ,
.Nm CCSymmetricWrappedSize ,
.Nm CCSymmetricUnwrappedSize
.Nd Common Symmetric Keywrap Algorithm Interfaces
.Sh LIBRARY
These functions are found in libSystem.
.Sh SYNOPSIS
.In CommonCrypto/CommonSymmetricKeywrap.h
.Ft int
.Fn CCSymmetricKeyWrap "CCWrappingAlgorithm algorithm" "const uint8_t *iv" "const size_t ivLen" \
"const uint8_t *kek" "size_t kekLen" "const uint8_t *rawKey" "size_t rawKeyLen" \
"uint8_t  *wrappedKey" "size_t *wrappedKeyLen"
.Ft int
.Fn CCSymmetricKeyUnwrap "CCWrappingAlgorithm algorithm" "const uint8_t *iv" \
"const size_t ivLen" "const uint8_t *kek" "size_t kekLen" "const uint8_t  *wrappedKey" \
"size_t wrappedKeyLen" "uint8_t  *rawKey" "size_t *rawKeyLen"
.Ft size_t
.Fn CCSymmetricWrappedSize "CCWrappingAlgorithm algorithm" "size_t rawKeyLen"
.Ft size_t
.Fn CCSymmetricUnwrappedSize "CCWrappingAlgorithm algorithm" "size_t wrappedKeyLen"
.Sh DESCRIPTION
.Ss Function  
.Nm CCSymmetricKeyWrap
.Ss Abstract  
Wrap a symmetric key with a Key Encryption Key (KEK).  
.Ss Parameters
.Bl -tag
.It algorithm       
Currently only AES Keywrapping (rfc3394) is available via kCCWRAPAES
.It iv              
The initialization value to be used.  CCrfc3394_iv is available as a constant for \
the standard IV to use.
.It ivLen           
The length of the initialization value to be used.  CCrfc3394_ivLen is available as \
a constant for the standard IV to use.
.It kek             
The Key Encryption Key to be used to wrap the raw key.
.It kekLen          
The length of the KEK in bytes.
.It rawKey          
The raw key bytes to be wrapped.
.It rawKeyLen       
The length of the key in bytes.
.It wrappedKey      
The resulting wrapped key produced by the function.  The space for this must be \
provided by the caller.
.It wrappedKeyLen   
The length of the wrapped key in bytes.
.El
.Pp 
.Ss Discussion 
The algorithm chosen is determined by the algorithm parameter and the size of the \
key being wrapped (ie aes128 for 128 bit keys).
.Pp
.Ss Result    
.Er kCCBufferTooSmall 
- indicates insufficent space in the wrappedKey buffer. 
.Pp
.Er kCCParamError 
- can result from bad values for the kek, rawKey, and wrappedKey key pointers.
.Ss Function  
.Nm CCSymmetricKeyUnwrap
.Ss Abstract  
Unwrap a symmetric key with a Key Encryption Key (KEK).  
.Ss Parameters
.Bl -tag
.It algorithm       
Currently only AES Keywrapping (rfc3394) is available via kCCWRAPAES
.It iv              
The initialization value to be used.  CCrfc3394_iv is available as a constant for the \
standard IV to use.
.It ivLen           
The length of the initialization value to be used.  CCrfc3394_ivLen is available as a \
constant for the standard IV to use.
.It kekLen          
The length of the KEK in bytes.
.It wrappedKey      
The wrapped key bytes.
.It wrappedKeyLen   
The length of the wrapped key in bytes.
.It rawKey          
The resulting raw key bytes. The space for this must be provided by the caller.
.It rawKeyLen       
The length of the raw key in bytes.
.El
.Pp 
.Ss Discussion 
The algorithm chosen is determined by the algorithm parameter and the size of the key \
being wrapped (ie aes128 for 128 bit keys).
.Ss Result    
.Er kCCBufferTooSmall 
- indicates insufficent space in the rawKey buffer. 
.Pp
.Er kCCParamError 
- can result from bad values for the kek, rawKey, and wrappedKey key pointers.
.Pp
.br
.Ss Function  
.Nm CCSymmetricWrappedSize
.Ss Abstract  
Determine the buffer size required to hold a key wrapped with 
.Fn CCAESKeyWrap .  
.Ss Parameters
.Bl -tag
.It algorithm       
Currently only AES Keywrapping (rfc3394) is available via kCCWRAPAES
.It rawKeyLen       
The length of the key in bytes.
.El
.Ss Result    
The length of the resulting wrapped key.
.br
.Ss Function  
.Nm CCSymmetricUnwrappedSize
.Ss abstract  
Determine the buffer size required to hold a key unwrapped with 
.Fn CCAESKeyUnwrap . 
.Ss Parameters
.Bl -tag
.It algorithm       
Currently only AES Keywrapping (rfc3394) is available via kCCWRAPAES
.It wrappedKeyLen   
The length of the wrapped key in bytes.
.El
.Ss Result    
The length of the resulting raw key.
.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