--- /dev/null
+/*
+ * Copyright (c) 2010-2012 Apple Inc. All Rights Reserved.
+ *
+ * @APPLE_LICENSE_HEADER_START@
+ *
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this
+ * file.
+ *
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
+ *
+ * @APPLE_LICENSE_HEADER_END@
+ */
+
+#ifndef _SEC_TRANSFORM_H__
+#define _SEC_TRANSFORM_H__
+
+#include <CoreFoundation/CoreFoundation.h>
+
+CF_EXTERN_C_BEGIN
+
+
+/*!
+ @header
+
+ To better follow this header, you should understand the following
+ terms:
+
+ Transform A transform converts data from one form to another.
+ Digests, encryption and decryption are all examples
+ of transforms. Each transform performs a single
+ operation.
+ Transform
+ Group A transform group is a directed (typically) acyclic
+ graph of transforms. Results from a transform flow
+ to the next Transform in the graph, and so on until
+ the end of the graph is reached.
+
+ Attribute Transforms may have one or more attributes. These
+ attributes are parameters for the transforms and
+ may affect the operation of the transform. The value
+ of an attribute may be set with static data or from
+ the value of an attribute in another transform
+ by connecting the attributes using the
+ SecTransformConnectTransforms API.
+
+ External
+ Representation Transforms may be created programmatically or from
+ an external representation. External representations
+ may be created from existing transforms.
+
+ There are many types of transforms available. These are documented
+ in their own headers. The functions in this header are applicable
+ to all transforms.
+
+*/
+
+
+/*!
+ @constant kSecTransformErrorDomain
+ The domain for CFErrorRefs created by Transforms
+ */
+CF_EXPORT const CFStringRef kSecTransformErrorDomain;
+
+/*!
+ @constant kSecTransformPreviousErrorKey
+ If multiple errors occurred, the CFErrorRef that
+ is returned from a Transfo]rm API will have a userInfo
+ dictionary and that dictionary will have the previous
+ error keyed by the kSecTransformPreviousErrorKey.
+ */
+CF_EXPORT const CFStringRef kSecTransformPreviousErrorKey;
+
+/*!
+ @constant kSecTransformAbortOriginatorKey
+ The value of this key will be the transform that caused
+ the transform chain to abort.
+*/
+CF_EXPORT const CFStringRef kSecTransformAbortOriginatorKey;
+
+
+/**************** Transform Error Codes ****************/
+/*!
+ @enum Security Transform Error Codes
+ @discussion
+ @const kSecTransformErrorAttributeNotFound
+ The attribute was not found.
+
+ @const kSecTransformErrorInvalidOperation
+ An invalid operation was attempted.
+
+ @const kSecTransformErrorNotInitializedCorrectly
+ A required initialization is missing. It
+ is most likely a missing required attribute.
+
+ @const kSecTransformErrorMoreThanOneOutput
+ A transform has an internal routing error
+ that has caused multiple outputs instead
+ of a single discrete output. This will
+ occur if SecTransformExecute has already
+ been called.
+
+ @const kSecTransformErrorInvalidInputDictionary
+ A dictionary given to
+ SecTransformCreateFromExternalRepresentation has invalid data.
+
+ @const kSecTransformErrorInvalidAlgorithm
+ A transform that needs an algorithm as an attribute
+ i.e the Sign and Verify transforms, received an invalid
+ algorithm.
+
+ @const kSecTransformErrorInvalidLength
+ A transform that needs a length such as a digest
+ transform has been given an invalid length.
+
+ @const kSecTransformErrorInvalidType
+ An invalid type has been set on an attribute.
+
+ @const kSecTransformErrorInvalidInput
+ The input set on a transform is invalid. This can
+ occur if the data set for an attribute does not
+ meet certain requirements such as correct key
+ usage for signing data.
+
+ @const kSecTransformErrorNameAlreadyRegistered
+ A custom transform of a particular name has already
+ been registered.
+
+ @const kSecTransformErrorUnsupportedAttribute
+ An illegal action such as setting a read only
+ attribute has occurred.
+
+ @const kSecTransformOperationNotSupportedOnGroup
+ An illegal action on a group transform such as
+ trying to call SecTransformSetAttribute has occurred.
+
+ @const kSecTransformErrorMissingParameter
+ A transform is missing a required attribute.
+
+ @const kSecTransformErrorInvalidConnection
+ A SecTransformConnectTransforms was called with
+ transforms in different groups.
+
+ @const kSecTransformTransformIsExecuting
+ An illegal operation was called on a Transform
+ while it was executing. Please see the sequencing documentation
+ in the discussion area of the SecTransformExecute API
+
+ @const kSecTransformInvalidOverride
+ An illegal override was given to a custom transform
+
+ @const kSecTransformTransformIsNotRegistered
+ A custom transform was asked to be created but the transform
+ has not been registered.
+
+ @const kSecTransformErrorAbortInProgress
+ The abort attribute has been set and the transform is in the
+ process of shutting down
+
+ @const kSecTransformErrorAborted
+ The transform was aborted.
+
+ @const kSecTransformInvalidArgument
+ An invalid argument was given to a Transform API
+
+
+*/
+
+enum
+{
+ kSecTransformErrorAttributeNotFound = 1,
+ kSecTransformErrorInvalidOperation = 2,
+ kSecTransformErrorNotInitializedCorrectly = 3,
+ kSecTransformErrorMoreThanOneOutput = 4,
+ kSecTransformErrorInvalidInputDictionary = 5,
+ kSecTransformErrorInvalidAlgorithm = 6,
+ kSecTransformErrorInvalidLength = 7,
+ kSecTransformErrorInvalidType = 8,
+ kSecTransformErrorInvalidInput = 10,
+ kSecTransformErrorNameAlreadyRegistered = 11,
+ kSecTransformErrorUnsupportedAttribute = 12,
+ kSecTransformOperationNotSupportedOnGroup = 13,
+ kSecTransformErrorMissingParameter = 14,
+ kSecTransformErrorInvalidConnection = 15,
+ kSecTransformTransformIsExecuting = 16,
+ kSecTransformInvalidOverride = 17,
+ kSecTransformTransformIsNotRegistered = 18,
+ kSecTransformErrorAbortInProgress = 19,
+ kSecTransformErrorAborted = 20,
+ kSecTransformInvalidArgument = 21
+
+};
+
+typedef CFTypeRef SecTransformRef;
+typedef CFTypeRef SecGroupTransformRef;
+
+/*!
+ @function SecTransformGetTypeID
+ @abstract Return the CFTypeID for a SecTransform.
+ @result The CFTypeID
+*/
+
+CF_EXPORT CFTypeID SecTransformGetTypeID(void);
+
+/*!
+ @function SecGroupTransformGetTypeID
+ @abstract Return the CFTypeID for a SecTransformGroup.
+ @result The CFTypeID
+*/
+
+
+CF_EXPORT CFTypeID SecGroupTransformGetTypeID(void);
+
+
+/**************** Transform Attribute Names ****************/
+/*!
+ @constant kSecTransformInputAttributeName
+ The name of the input attribute.
+ */
+CF_EXPORT const CFStringRef kSecTransformInputAttributeName __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @constant kSecTransformOutputAttributeName
+ The name of the output attribute.
+ */
+CF_EXPORT const CFStringRef kSecTransformOutputAttributeName __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @constant kSecTransformDebugAttributeName
+ Set this attribute to a CFWriteStream.
+ This will signal the transform to write debugging
+ information to the stream.
+ If this attribute is set to kCFBooleanTrue then
+ the debugging data will be written out to
+ stderr.
+ */
+CF_EXPORT const CFStringRef kSecTransformDebugAttributeName __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @constant kSecTransformTransformName
+ The name of the transform.
+*/
+CF_EXPORT const CFStringRef kSecTransformTransformName __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @constant kSecTransformAbortAttributeName
+ The name of the abort attribute.
+ */
+CF_EXPORT const CFStringRef kSecTransformAbortAttributeName __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @function SecTransformCreateFromExternalRepresentation
+
+ @abstract Creates a transform instance from a CFDictionary of
+ parameters.
+
+ @param dictionary The dictionary of parameters.
+
+ @param error An optional pointer to a CFErrorRef. This value is
+ set if an error occurred. If not NULL the caller is
+ responsible for releasing the CFErrorRef.
+
+ @result A pointer to a SecTransformRef object. You
+ must release the object with CFRelease when you are done
+ with it. A NULL will be returned if an error occurred during
+ initialization, and if the error parameter
+ is non-null, it contains the specific error data.
+
+*/
+CF_EXPORT
+SecTransformRef SecTransformCreateFromExternalRepresentation(
+ CFDictionaryRef dictionary,
+ CFErrorRef *error)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @function SecTransformCopyExternalRepresentation
+
+ @abstract Create a CFDictionaryRef that contains enough
+ information to be able to recreate a transform.
+
+ @param transformRef The transformRef to be externalized.
+
+ @discussion This function returns a CFDictionaryRef that contains
+ sufficient information to be able to recreate this
+ transform. You can pass this CFDictionaryRef to
+ SecTransformCreateFromExternalRepresentation
+ to be able to recreate the transform. The dictionary
+ can also be written out to disk using the techniques
+ described here.
+
+http://developer.apple.com/mac/library/documentation/CoreFoundation/Conceptual/CFPropertyLists/Articles/Saving.html
+*/
+
+CF_EXPORT
+CFDictionaryRef SecTransformCopyExternalRepresentation(
+ SecTransformRef transformRef)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @function SecTransformCreateGroupTransform
+
+ @abstract Create a SecGroupTransformRef that acts as a
+ container for a set of connected transforms.
+
+ @result A reference to a SecGroupTransform.
+
+ @discussion A SecGroupTransformRef is a container for all of
+ the transforms that are in a directed graph.
+ A SecGroupTransformRef can be used with
+ SecTransformExecute, SecTransformExecuteAsync
+ and SecTransformCopyExternalRepresentation
+ APIs. While the intention is that a
+ SecGroupTransformRef willwork just like a S
+ SecTransformRef that is currently not the case.
+ Using a SecGroupTransformRef with the
+ SecTransformConnectTransforms,
+ SecTransformSetAttribute and
+ SecTransformGetAttribute is undefined.
+*/
+CF_EXPORT
+SecGroupTransformRef SecTransformCreateGroupTransform(void);
+
+/*!
+ @function SecTransformConnectTransforms
+
+ @abstract Pipe fitting for transforms.
+
+ @param sourceTransformRef
+ The transform that sends the data to the
+ destinationTransformRef.
+
+ @param sourceAttributeName
+ The name of the attribute in the sourceTransformRef that
+ supplies the data to the destinationTransformRef.
+ Any attribute of the transform may be used as a source.
+
+ @param destinationTransformRef
+ The transform that has one of its attributes
+ be set with the data from the sourceTransformRef
+ parameter.
+
+ @param destinationAttributeName
+ The name of the attribute within the
+ destinationTransformRef whose data is set with the
+ data from the sourceTransformRef sourceAttributeName
+ attribute. Any attribute of the transform may be set.
+
+
+ @param group In order to ensure referential integrity, transforms
+ are chained together into a directed graph and
+ placed into a group. Each transform that makes up the
+ graph must be placed into the same group. After
+ a SecTransformRef has been placed into a group by
+ calling the SecTransformConnectTransforms it may be
+ released as the group will retain the transform.
+ CFRelease the group after you execute
+ it, or when you determine you will never execute it.
+
+ In the example below, the output of trans1 is
+ set to be the input of trans2. The output of trans2
+ is set to be the input of trans3. Since the
+ same group was used for the connections, the three
+ transforms are in the same group.
+
+<pre>
+@textblock
+ SecGroupTransformRef group =SecTransformCreateGroupTransform();
+ CFErrorRef error = NULL;
+
+ SecTransformRef trans1; // previously created using a
+ // Transform construction API
+ // like SecEncryptTransformCreate
+
+ SecTransformRef trans2; // previously created using a
+ // Transform construction API
+ // like SecEncryptTransformCreate
+
+ SecTransformRef trans3; // previously created using a
+ // Transform construction API
+ // like SecEncryptTransformCreate
+
+
+ SecTransformConnectTransforms(trans1, kSecTransformOutputAttributeName,
+ trans2, kSecTransformInputAttributeName,
+ group, &error);
+
+ SecTransformConnectTransforms(trans2, kSecTransformOutputAttributeName,
+ trans3, kSecTransformInputAttributeName.
+ group, &error);
+ CFRelease(trans1);
+ CFRelease(trans2);
+ CFRelease(trans3);
+
+ CFDataRef = (CFDataRef)SecTransformExecute(group, &error, NULL, NULL);
+ CFRelease(group);
+@/textblock
+</pre>
+
+ @param error An optional pointer to a CFErrorRef. This value
+ is set if an error occurred. If not NULL, the caller
+ is responsible for releasing the CFErrorRef.
+
+ @result The value returned is SecGroupTransformRef parameter.
+ This will allow for chaining calls to
+ SecTransformConnectTransforms.
+
+ @discussion This function places transforms into a group by attaching
+ the value of an attribute of one transform to the
+ attribute of another transform. Typically the attribute
+ supplying the data is the kSecTransformAttrOutput
+ attribute but that is not a requirement. It can be used to
+ set an attribute like Salt with the output attribute of
+ a random number transform. This function returns an
+ error and the named attribute will not be changed if
+ SecTransformExecute had previously been called on the
+ transform.
+*/
+
+CF_EXPORT
+SecGroupTransformRef SecTransformConnectTransforms(SecTransformRef sourceTransformRef,
+ CFStringRef sourceAttributeName,
+ SecTransformRef destinationTransformRef,
+ CFStringRef destinationAttributeName,
+ SecGroupTransformRef group,
+ CFErrorRef *error)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @function SecTransformSetAttribute
+
+ @abstract Set a static value as the value of an attribute in a
+ transform. This is useful for things like iteration
+ counts and other non-changing values.
+
+ @param transformRef The transform whose attribute is to be set.
+
+ @param key The name of the attribute to be set.
+
+ @param value The static value to set for the named attribute.
+
+ @param error An optional pointer to a CFErrorRef. This value
+ is set if an error occurred. If not NULL the caller
+ is responsible for releasing the CFErrorRef.
+
+ @result Returns true if the call succeeded. If an error occurred,
+ the error parameter has more information
+ about the failure case.
+
+ @discussion This API allows for setting static data into an
+ attribute for a transform. This is in contrast to
+ the SecTransformConnectTransforms function which sets derived
+ data. This function will return an error and the
+ named attribute will not be changed if SecTransformExecute
+ has been called on the transform.
+*/
+
+CF_EXPORT
+Boolean SecTransformSetAttribute(SecTransformRef transformRef,
+ CFStringRef key,
+ CFTypeRef value,
+ CFErrorRef *error)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @function SecTransformGetAttribute
+
+ @abstract Get the current value of a transform attribute.
+
+ @param transformRef The transform whose attribute value will be retrieved.
+
+ @param key The name of the attribute to retrieve.
+
+ @result The value of an attribute. If this attribute
+ is being set as the output of another transform
+ and SecTransformExecute has not been called on the
+ transform or if the attribute does not exists
+ then NULL will be returned.
+
+ @discussion This may be called after SecTransformExecute.
+*/
+
+CF_EXPORT
+CFTypeRef SecTransformGetAttribute(SecTransformRef transformRef,
+ CFStringRef key)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @function SecTransformFindByName
+
+ @abstract Finds a member of a transform group by its name.
+
+ @param transform The transform group to be searched.
+
+ @param name The name of the transform to be found.
+
+ @discussion When a transform instance is created it will be given a
+ unique name. This name can be used to find that instance
+ in a group. While it is possible to change this unique
+ name using the SecTransformSetAttribute API, developers
+ should not do so. This allows
+ SecTransformFindTransformByName to work correctly.
+
+ @result The transform group member, or NULL if the member
+ was not found.
+*/
+
+CF_EXPORT
+SecTransformRef SecTransformFindByName(SecGroupTransformRef transform,
+ CFStringRef name)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @function SecTransformExecute
+
+ @abstract Executes a Transform or transform group synchronously.
+
+ @param transformRef The transform to execute.
+
+ @param errorRef An optional pointer to a CFErrorRef. This value
+ will be set if an error occurred during
+ initialization or execution of the transform or group.
+ If not NULL the caller will be responsible for releasing
+ the returned CFErrorRef.
+
+ @result This is the result of the transform. The specific value
+ is determined by the transform being executed.
+
+ @discussion There are two phases that occur when executing a
+ transform. The first phase checks to see if tthe ranforms
+ have all of their required attributes set.
+ If a GroupTransform is being executed, then a required
+ attribute for a transform is valid if it is connected
+ to another attribute that supplies the required value.
+ If any of the required attributes are not set or connected
+ then SecTransformExecute will not run the transform but will
+ return NULL and the apporiate error is placed in the
+ error parameter if it is not NULL.
+
+ The second phase is the actual execution of the transform.
+ SecTransformExecute executes the transform or
+ GroupTransform and when all of the processing is completed
+ it returns the result. If an error occurs during
+ execution, then all processing will stop and NULL will be
+ returned and the appropriate error will be placed in the
+ error parameter if it is not NULL.
+*/
+
+CF_EXPORT CF_RETURNS_RETAINED
+CFTypeRef SecTransformExecute(SecTransformRef transformRef, CFErrorRef* errorRef)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA) CF_RETURNS_RETAINED;
+
+/*!
+ @typedef SecMessageBlock
+
+ @abstract A SecMessageBlock is used by a transform instance to
+ deliver messages during asynchronous operations.
+
+ @param message A CFType containing the message. This is where
+ either intermediate or final results are returned.
+
+ @param error If an error occurred, this will contain a CFErrorRef,
+ otherwise this will be NULL. If not NULL the caller
+ is responsible for releasing the CFErrorRef.
+
+ @param isFinal If set the message returned is the final result
+ otherwise it is an intermediate result.
+*/
+
+typedef void (^SecMessageBlock)(CFTypeRef message, CFErrorRef error,
+ Boolean isFinal);
+
+/*!
+ @function SecTransformExecuteAsync
+
+ @abstract Executes Transform or transform group asynchronously.
+
+
+ @param transformRef The transform to execute.
+
+ @param deliveryQueue
+ A dispatch queue on which to deliver the results of
+ this transform.
+
+ @param deliveryBlock
+ A SecMessageBlock to asynchronously receive the
+ results of the transform.
+
+ @discussion SecTransformExecuteAsync works just like the
+ SecTransformExecute API except that it
+ returns results to the deliveryBlock. There
+ may be multple results depending on the transform.
+ The block knows that the processing is complete
+ when the isFinal parameter is set to true. If an
+ error occurs the block's error parameter is
+ set and the isFinal parameter will be set to
+ true.
+*/
+
+CF_EXPORT
+void SecTransformExecuteAsync(SecTransformRef transformRef,
+ dispatch_queue_t deliveryQueue,
+ SecMessageBlock deliveryBlock)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+
+CF_EXTERN_C_END
+
+#endif /* _SEC_TRANSFORM_H__ */
projects / apple / security.git / blobdiff