Security-55471.14.18.tar.gz

[apple/security.git] / libsecurity_transform / lib / SecTransform.h

/*
 * Copyright © 2010 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__ */