CMS/SecCmsDecoder.h

   1 /*
   2  *  Copyright (c) 2004-2018 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
  27     @availability 10.4 and later
  28     @abstract Interfaces of the CMS implementation.
  29     @discussion The functions here implement functions for encoding
  30                 and decoding Cryptographic Message Syntax (CMS) objects
  31                 as described in rfc3369.
  32  */
  33
  34 #ifndef _SECURITY_SECCMSDECODER_H_
  35 #define _SECURITY_SECCMSDECODER_H_  1
  36
  37 #include <Security/SecCmsBase.h>
  38
  39 __BEGIN_DECLS
  40
  41 /*! @functiongroup Streaming interface */
  42
  43 #if TARGET_OS_OSX
  44 /*!
  45      @function
  46      @abstract Set up decoding of a BER-encoded CMS message.
  47      @param arena An ArenaPool object to use for the resulting message, or NULL if new ArenaPool
  48      should be created.
  49      @param cb callback function for delivery of inner content inner
  50      content will be stored in the message if cb is NULL.
  51      @param cb_arg first argument passed to cb when it is called.
  52      @param pwfn callback function for getting token password for
  53      enveloped data content with a password recipient.
  54      @param pwfn_arg first argument passed to pwfn when it is called.
  55      @param decrypt_key_cb callback function for getting bulk key
  56      for encryptedData content.
  57      @param decrypt_key_cb_arg first argument passed to decrypt_key_cb
  58      when it is called.
  59      @param outDecoder On success will contain a pointer to a newly created SecCmsDecoder.
  60      @result A result code. See "SecCmsBase.h" for possible results.
  61      @discussion Create a SecCmsDecoder().  If this function returns noErr, the caller must dispose of the returned outDecoder by calling SecCmsDecoderDestroy() or SecCmsDecoderFinish().
  62      @availability 10.4 through 10.7
  63  */
  64 extern OSStatus
  65 SecCmsDecoderCreate(SecArenaPoolRef arena,
  66                     SecCmsContentCallback cb, void *cb_arg,
  67                     PK11PasswordFunc pwfn, void *pwfn_arg,
  68                     SecCmsGetDecryptKeyCallback decrypt_key_cb, void
  69                     *decrypt_key_cb_arg,
  70                     SecCmsDecoderRef *outDecoder)
  71     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst);
  72 #else // !TARGET_OS_OSX
  73 /*!
  74     @function
  75     @abstract Set up decoding of a BER-encoded CMS message.
  76     @param cb callback function for delivery of inner content inner
  77         content will be stored in the message if cb is NULL.
  78     @param cb_arg first argument passed to cb when it is called.
  79     @param pwfn callback function for getting token password for
  80         enveloped data content with a password recipient.
  81     @param pwfn_arg first argument passed to pwfn when it is called.
  82     @param decrypt_key_cb callback function for getting bulk key
  83         for encryptedData content.
  84     @param decrypt_key_cb_arg first argument passed to decrypt_key_cb
  85         when it is called.
  86     @param outDecoder On success will contain a pointer to a newly created SecCmsDecoder.
  87     @result A result code. See "SecCmsBase.h" for possible results.
  88     @discussion Create a SecCmsDecoder().  If this function returns errSecSuccess, the caller must dispose of the returned outDecoder by calling SecCmsDecoderDestroy() or SecCmsDecoderFinish().
  89     @availability 10.4 and later
  90  */
  91 extern OSStatus
  92 SecCmsDecoderCreate(SecCmsContentCallback cb, void *cb_arg,
  93                    PK11PasswordFunc pwfn, void *pwfn_arg,
  94                    SecCmsGetDecryptKeyCallback decrypt_key_cb, void
  95                    *decrypt_key_cb_arg,
  96                    SecCmsDecoderRef *outDecoder)
  97     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst);
  98 #endif // !TARGET_OS_OSX
  99
 100 /*!
 101     @function
 102     @abstract Feed BER-encoded data to decoder.
 103     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
 104     @param buf Pointer to bytes to be decoded.
 105     @param len number of bytes to decode.
 106     @result A result code. See "SecCmsBase.h" for possible results.
 107     @discussion If a call to this function fails the caller should call SecCmsDecoderDestroy().
 108     @availability 10.4 and later
 109  */
 110 extern OSStatus
 111 SecCmsDecoderUpdate(SecCmsDecoderRef decoder, const void *buf, CFIndex len);
 112
 113 /*!
 114     @function
 115     @abstract Abort a (presumably failed) decoding process.
 116     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
 117     @availability 10.4 and later
 118  */
 119 extern void
 120 SecCmsDecoderDestroy(SecCmsDecoderRef decoder);
 121
 122 /*!
 123     @function
 124     @abstract Mark the end of inner content and finish decoding.
 125     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
 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 SecCmsDecoderFinish(SecCmsDecoderRef decoder, SecCmsMessageRef *outMessage);
 133
 134 /*! @functiongroup One shot interface */
 135 #if TARGET_OS_OSX
 136 /*!
 137     @function
 138     @abstract Decode a CMS message from BER encoded data.
 139     @discussion This function basically does the same as calling
 140     SecCmsDecoderStart(), SecCmsDecoderUpdate() and SecCmsDecoderFinish().
 141     @param encodedMessage Pointer to a CSSM_DATA containing the BER encoded cms
 142     message to decode.
 143     @param cb callback function for delivery of inner content inner
 144     content will be stored in the message if cb is NULL.
 145     @param cb_arg first argument passed to cb when it is called.
 146     @param pwfn callback function for getting token password for enveloped
 147     data content with a password recipient.
 148     @param pwfn_arg first argument passed to pwfn when it is called.
 149     @param decrypt_key_cb callback function for getting bulk key for encryptedData content.
 150     @param decrypt_key_cb_arg first argument passed to decrypt_key_cb when it is called.
 151     @param outMessage On success a pointer to a SecCmsMessage containing the decoded message.
 152     @result A result code. See "SecCmsBase.h" for possible results.
 153     @discussion decoder is no longer valid after this function is called.
 154     @availability 10.4 through 10.7
 155  */
 156 #pragma clang diagnostic push
 157 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
 158 extern OSStatus
 159 SecCmsMessageDecode(const CSSM_DATA *encodedMessage,
 160                     SecCmsContentCallback cb, void *cb_arg,
 161                     PK11PasswordFunc pwfn, void *pwfn_arg,
 162                     SecCmsGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg,
 163                     SecCmsMessageRef *outMessage)
 164     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst);
 165 #pragma clang diagnostic pop
 166 #else // !TARGET_OS_OSX
 167 /*!
 168     @function
 169     @abstract Decode a CMS message from BER encoded data.
 170     @discussion This function basically does the same as calling
 171                 SecCmsDecoderStart(), SecCmsDecoderUpdate() and SecCmsDecoderFinish().
 172     @param encodedMessage Pointer to a SecAsn1Item containing the BER encoded cms
 173            message to decode.
 174     @param cb callback function for delivery of inner content inner
 175            content will be stored in the message if cb is NULL.
 176     @param cb_arg first argument passed to cb when it is called.
 177     @param pwfn callback function for getting token password for enveloped
 178            data content with a password recipient.
 179     @param pwfn_arg first argument passed to pwfn when it is called.
 180     @param decrypt_key_cb callback function for getting bulk key for encryptedData content.
 181     @param decrypt_key_cb_arg first argument passed to decrypt_key_cb when it is called.
 182     @param outMessage On success a pointer to a SecCmsMessage containing the decoded message.
 183     @result A result code. See "SecCmsBase.h" for possible results.
 184     @discussion decoder is no longer valid after this function is called.
 185     @availability 10.4 and later
 186  */
 187 extern OSStatus
 188 SecCmsMessageDecode(const SecAsn1Item *encodedMessage,
 189                     SecCmsContentCallback cb, void *cb_arg,
 190                     PK11PasswordFunc pwfn, void *pwfn_arg,
 191                     SecCmsGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg,
 192                     SecCmsMessageRef *outMessage)
 193     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst);
 194 #endif // !TARGET_OS_OSX
 195
 196
 197 __END_DECLS
 198
 199 #endif /* _SECURITY_SECCMSDECODER_H_ */