OSX/libsecurity_transform/lib/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__ */