libsecurity_transform/lib/SecEncryptTransform.h

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