+++ /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