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