libsecurity_smime/lib/SecCmsDecoder.h

   1 /*
   2  *  Copyright (c) 2004,2008,2010,2013 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,2008,2010,2013 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 cb callback function for delivery of inner content inner
  51         content will be stored in the message if cb is NULL.
  52     @param cb_arg first argument passed to cb when it is called.
  53     @param pwfn callback function for getting token password for
  54         enveloped data content with a password recipient.
  55     @param pwfn_arg first argument passed to pwfn when it is called.
  56     @param decrypt_key_cb callback function for getting bulk key
  57         for encryptedData content.
  58     @param decrypt_key_cb_arg first argument passed to decrypt_key_cb
  59         when it is called.
  60     @param outDecoder On success will contain a pointer to a newly created SecCmsDecoder.
  61     @result A result code. See "SecCmsBase.h" for possible results.
  62     @discussion Create a SecCmsDecoder().  If this function returns errSecSuccess, the caller must dispose of the returned outDecoder by calling SecCmsDecoderDestroy() or SecCmsDecoderFinish().
  63     @availability 10.4 and later
  64     @updated 2004-04-05
  65  */
  66 extern OSStatus
  67 SecCmsDecoderCreate(SecCmsContentCallback cb, void *cb_arg,
  68                    PK11PasswordFunc pwfn, void *pwfn_arg,
  69                    SecCmsGetDecryptKeyCallback decrypt_key_cb, void
  70                    *decrypt_key_cb_arg,
  71                    SecCmsDecoderRef *outDecoder);
  72
  73 /*!
  74     @function
  75     @abstract Feed BER-encoded data to decoder.
  76     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
  77     @param buf Pointer to bytes to be decoded.
  78     @param len number of bytes to decode.
  79     @result A result code. See "SecCmsBase.h" for possible results.
  80     @discussion If a call to this function fails the caller should call SecCmsDecoderDestroy().
  81     @availability 10.4 and later
  82  */
  83 extern OSStatus
  84 SecCmsDecoderUpdate(SecCmsDecoderRef decoder, const void *buf, CFIndex len);
  85
  86 /*!
  87     @function
  88     @abstract Abort a (presumably failed) decoding process.
  89     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
  90     @availability 10.4 and later
  91  */
  92 extern void
  93 SecCmsDecoderDestroy(SecCmsDecoderRef decoder);
  94
  95 /*!
  96     @function
  97     @abstract Mark the end of inner content and finish decoding.
  98     @param decoder Pointer to a SecCmsDecoderContext created with SecCmsDecoderCreate().
  99     @param outMessage On success a pointer to a SecCmsMessage containing the decoded message.
 100     @result A result code. See "SecCmsBase.h" for possible results.
 101     @discussion decoder is no longer valid after this function is called.
 102     @availability 10.4 and later
 103  */
 104 extern OSStatus
 105 SecCmsDecoderFinish(SecCmsDecoderRef decoder, SecCmsMessageRef *outMessage);
 106
 107 /*! @functiongroup One shot interface */
 108 /*!
 109     @function
 110     @abstract Decode a CMS message from BER encoded data.
 111     @discussion This function basically does the same as calling
 112                 SecCmsDecoderStart(), SecCmsDecoderUpdate() and SecCmsDecoderFinish().
 113     @param DERmessage Pointer to a SecAsn1Item containing the BER encoded cms
 114            message to decode.
 115     @param cb callback function for delivery of inner content inner
 116            content will be stored in the message if cb is NULL.
 117     @param cb_arg first argument passed to cb when it is called.
 118     @param pwfn callback function for getting token password for enveloped
 119            data content with a password recipient.
 120     @param pwfn_arg first argument passed to pwfn when it is called.
 121     @param decrypt_key_cb callback function for getting bulk key for encryptedData content.
 122     @param decrypt_key_cb_arg first argument passed to decrypt_key_cb when it is called.
 123     @param outMessage On success a pointer to a SecCmsMessage containing the decoded message.
 124     @result A result code. See "SecCmsBase.h" for possible results.
 125     @discussion decoder is no longer valid after this function is called.
 126     @availability 10.4 and later
 127  */
 128 extern OSStatus
 129 SecCmsMessageDecode(const SecAsn1Item *encodedMessage,
 130                     SecCmsContentCallback cb, void *cb_arg,
 131                     PK11PasswordFunc pwfn, void *pwfn_arg,
 132                     SecCmsGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg,
 133                     SecCmsMessageRef *outMessage);
 134
 135
 136 #if defined(__cplusplus)
 137 }
 138 #endif
 139
 140 #endif /* _SECURITY_SECCMSDECODER_H_ */