OSX/libsecurity_smime/lib/SecCmsDecoder.h

   1 /*
   2  *  Copyright (c) 2004,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 /*!
  25     @header SecCmsDecoder.h
  26     @Copyright (c) 2004,2011,2014 Apple Inc. All Rights Reserved.
  27
  28     @availability 10.4 and later
  29     @abstract Interfaces of the CMS implementation.
  30     @discussion The functions here implement functions for encoding
  31                 and decoding Cryptographic Message Syntax (CMS) objects
  32                 as described in rfc3369.
  33  */
  34
  35 #ifndef _SECURITY_SECCMSDECODER_H_
  36 #define _SECURITY_SECCMSDECODER_H_  1
  37
  38 #include <Security/SecCmsBase.h>
  39
  40
  41 #if defined(__cplusplus)
  42 extern "C" {
  43 #endif
  44
  45
  46 /*! @functiongroup Streaming interface */
  47 /*!
  48     @function
  49     @abstract Set up decoding of a BER-encoded CMS message.
  50     @param arena An ArenaPool object to use for the resulting message, or NULL if new ArenaPool
  51         should be created.
  52     @param cb callback function for delivery of inner content inner
  53         content will be stored in the message if cb is NULL.
  54     @param cb_arg first argument passed to cb when it is called.
  55     @param pwfn callback function for getting token password for
  56         enveloped data content with a password recipient.
  57     @param pwfn_arg first argument passed to pwfn when it is called.
  58     @param decrypt_key_cb callback function for getting bulk key
  59         for encryptedData content.
  60     @param decrypt_key_cb_arg first argument passed to decrypt_key_cb
  61         when it is called.
  62     @param outDecoder On success will contain a pointer to a newly created SecCmsDecoder.
  63     @result A result code. See "SecCmsBase.h" for possible results.
  64     @discussion Create a SecCmsDecoder().  If this function returns noErr, the caller must dispose of the returned outDecoder by calling SecCmsDecoderDestroy() or SecCmsDecoderFinish().
  65     @availability 10.4 and later
  66     @updated 2004-04-05
  67  */
  68 extern OSStatus
  69 SecCmsDecoderCreate(SecArenaPoolRef arena,
  70                    SecCmsContentCallback cb, void *cb_arg,
  71                    PK11PasswordFunc pwfn, void *pwfn_arg,
  72                    SecCmsGetDecryptKeyCallback decrypt_key_cb, void
  73                    *decrypt_key_cb_arg,
  74                    SecCmsDecoderRef *outDecoder) DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
  75
  76 /*!
  77     @function
  78     @abstract Feed BER-encoded data to decoder.
  79     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
  80     @param buf Pointer to bytes to be decoded.
  81     @param len number of bytes to decode.
  82     @result A result code. See "SecCmsBase.h" for possible results.
  83     @discussion If a call to this function fails the caller should call SecCmsDecoderDestroy().
  84     @availability 10.4 and later
  85  */
  86 extern OSStatus
  87 SecCmsDecoderUpdate(SecCmsDecoderRef decoder, const void *buf, CFIndex len);
  88
  89 /*!
  90     @function
  91     @abstract Abort a (presumably failed) decoding process.
  92     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
  93     @availability 10.4 and later
  94  */
  95 extern void
  96 SecCmsDecoderDestroy(SecCmsDecoderRef decoder);
  97
  98 /*!
  99     @function
 100     @abstract Mark the end of inner content and finish decoding.
 101     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
 102     @param outMessage On success a pointer to a SecCmsMessage containing the decoded message.
 103     @result A result code. See "SecCmsBase.h" for possible results.
 104     @discussion decoder is no longer valid after this function is called.
 105     @availability 10.4 and later
 106  */
 107 extern OSStatus
 108 SecCmsDecoderFinish(SecCmsDecoderRef decoder, SecCmsMessageRef *outMessage);
 109
 110 /*! @functiongroup One shot interface */
 111 /*!
 112     @function
 113     @abstract Decode a CMS message from BER encoded data.
 114     @discussion This function basically does the same as calling
 115                 SecCmsDecoderStart(), SecCmsDecoderUpdate() and SecCmsDecoderFinish().
 116     @param encodedMessage Pointer to a CSSM_DATA containing the BER encoded cms
 117            message to decode.
 118     @param cb callback function for delivery of inner content inner
 119            content will be stored in the message if cb is NULL.
 120     @param cb_arg first argument passed to cb when it is called.
 121     @param pwfn callback function for getting token password for enveloped
 122            data content with a password recipient.
 123     @param pwfn_arg first argument passed to pwfn when it is called.
 124     @param decrypt_key_cb callback function for getting bulk key for encryptedData content.
 125     @param decrypt_key_cb_arg first argument passed to decrypt_key_cb when it is called.
 126     @param outMessage On success a pointer to a SecCmsMessage containing the decoded message.
 127     @result A result code. See "SecCmsBase.h" for possible results.
 128     @discussion decoder is no longer valid after this function is called.
 129     @availability 10.4 and later
 130  */
 131 extern OSStatus
 132 SecCmsMessageDecode(const CSSM_DATA *encodedMessage,
 133                     SecCmsContentCallback cb, void *cb_arg,
 134                     PK11PasswordFunc pwfn, void *pwfn_arg,
 135                     SecCmsGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg,
 136                     SecCmsMessageRef *outMessage) DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 137
 138
 139 #if defined(__cplusplus)
 140 }
 141 #endif
 142
 143 #endif /* _SECURITY_SECCMSDECODER_H_ */