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_SYMKEYWRAP_H_ 25#define _CC_SYMKEYWRAP_H_ 26 27#include <sys/types.h> 28#include <sys/param.h> 29#include <stdint.h> 30 31#include <string.h> 32#ifdef KERNEL 33#include <machine/limits.h> 34#else 35#include <limits.h> 36#include <stdlib.h> 37#endif /* KERNEL */ 38#include <Availability.h> 39 40 41#ifdef __cplusplus 42extern "C" { 43#endif 44 45enum { 46 kCCWRAPAES = 1, 47}; 48 49extern const uint8_t * const CCrfc3394_iv __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); 50extern const size_t CCrfc3394_ivLen __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); 51 52typedef uint32_t CCWrappingAlgorithm; 53 54/*! 55 @function CCSymmetricKeyWrap 56 @abstract Wrap a symmetric key with a Key Encryption Key (KEK). 57 58 @param algorithm Currently only AES Keywrapping (rfc3394) is available 59 via kCCWRAPAES 60 @param iv The initialization value to be used. CCrfc3394_iv is 61 available as a constant for the standard IV to use. 62 @param ivLen The length of the initialization value to be used. 63 CCrfc3394_ivLen is available as a constant for the 64 standard IV to use. 65 @param kek The Key Encryption Key to be used to wrap the raw key. 66 @param kekLen The length of the KEK in bytes. 67 @param rawKey The raw key bytes to be wrapped. 68 @param rawKeyLen The length of the key in bytes. 69 @param wrappedKey The resulting wrapped key produced by the function. 70 The space for this must be provided by the caller. 71 @param wrappedKeyLen The length of the wrapped key in bytes. 72 73 @discussion The algorithm chosen is determined by the algorithm parameter 74 and the size of the key being wrapped (ie aes128 for 128 bit 75 keys). 76 77 @result kCCBufferTooSmall indicates insufficent space in the wrappedKey 78 buffer. 79 kCCParamError can result from bad values for the kek, rawKey, and 80 wrappedKey key pointers. 81 */ 82 83int 84CCSymmetricKeyWrap( CCWrappingAlgorithm algorithm, 85 const uint8_t *iv, const size_t ivLen, 86 const uint8_t *kek, size_t kekLen, 87 const uint8_t *rawKey, size_t rawKeyLen, 88 uint8_t *wrappedKey, size_t *wrappedKeyLen) 89 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 90 91/*! 92 @function CCSymmetricKeyUnwrap 93 @abstract Unwrap a symmetric key with a Key Encryption Key (KEK). 94 95 @param algorithm Currently only AES Keywrapping (rfc3394) is available 96 via kCCWRAPAES 97 @param iv The initialization value to be used. CCrfc3394_iv is 98 available as a constant for the standard IV to use. 99 @param ivLen The length of the initialization value to be used. 100 CCrfc3394_ivLen is available as a constant for the 101 standard IV to use. 102 @param kek The Key Encryption Key to be used to unwrap the raw key. 103 @param kekLen The length of the KEK in bytes. 104 @param wrappedKey The wrapped key bytes. 105 @param wrappedKeyLen The length of the wrapped key in bytes. 106 @param rawKey The resulting raw key bytes. The space for this must 107 be provided by the caller. 108 @param rawKeyLen The length of the raw key in bytes. 109 110 @discussion The algorithm chosen is determined by the algorithm parameter 111 and the size of the key being wrapped (ie aes128 for 128 bit 112 keys). 113 114 @result kCCBufferTooSmall indicates insufficent space in the rawKey buffer. 115 kCCParamError can result from bad values for the kek, rawKey, and 116 wrappedKey key pointers. 117 */ 118 119 120int 121CCSymmetricKeyUnwrap( CCWrappingAlgorithm algorithm, 122 const uint8_t *iv, const size_t ivLen, 123 const uint8_t *kek, size_t kekLen, 124 const uint8_t *wrappedKey, size_t wrappedKeyLen, 125 uint8_t *rawKey, size_t *rawKeyLen) 126 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 127 128/*! 129 @function CCSymmetricWrappedSize 130 @abstract Determine the buffer size required to hold a key wrapped with 131 CCAESKeyWrap(). 132 133 @param algorithm Currently only AES Keywrapping (rfc3394) is 134 available via kCCWRAPAES 135 @param rawKeyLen The length of the key in bytes. 136 @result The length of the resulting wrapped key. 137 */ 138 139size_t 140CCSymmetricWrappedSize( CCWrappingAlgorithm algorithm, size_t rawKeyLen) 141__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 142 143/*! 144 @function CCSymmetricUnwrappedSize 145 @abstract Determine the buffer size required to hold a key unwrapped with 146 CCAESKeyUnwrap(). 147 148 @param algorithm Currently only AES Keywrapping (rfc3394) is 149 available via kCCWRAPAES 150 @param wrappedKeyLen The length of the wrapped key in bytes. 151 @result The length of the resulting raw key. 152 */ 153 154size_t 155CCSymmetricUnwrappedSize( CCWrappingAlgorithm algorithm, size_t wrappedKeyLen) 156__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 157 158#ifdef __cplusplus 159} 160#endif 161 162#endif /* _CC_SYMKEYWRAP_H_ */ 163