SecEncryptTransform.h
1 /* 2 * Copyright (c) 2010-2011,2013 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 /*! 25 @header SecEncryptTransform 26 27 This file defines a SecTransform that will do both asynchronous and synchronous 28 encryption. 29 30 The key that is supplied to the SecTransform determines the type of encryption 31 to be used. 32 33 */ 34 #if !defined(__SEC_ENCRYPT_TRANSFORM__) 35 #define __SEC_ENCRYPT_TRANSFORM__ 1 36 37 #include <CoreFoundation/CoreFoundation.h> 38 #include <Security/SecKey.h> 39 #include <Security/SecTransform.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 CF_ASSUME_NONNULL_BEGIN 46 CF_IMPLICIT_BRIDGING_ENABLED 47 48 /*! @abstract Indicates that no padding will be used when encrypting or decrypting. */ 49 extern const CFStringRef kSecPaddingNoneKey; 50 /*! Indicates that PKCS1 padding will be used when encrypting or decrypting. */ 51 extern const CFStringRef kSecPaddingPKCS1Key; 52 /*! Indicates that PKCS5 padding will be used when encrypting or decrypting. */ 53 extern const CFStringRef kSecPaddingPKCS5Key; 54 /*! Indicates that PKCS7 padding will be used when encrypting or decrypting. */ 55 extern const CFStringRef kSecPaddingPKCS7Key; 56 /*! Indicates that PKCS7 padding will be used when encrypting or decrypting. */ 57 extern const CFStringRef kSecPaddingOAEPKey 58 __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_NA); 59 /*! Indicates that no mode will be used when encrypting or decrypting. */ 60 extern const CFStringRef kSecModeNoneKey; 61 /*! Indicates that ECB mode will be used when encrypting or decrypting. */ 62 extern const CFStringRef kSecModeECBKey; 63 /*! Indicates that CBC mode will be used when encrypting or decrypting. */ 64 extern const CFStringRef kSecModeCBCKey; 65 /*! Indicates that CFB mode will be used when encrypting or decrypting. */ 66 extern const CFStringRef kSecModeCFBKey; 67 /*! Indicates that OFB mode will be used when encrypting or decrypting. */ 68 extern const CFStringRef kSecModeOFBKey; 69 70 /*! 71 @abstract 72 This attribute holds the encryption key for the transform. (ReadOnly) 73 */ 74 extern const CFStringRef kSecEncryptKey; 75 76 /*! 77 @abstract 78 Key for setting padding. 79 @discussion 80 This key is optional. If you do not supply a value for this key, 81 an appropriate value will be supplied for you. 82 */ 83 extern const CFStringRef kSecPaddingKey; 84 85 /*! 86 @abstract 87 Key for setting an initialization vector. 88 @discussion 89 This key is optional. If you do not supply a 90 value for this key, an appropriate value will be supplied for you. 91 */ 92 extern const CFStringRef kSecIVKey; 93 94 /*! 95 @abstract 96 Specifies the encryption mode. 97 @discussion 98 This key is optional. If you do not supply this key, 99 an appropriate value will be supplied for you. 100 */ 101 extern const CFStringRef kSecEncryptionMode; 102 103 /*! 104 @abstract 105 Specifies the OAEP message length. 106 @discussion 107 This should be set to a CFNumberRef when the padding is set to OAEP, 108 and a specific messages size is desired. If unset the minimum padding 109 will be added. It is ignored when the padding mode is not OAEP. 110 */ 111 extern const CFStringRef kSecOAEPMessageLengthAttributeName 112 __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_NA); 113 /*! 114 @abstract 115 Specifies the OAEP encoding paramaters 116 @discussion 117 This should be set to a CFDataRef when the padding is set to OAEP. 118 If unset a zero length CFDataRef is used. It is ignored by non 119 OAEP padding modes. 120 */ 121 extern const CFStringRef kSecOAEPEncodingParametersAttributeName 122 __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_NA); 123 /*! 124 @abstract 125 Specifies the OAEP MGF1 digest algorithm. 126 @discussion 127 This should be set to a digest algorithm when the padding is set to OAEP. 128 If unset SHA1 is used. It is ifnored by non OAEP padding modes. 129 */ 130 extern const CFStringRef kSecOAEPMGF1DigestAlgorithmAttributeName 131 __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_NA); 132 133 /*! 134 @function SecEncryptTransformCreate 135 @abstract Creates an encryption SecTransform object. 136 @param keyRef The key for the encryption operation 137 @param error A pointer to a CFErrorRef. This pointer will be set 138 if an error occurred. This value may be NULL if you 139 do not want an error returned. 140 @result A pointer to a SecTransformRef object. This object must 141 be released with CFRelease when you are done with 142 it. This function will return NULL if an error 143 occurred. 144 @discussion This function creates a transform which encrypts data. 145 */ 146 147 SecTransformRef SecEncryptTransformCreate(SecKeyRef keyRef, 148 CFErrorRef* error) 149 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA); 150 151 /*! 152 @function SecDecryptTransformCreate 153 @abstract Creates an encryption SecTransform object. 154 @param keyRef The key for the operation 155 @param error A pointer to a CFErrorRef. This pointer will be set 156 if an error occurred. This value may be NULL if you 157 do not want an error returned. 158 @result A pointer to a SecTransformRef object. This object must 159 be released with CFRelease when you are done with 160 it. This function will return NULL if an error 161 occurred. 162 @discussion This function creates a transform which encrypts data. 163 */ 164 165 SecTransformRef SecDecryptTransformCreate(SecKeyRef keyRef, 166 CFErrorRef* error) 167 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA); 168 169 /*! 170 @function SecDecryptTransformGetTypeID 171 @abstract Returns the CFTypeID for a decrypt transform. 172 @return the CFTypeID 173 */ 174 175 CFTypeID SecDecryptTransformGetTypeID(void) 176 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA); 177 178 /*! 179 @function SecEncryptTransformGetTypeID 180 @abstract Returns the CFTypeID for a decrypt transform. 181 @return the CFTypeID 182 */ 183 184 CFTypeID SecEncryptTransformGetTypeID(void) 185 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA); 186 187 CF_IMPLICIT_BRIDGING_DISABLED 188 CF_ASSUME_NONNULL_END 189 190 #ifdef __cplusplus 191 }; 192 #endif 193 194 #endif /* ! __SEC_ENCRYPT_TRANSFORM__ */