OSX/libsecurity_transform/lib/SecCustomTransform.h

   1 /*
   2  * Copyright (c) 2010-2011,2014 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _SEC_CUSTOM_TRANSFORM_H__
  25 #define _SEC_CUSTOM_TRANSFORM_H__
  26
  27 #include <Security/SecTransform.h>
  28
  29 // Blocks are required for custom transforms
  30 #ifdef __BLOCKS__
  31
  32 CF_EXTERN_C_BEGIN
  33
  34 CF_ASSUME_NONNULL_BEGIN
  35 CF_IMPLICIT_BRIDGING_ENABLED
  36
  37 /*!
  38     @header
  39
  40     Custom transforms are an API that provides the ability to easily create new
  41     transforms. The essential functions of a transform are created in a
  42     collection of blocks. These blocks override the standard behavior of the
  43     base transform; a custom transform with no overrides is a null transform
  44     that merely passes through a data flow.
  45
  46     A new transform type is created when calling the SecTransformRegister
  47     function which registers the name of the new transform and sets up its
  48     overrides. The SecTransformCreate function creates a new instance of a
  49     registered custom transform.
  50
  51     A sample custom transform is provided here, along with a basic test program.
  52     This transform creates a Caesar cipher transform, one that simply adds a
  53     value to every byte of the plaintext.
  54
  55     -----cut here-----
  56 <pre>
  57 @textblock
  58 //
  59 //  CaesarXform.c
  60 //
  61 //  Copyright (c) 2010-2011,2014 Apple Inc. All Rights Reserved.
  62 //
  63 //
  64
  65 #include <Security/SecCustomTransform.h>
  66 #include <Security/SecTransform.h>
  67
  68 // This is the unique name for the custom transform type.
  69 const CFStringRef kCaesarCipher = CFSTR("com.apple.caesarcipher");
  70
  71 // Name of the "key" attribute.
  72 const CFStringRef kKeyAttributeName = CFSTR("key");
  73
  74 // Shortcut to return a CFError.
  75 CFErrorRef invalid_input_error(void)
  76 {
  77     return CFErrorCreate(kCFAllocatorDefault, kSecTransformErrorDomain,
  78                          kSecTransformErrorInvalidInput, NULL);
  79 }
  80
  81 // =========================================================================
  82 //  Implementation of the Transform instance
  83 // =========================================================================
  84 static SecTransformInstanceBlock CaesarImplementation(CFStringRef name,
  85                                             SecTransformRef newTransform,
  86                                             SecTransformImplementationRef ref)
  87 {
  88
  89     SecTransformInstanceBlock instanceBlock =
  90     ^{
  91         CFErrorRef result = NULL;
  92
  93         // Every time a new instance of this custom transform class is
  94         // created, this block is called. This behavior means that any
  95         // block variables created in this block act like instance
  96         // variables for the new custom transform instance.
  97         __block int _key = 0;
  98
  99         result = SecTransformSetAttributeAction(ref,
 100                                                 kSecTransformActionAttributeNotification,
 101                                                 kKeyAttributeName,
 102                                                 ^(SecTransformAttributeRef name, CFTypeRef d)
 103             {
 104                 CFNumberGetValue((CFNumberRef)d, kCFNumberIntType, &_key);
 105                 return d;
 106             });
 107
 108         if (result)
 109             return result;
 110
 111         // Create an override that will be called to process the input
 112         // data into the output data
 113         result = SecTransformSetDataAction(ref,
 114                                            kSecTransformActionProcessData,
 115                                            ^(CFTypeRef d)
 116             {
 117                 if (NULL == d)               // End of stream?
 118                     return (CFTypeRef) NULL; // Just return a null.
 119
 120                 char *dataPtr = (char *)CFDataGetBytePtr((CFDataRef)d);
 121
 122                 CFIndex dataLength = CFDataGetLength((CFDataRef)d);
 123
 124                 // Do the processing in memory.  There are better ways to do
 125                 // this but for showing how custom transforms work this is fine.
 126                 char *buffer = (char *)malloc(dataLength);
 127                 if (NULL == buffer)
 128                     return (CFTypeRef) invalid_input_error();            // Return a CFErrorRef
 129
 130                 // Do the work of the caesar cipher (Rot(n))
 131
 132                 CFIndex i;
 133                 for (i = 0; i < dataLength; i++)
 134                     buffer[i] = dataPtr[i] + _key;
 135
 136                 return (CFTypeRef)CFDataCreateWithBytesNoCopy(NULL, (UInt8 *)buffer,
 137                                                               dataLength, kCFAllocatorMalloc);
 138             });
 139         return result;
 140     };
 141
 142     return Block_copy(instanceBlock);
 143 }
 144
 145 SecTransformRef CaesarTransformCreate(CFIndex k, CFErrorRef* error)
 146 {
 147     SecTransformRef caesarCipher;
 148     __block Boolean result = 1;
 149     static dispatch_once_t registeredOK = 0;
 150
 151     dispatch_once(&registeredOK,
 152                   ^{
 153                      result = SecTransformRegister(kCaesarCipher, &CaesarImplementation, error);
 154                   });
 155
 156     if (!result)
 157         return NULL;
 158
 159     caesarCipher = SecTransformCreate(kCaesarCipher, error);
 160     if (NULL != caesarCipher)
 161     {
 162         CFNumberRef keyNumber =  CFNumberCreate(kCFAllocatorDefault,
 163                                                 kCFNumberIntType, &k);
 164         SecTransformSetAttribute(caesarCipher, kKeyAttributeName,
 165                                  keyNumber, error);
 166         CFRelease(keyNumber);
 167     }
 168
 169     return caesarCipher;
 170 }
 171
 172
 173 // The second function shows how to use custom transform defined in the
 174 // previous function
 175
 176 // =========================================================================
 177 //  Use a custom ROT-N (caesar cipher) transform
 178 // =========================================================================
 179 CFDataRef TestCaesar(CFDataRef theData, int rotNumber)
 180 {
 181     CFDataRef result = NULL;
 182     CFErrorRef error = NULL;
 183
 184     if (NULL == theData)
 185         return result;
 186
 187     // Create an instance of the custom transform
 188     SecTransformRef caesarCipher = CaesarTransformCreate(rotNumber, &error);
 189     if (NULL == caesarCipher || NULL != error)
 190         return result;
 191
 192     // Set the data to be transformed as the input to the custom transform
 193     SecTransformSetAttribute(caesarCipher,
 194                              kSecTransformInputAttributeName, theData, &error);
 195
 196     if (NULL != error)
 197     {
 198         CFRelease(caesarCipher);
 199         return result;
 200     }
 201
 202     // Execute the transform synchronously
 203     result = (CFDataRef)SecTransformExecute(caesarCipher, &error);
 204     CFRelease(caesarCipher);
 205
 206     return result;
 207 }
 208
 209 #include <CoreFoundation/CoreFoundation.h>
 210
 211 int main (int argc, const char *argv[])
 212 {
 213     CFDataRef testData, testResult;
 214     UInt8 bytes[26];
 215     int i;
 216
 217     // Create some test data, a string from A-Z
 218
 219     for (i = 0; i < sizeof(bytes); i++)
 220         bytes[i] = 'A' + i;
 221
 222     testData = CFDataCreate(kCFAllocatorDefault, bytes, sizeof(bytes));
 223     CFRetain(testData);
 224     CFShow(testData);
 225
 226     // Encrypt the test data
 227     testResult = TestCaesar(testData, 3);
 228
 229     CFShow(testResult);
 230     CFRelease(testData);
 231     CFRelease(testResult);
 232     return 0;
 233 }
 234 @/textblock
 235 </pre>
 236
 237 */
 238
 239 /****************       Custom Transform attribute metadata   ****************/
 240
 241 /*!
 242     @enum Custom Transform Attribute Metadata
 243     @discussion
 244             Within a transform, each of its attributes is a collection of
 245             "metadata attributes", of which name and current value are two. The
 246             value is directly visible from outside; the other metadata
 247             attributes direct the behavior of the transform and
 248             its function within its group. Each attribute may be tailored by setting its metadata.
 249
 250     @const kSecTransformMetaAttributeValue
 251             The actual value of the attribute. The attribute value has a default
 252             value of NULL.
 253
 254     @const kSecTransformMetaAttributeName
 255             The name of the attribute. Attribute name is read only and may
 256             not be used with the SecTransformSetAttributeBlock block.
 257
 258     @const kSecTransformMetaAttributeRef
 259             A direct reference to an attribute's value. This reference allows
 260             for direct access to an attribute without having to look up the
 261             attribute by name.  If a transform commonly uses an attribute, using
 262             a reference speeds up the use of that attribute. Attribute
 263             references are not visible or valid from outside of the particular
 264             transform instance.
 265
 266     @const kSecTransformMetaAttributeRequired
 267             Specifies if an attribute must have a non NULL value set or have an
 268             incoming connection before the transform starts to execute. This
 269             metadata has a default value of true for the input attribute, but
 270             false for all other attributes.
 271
 272     @const kSecTransformMetaAttributeRequiresOutboundConnection
 273             Specifies if an attribute must have an outbound connection. This
 274             metadata has a default value of true for the output attribute but is
 275             false for all other attributes.
 276
 277     @const kSecTransformMetaAttributeDeferred
 278             Determines if the AttributeSetNotification notification or the
 279             ProcessData blocks are deferred until SecExecuteTransform is called.
 280             This metadata value has a default value of true for the input
 281             attribute but is false for all other attributes.
 282
 283     @const kSecTransformMetaAttributeStream
 284             Specifies if the attribute should expect a series of values ending
 285             with a NULL to specify the end of the data stream. This metadata has
 286             a default value of true for the input and output attributes, but is
 287             false for all other attributes.
 288
 289     @const kSecTransformMetaAttributeCanCycle
 290             A Transform group is a directed graph which is typically acyclic.
 291             Some transforms need to work with cycles. For example, a transform
 292             that emits a header and trailer around the data of another transform
 293             must create a cycle. If this metadata set to true, no error is
 294             returned if a cycle is detected for this attribute.
 295
 296     @const kSecTransformMetaAttributeExternalize
 297             Specifies if this attribute should be written out when creating the
 298             external representation of this transform. This metadata has a
 299             default value of true.
 300
 301     @const kSecTransformMetaAttributeHasOutboundConnections
 302             This metadata value is true if the attribute has an outbound
 303             connection. This metadata is read only.
 304
 305     @const kSecTransformMetaAttributeHasInboundConnection
 306             This metadata value is true if the attribute has an inbound
 307             connection. This metadata is read only.
 308 */
 309
 310 typedef CF_ENUM(CFIndex, SecTransformMetaAttributeType)
 311 {
 312     kSecTransformMetaAttributeValue,
 313     kSecTransformMetaAttributeName,
 314     kSecTransformMetaAttributeRef,
 315     kSecTransformMetaAttributeRequired,
 316     kSecTransformMetaAttributeRequiresOutboundConnection,
 317     kSecTransformMetaAttributeDeferred,
 318     kSecTransformMetaAttributeStream,
 319     kSecTransformMetaAttributeCanCycle,
 320     kSecTransformMetaAttributeExternalize,
 321     kSecTransformMetaAttributeHasOutboundConnections,
 322     kSecTransformMetaAttributeHasInboundConnection
 323 };
 324
 325 /*!
 326     @typedef        SecTransformAttributeRef
 327
 328     @abstract       A direct reference to an attribute. Using an attribute
 329                     reference speeds up using an attribute's value by removing
 330                     the need to look
 331     it up by name.
 332 */
 333 typedef CFTypeRef SecTransformAttributeRef;
 334
 335
 336 /*!
 337     @typedef        SecTransformStringOrAttributeRef
 338
 339     @abstract       This type signifies that either a CFStringRef or
 340                     a SecTransformAttributeRef may be used.
 341 */
 342 typedef CFTypeRef SecTransformStringOrAttributeRef;
 343
 344
 345 /*!
 346     @typedef        SecTransformActionBlock
 347
 348     @abstract       A block that overrides the default behavior of a
 349                     custom transform.
 350
 351     @result         If this block is used to overide the
 352                     kSecTransformActionExternalizeExtraData action then the
 353                     block should return a CFDictinaryRef of the custom
 354                     items to be exported. For all of other actions the
 355                     block should return NULL. If an error occurs for
 356                     any action, the block should return a CFErrorRef.
 357
 358     @discussion     A SecTransformTransformActionBlock block is used to
 359                     override
 360                     the default behavior of a custom transform. This block is
 361                     associated with the SecTransformOverrideTransformAction
 362                     block.
 363
 364                     The behaviors that can be overridden are:
 365
 366                         kSecTransformActionCanExecute
 367                             Determine if the transform has all of the data
 368                             needed to run.
 369
 370                         kSecTransformActionStartingExecution
 371                             Called just before running ProcessData.
 372
 373                         kSecTransformActionFinalize
 374                             Called just before deleting the custom transform.
 375
 376                         kSecTransformActionExternalizeExtraData
 377                             Called to allow for writing out custom data
 378                             to be exported.
 379
 380                     Example:
 381 <pre>
 382 @textblock
 383                     SecTransformImplementationRef ref;
 384                     CFErrorRef error = NULL;
 385
 386                     error = SecTransformSetTransformAction(ref, kSecTransformActionStartingExecution,
 387                     ^{
 388                         // This is where the work to initialize any data needed
 389                         // before running
 390                         CFErrorRef result = DoMyInitialization();
 391                         return result;
 392                     });
 393
 394                     SecTransformTransformActionBlock actionBlock =
 395                     ^{
 396                         // This is where the work to clean up any existing data
 397                         // before running
 398                         CFErrorRef result = DoMyFinalization();
 399                         return result;
 400                     };
 401
 402                     error = SecTransformSetTransformAction(ref, kSecTransformActionFinalize,
 403                         actionBlock);
 404 @/textblock
 405 </pre>
 406 */
 407 typedef CFTypeRef __nullable (^SecTransformActionBlock)(void);
 408
 409 /*!
 410     @typedef        SecTransformAttributeActionBlock
 411
 412     @abstract       A block used to override the default attribute handling
 413                     for when an attribute is set.
 414
 415     @param attribute       The attribute whose default is being overridden or NULL
 416                     if this is a generic notification override
 417
 418     @param value    Proposed new value for the attribute.
 419
 420     @result         The new value of the attribute if successful. If an
 421                     error occurred then a CFErrorRef is returned. If a transform
 422                     needs to have a CFErrorRef as the value of an attribute,
 423                     then the CFErrorRef needs to be placed into a container such
 424                     as a CFArrayRef, CFDictionaryRef etc.
 425
 426     @discussion     See the example program in this header for more details.
 427
 428 */
 429 typedef CFTypeRef __nullable (^SecTransformAttributeActionBlock)(
 430                                 SecTransformAttributeRef attribute,
 431                                 CFTypeRef value);
 432
 433 /*!
 434     @typedef        SecTransformDataBlock
 435
 436     @abstract       A block used to override the default data handling
 437                     for a transform.
 438
 439     @param data     The data to be processed. When this block is used
 440                     to to implement the kSecTransformActionProcessData action,
 441                     the data is the input data that is to be processed into the
 442                     output data.  When this block is used to implement the
 443                     kSecTransformActionInternalizeExtraData action, the data is
 444                     a CFDictionaryRef that contains the data that needs to be
 445                     imported.
 446
 447     @result         When this block is used to implment the
 448                     kSecTransformActionProcessData action, the value returned
 449                     is to be the data that will be passed to the output
 450                     attribute.  If an error occured while processing the input
 451                     data then the block should return a CFErrorRef.
 452
 453                     When this block is used to implement the
 454                     kSecTransformActionInternalizeExtraData action then this block
 455                     should return NULL or a CFErrorRef if an error occurred.
 456
 457     @discussion     See the example program for more details.
 458 */
 459 typedef CFTypeRef __nullable (^SecTransformDataBlock)(CFTypeRef data);
 460
 461 /*!
 462     @typedef        SecTransformInstanceBlock
 463
 464     @abstract       This is the block that is returned from an
 465                     implementation of a CreateTransform function.
 466
 467     @result         A CFErrorRef if an error occurred or NULL.
 468
 469     @discussion     The instance block that is returned from the
 470                     developers CreateTransform function, defines
 471                     the behavior of a custom attribute.  Please
 472                     see the example at the head of this file.
 473
 474 */
 475 typedef CFErrorRef __nullable (^SecTransformInstanceBlock)(void);
 476
 477 /*!
 478     @typedef        SecTransformImplementationRef
 479
 480     @abstract       The SecTransformImplementationRef is a pointer to a block
 481                     that implements an instance of a transform.
 482
 483 */
 484 typedef const struct OpaqueSecTransformImplementation* SecTransformImplementationRef;
 485
 486 /*!
 487     @function       SecTransformSetAttributeAction
 488
 489     @abstract       Be notified when a attribute is set. The supplied block is
 490                     called when the attribute is set. This can be done for a
 491                     specific named attribute or all attributes.
 492
 493     @param ref      A SecTransformImplementationRef that is bound to an instance
 494                     of a custom transform.
 495
 496     @param action   The behavior to be set. This can be one of the following
 497                     actions:
 498
 499                     kSecTransformActionAttributeNotification - add a block that
 500                     is called when an attribute is set. If the name is NULL,
 501                     then the supplied block is called for all set attributes
 502                     except for ones that have a specific block as a handler.
 503
 504                     For example, if there is a handler for the attribute "foo"
 505                     and for all attributes, the "foo" handler is called when the
 506                     "foo" attribute is set, but all other attribute sets will
 507                     call the NULL handler.
 508
 509                     The kSecTransformActionProcessData action is a special case
 510                     of a SecTransformSetAttributeAction action.  If this is
 511                     called on the input attribute then it will overwrite any
 512                     kSecTransformActionProcessData that was set.
 513
 514                     kSecTransformActionAttributeValidation Add a block that is
 515                     called to validate the input to an attribute.
 516
 517     @param attribute
 518                     The name of the attribute that will be handled. An attribute
 519                     reference may also be given here. A NULL name indicates that
 520                     the supplied action is for all attributes.
 521
 522     @param newAction
 523                     A SecTransformAttributeActionBlock which implements the
 524                     behavior.
 525
 526     @result         A CFErrorRef if an error occured NULL otherwise.
 527
 528     @discussion     This function may be called multiple times for either a
 529                     named attribute or for all attributes when the attribute
 530                     parameter is NULL. Each time the API is called it overwrites
 531                     what was there previously.
 532
 533 */
 534 CF_EXPORT __nullable
 535 CFErrorRef SecTransformSetAttributeAction(SecTransformImplementationRef ref,
 536                                 CFStringRef action,
 537                                 SecTransformStringOrAttributeRef __nullable attribute,
 538                                 SecTransformAttributeActionBlock newAction);
 539 /*!
 540     @function       SecTransformSetDataAction
 541
 542     @abstract       Change the way a custom transform will do data processing.
 543                     When the action parameter is kSecTransformActionProcessData
 544                     The newAction block will change the way that input data is
 545                     processed to become the output data. When the action
 546                     parameter is kSecTransformActionInternalizeExtraData it will
 547                     change the way a custom transform reads in data to be
 548                     imported into the transform.
 549
 550     @param ref      A SecTransformImplementationRef that is bound to an instance
 551                     of a custom transform.
 552
 553     @param action   The action being overridden.  This value should be one of the
 554                     following:
 555                         kSecTransformActionProcessData
 556                             Change the way that input data is processed into the
 557                             output data. The default behavior is to simply copy
 558                             the input data to the output attribute.
 559
 560                             The kSecTransformActionProcessData action is really
 561                             a special case of a SecTransformSetAttributeAction
 562                             action. If you call this method with
 563                             kSecTransformActionProcessData it would overwrite
 564                             any kSecTransformActionAttributeNotification action
 565                             that was set proviously
 566
 567                         kSecTransformActionInternalizeExtraData
 568                             Change the way that custom externalized data is
 569                             imported into the transform.  The default behavior
 570                             is to do nothing.
 571
 572     @param newAction
 573                     A SecTransformDataBlock which implements the behavior.
 574
 575                     If the action parameter is kSecTransformActionProcessData then
 576                     this block will be called to process the input data into the
 577                     output data.
 578
 579                     if the action parameter is kSecTransformActionInternalizeExtraData then
 580                     this block will called to input custom data into the transform.
 581
 582     @result         A CFErrorRef is an error occured NULL otherwise.
 583
 584     @discussion      This API may be called multiple times.  Each time the API is called
 585                     it overwrites what was there previously.
 586
 587 */
 588 CF_EXPORT __nullable
 589 CFErrorRef SecTransformSetDataAction(SecTransformImplementationRef ref,
 590                                     CFStringRef action,
 591                                     SecTransformDataBlock newAction);
 592
 593 /*
 594     @function       SecTransformSetTransformAction
 595
 596     @abstract       Change the way that transform deals with transform lifecycle
 597                     behaviors.
 598
 599     @param ref      A SecTransformImplementationRef that is bound to an instance
 600                     of a custom transform. It provides the neccessary context
 601                     for making the call to modify a custom transform.
 602
 603     @param action   Defines what behavior will be changed.  The possible values
 604                     are:
 605
 606                         kSecTransformActionCanExecute
 607                             A CanExecute block is called before the transform
 608                             starts to execute. Returning NULL indicates that the
 609                             transform has all necessary parameters set up to be
 610                             able to execute. If there is a condition that
 611                             prevents this transform from executing, return a
 612                             CFError. The default behavior is to return NULL.
 613
 614                         kSecTransformActionStartingExecution
 615                             A StartingExecution block is called as a transform
 616                             starts execution but before any input is delivered.
 617                             Transform-specific initialization can be performed
 618                             in this block.
 619
 620                         kSecTransformActionFinalize
 621                             A Finalize block is called before a transform is
 622                             released. Any final cleanup can be performed in this
 623                             block.
 624
 625                         kSecTransformActionExternalizeExtraData
 626                             An ExternalizeExtraData block is called before a
 627                             transform is externalized. If there is any extra
 628                             work that the transform needs to do (e.g. copy data
 629                             from local variables to attributes) it can be
 630                             performed in this block.
 631
 632     @param newAction
 633                     A SecTransformTransformActionBlock which implements the behavior.
 634
 635     @result         A CFErrorRef if an error occured NULL otherwise.
 636
 637 */
 638 CF_EXPORT __nullable
 639 CFErrorRef SecTransformSetTransformAction(SecTransformImplementationRef ref,
 640                                 CFStringRef action,
 641                                 SecTransformActionBlock newAction);
 642
 643 /*!
 644  @function       SecTranformCustomGetAttribute
 645
 646  @abstract       Allow a custom transform to get an attribute value
 647
 648  @param ref      A SecTransformImplementationRef that is bound to an instance
 649  of a custom transform.
 650
 651  @param attribute
 652  The name or the attribute handle of the attribute whose
 653  value is to be retrieved.
 654
 655  @param type     The type of data to be retrieved for the attribute.  See the
 656  discussion on SecTransformMetaAttributeType for details.
 657
 658  @result         The value of the attribute.
 659
 660  */
 661 CF_EXPORT __nullable
 662 CFTypeRef SecTranformCustomGetAttribute(SecTransformImplementationRef ref,
 663                                         SecTransformStringOrAttributeRef attribute,
 664                                         SecTransformMetaAttributeType type) AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_8;
 665
 666 /*!
 667  @function       SecTransformCustomGetAttribute
 668
 669  @abstract       Allow a custom transform to get an attribute value
 670
 671  @param ref      A SecTransformImplementationRef that is bound to an instance
 672  of a custom transform.
 673
 674  @param attribute
 675  The name or the attribute handle of the attribute whose
 676  value is to be retrieved.
 677
 678  @param type     The type of data to be retrieved for the attribute.  See the
 679  discussion on SecTransformMetaAttributeType for details.
 680
 681  @result         The value of the attribute.
 682
 683  */
 684 CF_EXPORT __nullable
 685 CFTypeRef SecTransformCustomGetAttribute(SecTransformImplementationRef ref,
 686                                         SecTransformStringOrAttributeRef attribute,
 687                                         SecTransformMetaAttributeType type) __asm__("_SecTranformCustomGetAttribute");
 688
 689 /*!
 690     @function       SecTransformCustomSetAttribute
 691
 692     @abstract       Allow a custom transform to set an attribute value
 693
 694     @param ref      A SecTransformImplementationRef that is bound to an instance
 695                     of a custom transform.
 696
 697     @param attribute
 698                     The name or the attribute handle of the attribute whose
 699                     value is to be set.
 700
 701     @param type     The type of data to be retrieved for the attribute.  See the
 702                     discussion on SecTransformMetaAttributeType for details.
 703
 704     @param value    The new value for the attribute
 705
 706     @result         A CFErrorRef if an error occured , NULL otherwise.
 707
 708     @discussion     Unlike the SecTransformSetAttribute API this API can set
 709                     attribute values while a transform is executing.  These
 710                     values are limited to the custom transform instance that
 711                     is bound to the ref parameter.
 712
 713 */
 714 CF_EXPORT __nullable
 715 CFTypeRef SecTransformCustomSetAttribute(SecTransformImplementationRef ref,
 716                                     SecTransformStringOrAttributeRef attribute,
 717                                     SecTransformMetaAttributeType type,
 718                                     CFTypeRef __nullable value);
 719 /*!
 720     @function       SecTransformPushbackAttribute
 721
 722     @abstract       Allows for putting a single value back for a specific
 723                     attribute.  This will stop the flow of data into the
 724                     specified attribute until any attribute is changed for the
 725                     transform instance bound to the ref parameter.
 726
 727     @param ref      A SecTransformImplementationRef that is bound to an instance
 728                     of a custom transform.
 729
 730     @param attribute
 731                     The name or the attribute handle of the attribute whose
 732                     value is to be pushed back.
 733
 734     @param value    The value being pushed back.
 735
 736     @result         A CFErrorRef if an error occured , NULL otherwise.
 737
 738 */
 739 CF_EXPORT __nullable
 740 CFTypeRef SecTransformPushbackAttribute(SecTransformImplementationRef ref,
 741                                 SecTransformStringOrAttributeRef attribute,
 742                                 CFTypeRef value);
 743
 744 /*!
 745     @typedef        SecTransformCreateFP
 746
 747     @abstract       A function pointer to a function that will create a
 748                     new instance of a custom transform.
 749
 750     @param name     The name of the new custom transform. This name MUST be
 751                     unique.
 752
 753     @param newTransform
 754                     The newly created transform Ref.
 755
 756     @param ref      A reference that is bound to an instance of a custom
 757                     transform.
 758
 759     @result         A SecTransformInstanceBlock that is used to create a new
 760                     instance of a custom transform.
 761
 762     @discussion      The CreateTransform function creates a new transform. The
 763                     SecTransformInstanceBlock that is returned from this
 764                     function provides the implementation of all of the overrides
 765                     necessary to create the custom transform. This returned
 766                     SecTransformInstanceBlock is also where the "instance"
 767                     variables for the custom transform may be defined. See the
 768                     example in the header section of this file for more detail.
 769 */
 770
 771 typedef SecTransformInstanceBlock __nonnull (*SecTransformCreateFP)(CFStringRef name,
 772                             SecTransformRef newTransform,
 773                             SecTransformImplementationRef ref);
 774
 775 /************** custom Transform transform override actions   **************/
 776
 777 /*!
 778     @constant  kSecTransformActionCanExecute
 779                 Overrides the standard behavior that checks to see if all of the
 780                 required attributes either have been set or are connected to
 781                 another transform.  When overriding the default behavior the
 782                 developer can decided what the necessary data is to have for a
 783                 transform to be considered 'ready to run'.  Returning NULL means
 784                 that the transform is ready to be run. If the transform is NOT
 785                 ready to run then the override should return a CFErrorRef
 786                 stipulating the error.
 787  */
 788 CF_EXPORT const CFStringRef kSecTransformActionCanExecute;
 789 /*!
 790     @constant  kSecTransformActionStartingExecution
 791                 Overrides the standard behavior that occurs just before starting
 792                 execution of a custom transform. This is typically overridden
 793                 to allow for initialization. This is used with the
 794                 SecTransformOverrideTransformAction block.
 795  */
 796 CF_EXPORT const CFStringRef kSecTransformActionStartingExecution;
 797
 798 /*!
 799     @constant kSecTransformActionFinalize
 800                 Overrides the standard behavior that occurs just before deleting
 801                 a custom transform. This is typically overridden to allow for
 802                 memory clean up of a custom transform.  This is used with the
 803                 SecTransformOverrideTransformAction block.
 804  */
 805 CF_EXPORT const CFStringRef kSecTransformActionFinalize;
 806
 807 /*!
 808
 809     @constant kSecTransformActionExternalizeExtraData
 810                 Allows for adding to the data that is stored using an override
 811                 to the kSecTransformActionExternalizeExtraData block. The output
 812                 of this override is a dictionary that contains the custom
 813                 externalized data. A common use of this override is to write out
 814                 a version number of a custom transform.
 815  */
 816 CF_EXPORT const CFStringRef kSecTransformActionExternalizeExtraData;
 817
 818 /*!
 819     @constant  kSecTransformActionProcessData
 820                 Overrides the standard data processing for an attribute. This is
 821                 almost exclusively used for processing the input attribute as
 822                 the return value of their block sets the output attribute. This
 823                 is used with the SecTransformOverrideAttributeAction block.
 824  */
 825 CF_EXPORT const CFStringRef kSecTransformActionProcessData;
 826
 827 /*!
 828     @constant kSecTransformActionInternalizeExtraData
 829                 Overrides the standard processing that occurs when externalized
 830                 data is used to create a transform.  This is closely tied to the
 831                 kSecTransformActionExternalizeExtraData override. The 'normal'
 832                 attributes are read into the new transform and then this is
 833                 called to read in the items that were written out using
 834                 kSecTransformActionExternalizeExtraData override. A common use
 835                 of this override would be to read in the version number of the
 836                 externalized custom transform.
 837  */
 838 CF_EXPORT const CFStringRef kSecTransformActionInternalizeExtraData;
 839
 840 /*!
 841     @constant SecTransformActionAttributeNotification
 842                 Allows a block to be called when an attribute is set.  This
 843                 allows for caching the value as a block variable in the instance
 844                 block or transmogrifying the data to be set. This action is
 845                 where a custom transform would be able to do processing outside
 846                 of processing input to output as process data does.  One the
 847                 data has been processed the action block can call
 848                 SecTransformCustomSetAttribute to update and other attribute.
 849  */
 850 CF_EXPORT const CFStringRef kSecTransformActionAttributeNotification;
 851
 852 /*!
 853     @constant kSecTransformActionAttributeValidation
 854                 Allows a block to be called to validate the new value for an
 855                 attribute.  The default is no validation and any CFTypeRef can
 856                 be used as the new value.  The block should return NULL if the
 857                 value is ok to set on the attribute or a CFErrorRef otherwise.
 858
 859 */
 860 CF_EXPORT const CFStringRef kSecTransformActionAttributeValidation;
 861
 862 /*!
 863     @function       SecTransformRegister
 864
 865     @abstract       Register a new custom transform so that it may be used to
 866                     process data
 867
 868     @param uniqueName
 869                     A unique name for this custom transform.  It is recommended
 870                     that a reverse DNS name be used for the name of your custom
 871                     transform
 872
 873     @param createTransformFunction
 874                     A SecTransformCreateFP function pointer. The function must
 875                     return a SecTransformInstanceBlock block that block_copy has
 876                     been called on before returning the block. Failure to call
 877                     block_copy will cause undefined behavior.
 878
 879     @param error    This pointer is set if an error occurred.  This value
 880                     may be NULL if you do not want an error returned.
 881
 882     @result         True if the custom transform was registered false otherwise
 883
 884 */
 885 CF_EXPORT
 886 Boolean SecTransformRegister(CFStringRef uniqueName,
 887                                     SecTransformCreateFP createTransformFunction,
 888                                     CFErrorRef* error)
 889                             __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
 890
 891 /*!
 892      @function      SecTransformCreate
 893
 894      @abstract      Creates a transform computation object.
 895
 896      @param name    The type of transform to create, must have been registered
 897                     by SecTransformRegister, or be a system pre-defined
 898                     transform type.
 899
 900      @param error   A pointer to a CFErrorRef.  This pointer is set if an error
 901                     occurred.  This value may be NULL if you do not want an
 902                     error returned.
 903
 904      @result        A pointer to a SecTransformRef object.  This object must be
 905                     released with CFRelease when you are done with it.  This
 906                     function returns NULL if an error occurred.
 907  */
 908 CF_EXPORT __nullable
 909 SecTransformRef SecTransformCreate(CFStringRef name, CFErrorRef *error)
 910                             __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_NA);
 911
 912 /*!
 913     @Function       SecTransformNoData
 914
 915     @abstract       Returns back A CFTypeRef from inside a processData
 916                     override that says that while no data is being returned
 917                     the transform is still active and awaiting data.
 918
 919     @result         A 'special' value that allows that specifies that the
 920                     transform is still active and awaiting data.
 921
 922     @discussion      The standard behavior for the ProcessData override is that
 923                     it will receive a CFDataRef and it processes that data and
 924                     returns a CFDataRef that contains the processed data. When
 925                     there is no more data to process the ProcessData override
 926                     block is called one last time with a NULL CFDataRef.  The
 927                     ProcessData block should/must return the NULL CFDataRef to
 928                     complete the processing.  This model does not work well for
 929                     some transforms. For example a digest transform needs to see
 930                     ALL of the data that is being digested before it can send
 931                     out the digest value.
 932
 933                     If a ProcessData block has no data to return, it can return
 934                     SecTransformNoData(), which informs the transform system
 935                     that there is no data to pass on to the next transform.
 936
 937
 938 */
 939 CF_EXPORT
 940 CFTypeRef SecTransformNoData(void);
 941
 942 CF_IMPLICIT_BRIDGING_DISABLED
 943 CF_ASSUME_NONNULL_END
 944
 945 CF_EXTERN_C_END
 946
 947 #endif // __BLOCKS__
 948 #endif // _SEC_CUSTOM_TRANSFORM_H__