libsecurity_smime/lib/SecCmsEncoder.h

   1 /*
   2  *  Copyright (c) 2004,2008,2010 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 SecCmsEncoder.h
  26     @Copyright (c) 2004,2008,2010 Apple Inc. All Rights Reserved.
  27
  28     @availability 10.4 and later
  29     @abstract CMS message encoding
  30     @discussion The functions here implement functions for encoding
  31                 Cryptographic Message Syntax (CMS) objects as described
  32                 in rfc3369.
  33                 A SecCmsEncoder object is used to encode CMS messages into BER.
  34  */
  35
  36 #ifndef _SECURITY_SECCMSENCODER_H_
  37 #define _SECURITY_SECCMSENCODER_H_  1
  38
  39 #include <Security/SecCmsBase.h>
  40 #include <CoreFoundation/CFData.h>
  41
  42
  43 #if defined(__cplusplus)
  44 extern "C" {
  45 #endif
  46
  47
  48 /*! @functiongroup Streaming interface */
  49 /*!
  50     @function
  51     @abstract Set up encoding of a CMS message.
  52         @param cmsg The SecCmsMessageRef to be encoded.
  53     @param outputfn callback function for delivery of BER-encoded output will
  54         not be called if NULL.
  55     @param outputarg first argument passed to outputfn when it is called.
  56     @param dest If non-NULL, a CFMutableDataRef to which the
  57         BER-encoded output will be appended.
  58     @param pwfn callback function for getting token password for enveloped
  59            data content with a password recipient.
  60     @param pwfn_arg first argument passed to pwfn when it is called.
  61     @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
  62     @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
  63         called.
  64     @param detached_digestalgs digest algorithms in detached_digests
  65     @param detached_digests digests from detached content (one for every element
  66         in detached_digestalgs).
  67     @result On success a pointer to a SecCmsMessage containing the decoded message
  68         is returned. On failure returns NULL. Call PR_GetError() to find out what
  69         went wrong in this case.
  70     @availability 10.4 and later
  71  */
  72 extern OSStatus
  73 SecCmsEncoderCreate(SecCmsMessageRef cmsg,
  74                     SecCmsContentCallback outputfn, void *outputarg,
  75                     CFMutableDataRef outBer,
  76                     PK11PasswordFunc pwfn, void *pwfn_arg,
  77                     SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg,
  78                     SecCmsEncoderRef *outEncoder);
  79
  80 /*!
  81     @function
  82     @abstract Take content data delivery from the user
  83     @param encoder encoder context
  84     @param data content data
  85     @param len length of content data
  86     @result On success 0 is returned. On failure returns non zero. Call
  87         PR_GetError() to find out what went wrong in this case.
  88     @availability 10.4 and later
  89  */
  90 extern OSStatus
  91 SecCmsEncoderUpdate(SecCmsEncoderRef encoder, const void *data, CFIndex len);
  92
  93 /*!
  94     @function
  95     @abstract Abort a (presumably failed) encoding process.
  96     @param encoder Pointer to a SecCmsEncoderContext created with SecCmsEncoderCreate().
  97     @availability 10.4 and later
  98  */
  99 extern void
 100 SecCmsEncoderDestroy(SecCmsEncoderRef encoder);
 101
 102 /*!
 103     @function
 104     @abstract Signal the end of data.
 105     @discussion Walks down the chain of encoders and the finishes them from the
 106         innermost out.
 107     @param encoder Pointer to a SecCmsEncoder created with SecCmsEncoderCreate().
 108     @result On success 0 is returned. On failure returns non zero. Call
 109         PR_GetError() to find out what went wrong in this case.
 110     @availability 10.4 and later
 111  */
 112 extern OSStatus
 113 SecCmsEncoderFinish(SecCmsEncoderRef encoder);
 114
 115 /*! @functiongroup One shot interface */
 116 /*!
 117     @function
 118     @abstract BER Encode a CMS message.
 119         @param cmsg The SecCmsMessageRef to be encoded.
 120         @param input The inner content of the message.
 121     @param outBer A CFMutableDataRef to which the
 122         BER-encoded output will be appended.
 123     @discussion BER Encode a CMS message, with input being the plaintext message and outBer being the output, stored in arena's pool.
 124  */
 125 extern OSStatus
 126 SecCmsMessageEncode(SecCmsMessageRef cmsg, const SecAsn1Item *input,
 127                     CFMutableDataRef outBer);
 128
 129
 130 #if defined(__cplusplus)
 131 }
 132 #endif
 133
 134 #endif /* _SECURITY_SECCMSENCODER_H_ */