+/*
+ * Copyright (c) 2010-2011,2014 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_CUSTOM_TRANSFORM_H__
+#define _SEC_CUSTOM_TRANSFORM_H__
+
+#include <Security/SecTransform.h>
+
+// Blocks are required for custom transforms
+#ifdef __BLOCKS__
+
+CF_EXTERN_C_BEGIN
+
+/*!
+ @header
+
+ Custom transforms are an API that provides the ability to easily create new
+ transforms. The essential functions of a transform are created in a
+ collection of blocks. These blocks override the standard behavior of the
+ base transform; a custom transform with no overrides is a null transform
+ that merely passes through a data flow.
+
+ A new transform type is created when calling the SecTransformRegister
+ function which registers the name of the new transform and sets up its
+ overrides. The SecTransformCreate function creates a new instance of a
+ registered custom transform.
+
+ A sample custom transform is provided here, along with a basic test program.
+ This transform creates a Caesar cipher transform, one that simply adds a
+ value to every byte of the plaintext.
+
+ -----cut here-----
+<pre>
+@textblock
+//
+// CaesarXform.c
+//
+// Copyright (c) 2010-2011,2014 Apple Inc. All Rights Reserved.
+//
+//
+
+#include <Security/SecCustomTransform.h>
+#include <Security/SecTransform.h>
+
+// This is the unique name for the custom transform type.
+const CFStringRef kCaesarCipher = CFSTR("com.apple.caesarcipher");
+
+// Name of the "key" attribute.
+const CFStringRef kKeyAttributeName = CFSTR("key");
+
+// Shortcut to return a CFError.
+CFErrorRef invalid_input_error(void)
+{
+ return CFErrorCreate(kCFAllocatorDefault, kSecTransformErrorDomain,
+ kSecTransformErrorInvalidInput, NULL);
+}
+
+// =========================================================================
+// Implementation of the Transform instance
+// =========================================================================
+static SecTransformInstanceBlock CaesarImplementation(CFStringRef name,
+ SecTransformRef newTransform,
+ SecTransformImplementationRef ref)
+{
+
+ SecTransformInstanceBlock instanceBlock =
+ ^{
+ CFErrorRef result = NULL;
+
+ // Every time a new instance of this custom transform class is
+ // created, this block is called. This behavior means that any
+ // block variables created in this block act like instance
+ // variables for the new custom transform instance.
+ __block int _key = 0;
+
+ result = SecTransformSetAttributeAction(ref,
+ kSecTransformActionAttributeNotification,
+ kKeyAttributeName,
+ ^(SecTransformAttributeRef name, CFTypeRef d)
+ {
+ CFNumberGetValue((CFNumberRef)d, kCFNumberIntType, &_key);
+ return d;
+ });
+
+ if (result)
+ return result;
+
+ // Create an override that will be called to process the input
+ // data into the output data
+ result = SecTransformSetDataAction(ref,
+ kSecTransformActionProcessData,
+ ^(CFTypeRef d)
+ {
+ if (NULL == d) // End of stream?
+ return (CFTypeRef) NULL; // Just return a null.
+
+ char *dataPtr = (char *)CFDataGetBytePtr((CFDataRef)d);
+
+ CFIndex dataLength = CFDataGetLength((CFDataRef)d);
+
+ // Do the processing in memory. There are better ways to do
+ // this but for showing how custom transforms work this is fine.
+ char *buffer = (char *)malloc(dataLength);
+ if (NULL == buffer)
+ return (CFTypeRef) invalid_input_error(); // Return a CFErrorRef
+
+ // Do the work of the caesar cipher (Rot(n))
+
+ CFIndex i;
+ for (i = 0; i < dataLength; i++)
+ buffer[i] = dataPtr[i] + _key;
+
+ return (CFTypeRef)CFDataCreateWithBytesNoCopy(NULL, (UInt8 *)buffer,
+ dataLength, kCFAllocatorMalloc);
+ });
+ return result;
+ };
+
+ return Block_copy(instanceBlock);
+}
+
+SecTransformRef CaesarTransformCreate(CFIndex k, CFErrorRef* error)
+{
+ SecTransformRef caesarCipher;
+ __block Boolean result = 1;
+ static dispatch_once_t registeredOK = 0;
+
+ dispatch_once(®isteredOK,
+ ^{
+ result = SecTransformRegister(kCaesarCipher, &CaesarImplementation, error);
+ });
+
+ if (!result)
+ return NULL;
+
+ caesarCipher = SecTransformCreate(kCaesarCipher, error);
+ if (NULL != caesarCipher)
+ {
+ CFNumberRef keyNumber = CFNumberCreate(kCFAllocatorDefault,
+ kCFNumberIntType, &k);
+ SecTransformSetAttribute(caesarCipher, kKeyAttributeName,
+ keyNumber, error);
+ CFRelease(keyNumber);
+ }
+
+ return caesarCipher;
+}
+
+
+// The second function shows how to use custom transform defined in the
+// previous function
+
+// =========================================================================
+// Use a custom ROT-N (caesar cipher) transform
+// =========================================================================
+CFDataRef TestCaesar(CFDataRef theData, int rotNumber)
+{
+ CFDataRef result = NULL;
+ CFErrorRef error = NULL;
+
+ if (NULL == theData)
+ return result;
+
+ // Create an instance of the custom transform
+ SecTransformRef caesarCipher = CaesarTransformCreate(rotNumber, &error);
+ if (NULL == caesarCipher || NULL != error)
+ return result;
+
+ // Set the data to be transformed as the input to the custom transform
+ SecTransformSetAttribute(caesarCipher,
+ kSecTransformInputAttributeName, theData, &error);
+
+ if (NULL != error)
+ {
+ CFRelease(caesarCipher);
+ return result;
+ }
+
+ // Execute the transform synchronously
+ result = (CFDataRef)SecTransformExecute(caesarCipher, &error);
+ CFRelease(caesarCipher);
+
+ return result;
+}
+
+#include <CoreFoundation/CoreFoundation.h>
+
+int main (int argc, const char *argv[])
+{
+ CFDataRef testData, testResult;
+ UInt8 bytes[26];
+ int i;
+
+ // Create some test data, a string from A-Z
+
+ for (i = 0; i < sizeof(bytes); i++)
+ bytes[i] = 'A' + i;
+
+ testData = CFDataCreate(kCFAllocatorDefault, bytes, sizeof(bytes));
+ CFRetain(testData);
+ CFShow(testData);
+
+ // Encrypt the test data
+ testResult = TestCaesar(testData, 3);
+
+ CFShow(testResult);
+ CFRelease(testData);
+ CFRelease(testResult);
+ return 0;
+}
+@/textblock
+</pre>
+
+*/
+
+/**************** Custom Transform attribute metadata ****************/
+
+/*!
+ @enum Custom Transform Attribute Metadata
+ @discussion
+ Within a transform, each of its attributes is a collection of
+ "metadata attributes", of which name and current value are two. The
+ value is directly visible from outside; the other metadata
+ attributes direct the behavior of the transform and
+ its function within its group. Each attribute may be tailored by setting its metadata.
+
+ @const kSecTransformMetaAttributeValue
+ The actual value of the attribute. The attribute value has a default
+ value of NULL.
+
+ @const kSecTransformMetaAttributeName
+ The name of the attribute. Attribute name is read only and may
+ not be used with the SecTransformSetAttributeBlock block.
+
+ @const kSecTransformMetaAttributeRef
+ A direct reference to an attribute's value. This reference allows
+ for direct access to an attribute without having to look up the
+ attribute by name. If a transform commonly uses an attribute, using
+ a reference speeds up the use of that attribute. Attribute
+ references are not visible or valid from outside of the particular
+ transform instance.
+
+ @const kSecTransformMetaAttributeRequired
+ Specifies if an attribute must have a non NULL value set or have an
+ incoming connection before the transform starts to execute. This
+ metadata has a default value of true for the input attribute, but
+ false for all other attributes.
+
+ @const kSecTransformMetaAttributeRequiresOutboundConnection
+ Specifies if an attribute must have an outbound connection. This
+ metadata has a default value of true for the output attribute but is
+ false for all other attributes.
+
+ @const kSecTransformMetaAttributeDeferred
+ Determines if the AttributeSetNotification notification or the
+ ProcessData blocks are deferred until SecExecuteTransform is called.
+ This metadata value has a default value of true for the input
+ attribute but is false for all other attributes.
+
+ @const kSecTransformMetaAttributeStream
+ Specifies if the attribute should expect a series of values ending
+ with a NULL to specify the end of the data stream. This metadata has
+ a default value of true for the input and output attributes, but is
+ false for all other attributes.
+
+ @const kSecTransformMetaAttributeCanCycle
+ A Transform group is a directed graph which is typically acyclic.
+ Some transforms need to work with cycles. For example, a transform
+ that emits a header and trailer around the data of another transform
+ must create a cycle. If this metadata set to true, no error is
+ returned if a cycle is detected for this attribute.
+
+ @const kSecTransformMetaAttributeExternalize
+ Specifies if this attribute should be written out when creating the
+ external representation of this transform. This metadata has a
+ default value of true.
+
+ @const kSecTransformMetaAttributeHasOutboundConnections
+ This metadata value is true if the attribute has an outbound
+ connection. This metadata is read only.
+
+ @const kSecTransformMetaAttributeHasInboundConnection
+ This metadata value is true if the attribute has an inbound
+ connection. This metadata is read only.
+*/
+
+enum
+{
+ kSecTransformMetaAttributeValue,
+ kSecTransformMetaAttributeName,
+ kSecTransformMetaAttributeRef,
+ kSecTransformMetaAttributeRequired,
+ kSecTransformMetaAttributeRequiresOutboundConnection,
+ kSecTransformMetaAttributeDeferred,
+ kSecTransformMetaAttributeStream,
+ kSecTransformMetaAttributeCanCycle,
+ kSecTransformMetaAttributeExternalize,
+ kSecTransformMetaAttributeHasOutboundConnections,
+ kSecTransformMetaAttributeHasInboundConnection
+};
+
+typedef CFIndex SecTransformMetaAttributeType;
+
+/*!
+ @typedef SecTransformAttributeRef
+
+ @abstract A direct reference to an attribute. Using an attribute
+ reference speeds up using an attribute's value by removing
+ the need to look
+ it up by name.
+*/
+typedef CFTypeRef SecTransformAttributeRef;
+
+
+/*!
+ @typedef SecTransformStringOrAttributeRef
+
+ @abstract This type signifies that either a CFStringRef or
+ a SecTransformAttributeRef may be used.
+*/
+typedef CFTypeRef SecTransformStringOrAttributeRef;
+
+
+/*!
+ @typedef SecTransformActionBlock
+
+ @abstract A block that overrides the default behavior of a
+ custom transform.
+
+ @result If this block is used to overide the
+ kSecTransformActionExternalizeExtraData action then the
+ block should return a CFDictinaryRef of the custom
+ items to be exported. For all of other actions the
+ block should return NULL. If an error occurs for
+ any action, the block should return a CFErrorRef.
+
+ @discussion A SecTransformTransformActionBlock block is used to
+ override
+ the default behavior of a custom transform. This block is
+ associated with the SecTransformOverrideTransformAction
+ block.
+
+ The behaviors that can be overridden are:
+
+ kSecTransformActionCanExecute
+ Determine if the transform has all of the data
+ needed to run.
+
+ kSecTransformActionStartingExecution
+ Called just before running ProcessData.
+
+ kSecTransformActionFinalize
+ Called just before deleting the custom transform.
+
+ kSecTransformActionExternalizeExtraData
+ Called to allow for writing out custom data
+ to be exported.
+
+ Example:
+<pre>
+@textblock
+ SecTransformImplementationRef ref;
+ CFErrorRef error = NULL;
+
+ error = SecTransformSetTransformAction(ref, kSecTransformActionStartingExecution,
+ ^{
+ // This is where the work to initialize any data needed
+ // before running
+ CFErrorRef result = DoMyInitialization();
+ return result;
+ });
+
+ SecTransformTransformActionBlock actionBlock =
+ ^{
+ // This is where the work to clean up any existing data
+ // before running
+ CFErrorRef result = DoMyFinalization();
+ return result;
+ };
+
+ error = SecTransformSetTransformAction(ref, kSecTransformActionFinalize,
+ actionBlock);
+@/textblock
+</pre>
+*/
+typedef CFTypeRef (^SecTransformActionBlock)(void);
+
+/*!
+ @typedef SecTransformAttributeActionBlock
+
+ @abstract A block used to override the default attribute handling
+ for when an attribute is set.
+
+ @param attribute The attribute whose default is being overridden or NULL
+ if this is a generic notification override
+
+ @param value Proposed new value for the attribute.
+
+ @result The new value of the attribute if successful. If an
+ error occurred then a CFErrorRef is returned. If a transform
+ needs to have a CFErrorRef as the value of an attribute,
+ then the CFErrorRef needs to be placed into a container such
+ as a CFArrayRef, CFDictionaryRef etc.
+
+ @discussion See the example program in this header for more details.
+
+*/
+typedef CFTypeRef (^SecTransformAttributeActionBlock)(
+ SecTransformAttributeRef attribute,
+ CFTypeRef value);
+
+/*!
+ @typedef SecTransformDataBlock
+
+ @abstract A block used to override the default data handling
+ for a transform.
+
+ @param data The data to be processed. When this block is used
+ to to implement the kSecTransformActionProcessData action,
+ the data is the input data that is to be processed into the
+ output data. When this block is used to implement the
+ kSecTransformActionInternalizeExtraData action, the data is
+ a CFDictionaryRef that contains the data that needs to be
+ imported.
+
+ @result When this block is used to implment the
+ kSecTransformActionProcessData action, the value returned
+ is to be the data that will be passed to the output
+ attribute. If an error occured while processing the input
+ data then the block should return a CFErrorRef.
+
+ When this block is used to implement the
+ kSecTransformActionInternalizeExtraData action then this block
+ should return NULL or a CFErrorRef if an error occurred.
+
+ @discussion See the example program for more details.
+*/
+typedef CFTypeRef (^SecTransformDataBlock)(CFTypeRef data);
+
+/*!
+ @typedef SecTransformInstanceBlock
+
+ @abstract This is the block that is returned from an
+ implementation of a CreateTransform function.
+
+ @result A CFErrorRef if an error occurred or NULL.
+
+ @discussion The instance block that is returned from the
+ developers CreateTransform function, defines
+ the behavior of a custom attribute. Please
+ see the example at the head of this file.
+
+*/
+typedef CFErrorRef (^SecTransformInstanceBlock)(void);
+
+/*!
+ @typedef SecTransformImplementationRef
+
+ @abstract The SecTransformImplementationRef is a pointer to a block
+ that implements an instance of a transform.
+
+*/
+typedef const struct OpaqueSecTransformImplementation* SecTransformImplementationRef;
+
+/*!
+ @function SecTransformSetAttributeAction
+
+ @abstract Be notified when a attribute is set. The supplied block is
+ called when the attribute is set. This can be done for a
+ specific named attribute or all attributes.
+
+ @param ref A SecTransformImplementationRef that is bound to an instance
+ of a custom transform.
+
+ @param action The behavior to be set. This can be one of the following
+ actions:
+
+ kSecTransformActionAttributeNotification - add a block that
+ is called when an attribute is set. If the name is NULL,
+ then the supplied block is called for all set attributes
+ except for ones that have a specific block as a handler.
+
+ For example, if there is a handler for the attribute "foo"
+ and for all attributes, the "foo" handler is called when the
+ "foo" attribute is set, but all other attribute sets will
+ call the NULL handler.
+
+ The kSecTransformActionProcessData action is a special case
+ of a SecTransformSetAttributeAction action. If this is
+ called on the input attribute then it will overwrite any
+ kSecTransformActionProcessData that was set.
+
+ kSecTransformActionAttributeValidation Add a block that is
+ called to validate the input to an attribute.
+
+ @param attribute
+ The name of the attribute that will be handled. An attribute
+ reference may also be given here. A NULL name indicates that
+ the supplied action is for all attributes.
+
+ @param newAction
+ A SecTransformAttributeActionBlock which implements the
+ behavior.
+
+ @result A CFErrorRef if an error occured NULL otherwise.
+
+ @discussion This function may be called multiple times for either a
+ named attribute or for all attributes when the attribute
+ parameter is NULL. Each time the API is called it overwrites
+ what was there previously.
+
+*/
+CF_EXPORT
+CFErrorRef SecTransformSetAttributeAction(SecTransformImplementationRef ref,
+ CFStringRef action,
+ SecTransformStringOrAttributeRef attribute,
+ SecTransformAttributeActionBlock newAction);
+/*!
+ @function SecTransformSetDataAction
+
+ @abstract Change the way a custom transform will do data processing.
+ When the action parameter is kSecTransformActionProcessData
+ The newAction block will change the way that input data is
+ processed to become the output data. When the action
+ parameter is kSecTransformActionInternalizeExtraData it will
+ change the way a custom transform reads in data to be
+ imported into the transform.
+
+ @param ref A SecTransformImplementationRef that is bound to an instance
+ of a custom transform.
+
+ @param action The action being overridden. This value should be one of the
+ following:
+ kSecTransformActionProcessData
+ Change the way that input data is processed into the
+ output data. The default behavior is to simply copy
+ the input data to the output attribute.
+
+ The kSecTransformActionProcessData action is really
+ a special case of a SecTransformSetAttributeAction
+ action. If you call this method with
+ kSecTransformActionProcessData it would overwrite
+ any kSecTransformActionAttributeNotification action
+ that was set proviously
+
+ kSecTransformActionInternalizeExtraData
+ Change the way that custom externalized data is
+ imported into the transform. The default behavior
+ is to do nothing.
+
+ @param newAction
+ A SecTransformDataBlock which implements the behavior.
+
+ If the action parameter is kSecTransformActionProcessData then
+ this block will be called to process the input data into the
+ output data.
+
+ if the action parameter is kSecTransformActionInternalizeExtraData then
+ this block will called to input custom data into the transform.
+
+ @result A CFErrorRef is an error occured NULL otherwise.
+
+ @discussion This API may be called multiple times. Each time the API is called
+ it overwrites what was there previously.
+
+*/
+CF_EXPORT
+CFErrorRef SecTransformSetDataAction(SecTransformImplementationRef ref,
+ CFStringRef action,
+ SecTransformDataBlock newAction);
+
+/*
+ @function SecTransformSetTransformAction
+
+ @abstract Change the way that transform deals with transform lifecycle
+ behaviors.
+
+ @param ref A SecTransformImplementationRef that is bound to an instance
+ of a custom transform. It provides the neccessary context
+ for making the call to modify a custom transform.
+
+ @param action Defines what behavior will be changed. The possible values
+ are:
+
+ kSecTransformActionCanExecute
+ A CanExecute block is called before the transform
+ starts to execute. Returning NULL indicates that the
+ transform has all necessary parameters set up to be
+ able to execute. If there is a condition that
+ prevents this transform from executing, return a
+ CFError. The default behavior is to return NULL.
+
+ kSecTransformActionStartingExecution
+ A StartingExecution block is called as a transform
+ starts execution but before any input is delivered.
+ Transform-specific initialization can be performed
+ in this block.
+
+ kSecTransformActionFinalize
+ A Finalize block is called before a transform is
+ released. Any final cleanup can be performed in this
+ block.
+
+ kSecTransformActionExternalizeExtraData
+ An ExternalizeExtraData block is called before a
+ transform is externalized. If there is any extra
+ work that the transform needs to do (e.g. copy data
+ from local variables to attributes) it can be
+ performed in this block.
+
+ @param newAction
+ A SecTransformTransformActionBlock which implements the behavior.
+
+ @result A CFErrorRef if an error occured NULL otherwise.
+
+*/
+CF_EXPORT
+CFErrorRef SecTransformSetTransformAction(SecTransformImplementationRef ref,
+ CFStringRef action,
+ SecTransformActionBlock newAction);
+
+/*!
+ @function SecTranformCustomGetAttribute
+
+ @abstract Allow a custom transform to get an attribute value
+
+ @param ref A SecTransformImplementationRef that is bound to an instance
+ of a custom transform.
+
+ @param attribute
+ The name or the attribute handle of the attribute whose
+ value is to be retrieved.
+
+ @param type The type of data to be retrieved for the attribute. See the
+ discussion on SecTransformMetaAttributeType for details.
+
+ @result The value of the attribute.
+
+ */
+CF_EXPORT
+CFTypeRef SecTranformCustomGetAttribute(SecTransformImplementationRef ref,
+ SecTransformStringOrAttributeRef attribute,
+ SecTransformMetaAttributeType type) AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_8;
+
+/*!
+ @function SecTransformCustomGetAttribute
+
+ @abstract Allow a custom transform to get an attribute value
+
+ @param ref A SecTransformImplementationRef that is bound to an instance
+ of a custom transform.
+
+ @param attribute
+ The name or the attribute handle of the attribute whose
+ value is to be retrieved.
+
+ @param type The type of data to be retrieved for the attribute. See the
+ discussion on SecTransformMetaAttributeType for details.
+
+ @result The value of the attribute.
+
+ */
+CF_EXPORT
+CFTypeRef SecTransformCustomGetAttribute(SecTransformImplementationRef ref,
+ SecTransformStringOrAttributeRef attribute,
+ SecTransformMetaAttributeType type) __asm__("_SecTranformCustomGetAttribute");
+
+/*!
+ @function SecTransformCustomSetAttribute
+
+ @abstract Allow a custom transform to set an attribute value
+
+ @param ref A SecTransformImplementationRef that is bound to an instance
+ of a custom transform.
+
+ @param attribute
+ The name or the attribute handle of the attribute whose
+ value is to be set.
+
+ @param type The type of data to be retrieved for the attribute. See the
+ discussion on SecTransformMetaAttributeType for details.
+
+ @param value The new value for the attribute
+
+ @result A CFErrorRef if an error occured , NULL otherwise.
+
+ @discussion Unlike the SecTransformSetAttribute API this API can set
+ attribute values while a transform is executing. These
+ values are limited to the custom transform instance that
+ is bound to the ref parameter.
+
+*/
+CF_EXPORT
+CFTypeRef SecTransformCustomSetAttribute(SecTransformImplementationRef ref,
+ SecTransformStringOrAttributeRef attribute,
+ SecTransformMetaAttributeType type,
+ CFTypeRef value);
+/*!
+ @function SecTransformPushbackAttribute
+
+ @abstract Allows for putting a single value back for a specific
+ attribute. This will stop the flow of data into the
+ specified attribute until any attribute is changed for the
+ transform instance bound to the ref parameter.
+
+ @param ref A SecTransformImplementationRef that is bound to an instance
+ of a custom transform.
+
+ @param attribute
+ The name or the attribute handle of the attribute whose
+ value is to be pushed back.
+
+ @param value The value being pushed back.
+
+ @result A CFErrorRef if an error occured , NULL otherwise.
+
+*/
+CF_EXPORT
+CFTypeRef SecTransformPushbackAttribute(SecTransformImplementationRef ref,
+ SecTransformStringOrAttributeRef attribute,
+ CFTypeRef value);
+
+/*!
+ @typedef SecTransformCreateFP
+
+ @abstract A function pointer to a function that will create a
+ new instance of a custom transform.
+
+ @param name The name of the new custom transform. This name MUST be
+ unique.
+
+ @param newTransform
+ The newly created transform Ref.
+
+ @param ref A reference that is bound to an instance of a custom
+ transform.
+
+ @result A SecTransformInstanceBlock that is used to create a new
+ instance of a custom transform.
+
+ @discussion The CreateTransform function creates a new transform. The
+ SecTransformInstanceBlock that is returned from this
+ function provides the implementation of all of the overrides
+ necessary to create the custom transform. This returned
+ SecTransformInstanceBlock is also where the "instance"
+ variables for the custom transform may be defined. See the
+ example in the header section of this file for more detail.
+*/
+
+typedef SecTransformInstanceBlock (*SecTransformCreateFP)(CFStringRef name,
+ SecTransformRef newTransform,
+ SecTransformImplementationRef ref);
+
+/************** custom Transform transform override actions **************/
+
+/*!
+ @constant kSecTransformActionCanExecute
+ Overrides the standard behavior that checks to see if all of the
+ required attributes either have been set or are connected to
+ another transform. When overriding the default behavior the
+ developer can decided what the necessary data is to have for a
+ transform to be considered 'ready to run'. Returning NULL means
+ that the transform is ready to be run. If the transform is NOT
+ ready to run then the override should return a CFErrorRef
+ stipulating the error.
+ */
+CF_EXPORT const CFStringRef kSecTransformActionCanExecute;
+/*!
+ @constant kSecTransformActionStartingExecution
+ Overrides the standard behavior that occurs just before starting
+ execution of a custom transform. This is typically overridden
+ to allow for initialization. This is used with the
+ SecTransformOverrideTransformAction block.
+ */
+CF_EXPORT const CFStringRef kSecTransformActionStartingExecution;
+
+/*!
+ @constant kSecTransformActionFinalize
+ Overrides the standard behavior that occurs just before deleting
+ a custom transform. This is typically overridden to allow for
+ memory clean up of a custom transform. This is used with the
+ SecTransformOverrideTransformAction block.
+ */
+CF_EXPORT const CFStringRef kSecTransformActionFinalize;
+
+/*!
+
+ @constant kSecTransformActionExternalizeExtraData
+ Allows for adding to the data that is stored using an override
+ to the kSecTransformActionExternalizeExtraData block. The output
+ of this override is a dictionary that contains the custom
+ externalized data. A common use of this override is to write out
+ a version number of a custom transform.
+ */
+CF_EXPORT const CFStringRef kSecTransformActionExternalizeExtraData;
+
+/*!
+ @constant kSecTransformActionProcessData
+ Overrides the standard data processing for an attribute. This is
+ almost exclusively used for processing the input attribute as
+ the return value of their block sets the output attribute. This
+ is used with the SecTransformOverrideAttributeAction block.
+ */
+CF_EXPORT const CFStringRef kSecTransformActionProcessData;
+
+/*!
+ @constant kSecTransformActionInternalizeExtraData
+ Overrides the standard processing that occurs when externalized
+ data is used to create a transform. This is closely tied to the
+ kSecTransformActionExternalizeExtraData override. The 'normal'
+ attributes are read into the new transform and then this is
+ called to read in the items that were written out using
+ kSecTransformActionExternalizeExtraData override. A common use
+ of this override would be to read in the version number of the
+ externalized custom transform.
+ */
+CF_EXPORT const CFStringRef kSecTransformActionInternalizeExtraData;
+
+/*!
+ @constant SecTransformActionAttributeNotification
+ Allows a block to be called when an attribute is set. This
+ allows for caching the value as a block variable in the instance
+ block or transmogrifying the data to be set. This action is
+ where a custom transform would be able to do processing outside
+ of processing input to output as process data does. One the
+ data has been processed the action block can call
+ SecTransformCustomSetAttribute to update and other attribute.
+ */
+CF_EXPORT const CFStringRef kSecTransformActionAttributeNotification;
+
+/*!
+ @constant kSecTransformActionAttributeValidation
+ Allows a block to be called to validate the new value for an
+ attribute. The default is no validation and any CFTypeRef can
+ be used as the new value. The block should return NULL if the
+ value is ok to set on the attribute or a CFErrorRef otherwise.
+
+*/
+CF_EXPORT const CFStringRef kSecTransformActionAttributeValidation;
+
+/*!
+ @function SecTransformRegister
+
+ @abstract Register a new custom transform so that it may be used to
+ process data
+
+ @param uniqueName
+ A unique name for this custom transform. It is recommended
+ that a reverse DNS name be used for the name of your custom
+ transform
+
+ @param createTransformFunction
+ A SecTransformCreateFP function pointer. The function must
+ return a SecTransformInstanceBlock block that block_copy has
+ been called on before returning the block. Failure to call
+ block_copy will cause undefined behavior.
+
+ @param error This pointer is set if an error occurred. This value
+ may be NULL if you do not want an error returned.
+
+ @result True if the custom transform was registered false otherwise
+
+*/
+CF_EXPORT
+Boolean SecTransformRegister(CFStringRef uniqueName,
+ SecTransformCreateFP createTransformFunction,
+ CFErrorRef* error)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @function SecTransformCreate
+
+ @abstract Creates a transform computation object.
+
+ @param name The type of transform to create, must have been registered
+ by SecTransformRegister, or be a system pre-defined
+ transform type.
+
+ @param error A pointer to a CFErrorRef. This pointer is set if an error
+ occurred. This value may be NULL if you do not want an
+ error returned.
+
+ @result A pointer to a SecTransformRef object. This object must be
+ released with CFRelease when you are done with it. This
+ function returns NULL if an error occurred.
+ */
+CF_EXPORT
+SecTransformRef SecTransformCreate(CFStringRef name, CFErrorRef *error)
+ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
+
+/*!
+ @Function SecTransformNoData
+
+ @abstract Returns back A CFTypeRef from inside a processData
+ override that says that while no data is being returned
+ the transform is still active and awaiting data.
+
+ @result A 'special' value that allows that specifies that the
+ transform is still active and awaiting data.
+
+ @discussion The standard behavior for the ProcessData override is that
+ it will receive a CFDataRef and it processes that data and
+ returns a CFDataRef that contains the processed data. When
+ there is no more data to process the ProcessData override
+ block is called one last time with a NULL CFDataRef. The
+ ProcessData block should/must return the NULL CFDataRef to
+ complete the processing. This model does not work well for
+ some transforms. For example a digest transform needs to see
+ ALL of the data that is being digested before it can send
+ out the digest value.
+
+ If a ProcessData block has no data to return, it can return
+ SecTransformNoData(), which informs the transform system
+ that there is no data to pass on to the next transform.
+
+
+*/
+CF_EXPORT
+CFTypeRef SecTransformNoData(void);
+
+CF_EXTERN_C_END
+
+#endif // __BLOCKS__
+#endif // _SEC_CUSTOM_TRANSFORM_H__
projects / apple / security.git / blobdiff