CMS/SecCmsEncoder.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 SecCmsEncoder.h
  26
  27     @availability 10.4 and later
  28     @abstract CMS message encoding
  29     @discussion The functions here implement functions for encoding
  30                 Cryptographic Message Syntax (CMS) objects as described
  31                 in rfc3369.
  32                 A SecCmsEncoder object is used to encode CMS messages into BER.
  33  */
  34
  35 #ifndef _SECURITY_SECCMSENCODER_H_
  36 #define _SECURITY_SECCMSENCODER_H_  1
  37
  38 #include <Security/SecCmsBase.h>
  39 #include <CoreFoundation/CFData.h>
  40
  41
  42 __BEGIN_DECLS
  43
  44 /*! @functiongroup Streaming interface */
  45
  46 #if TARGET_OS_OSX
  47 /*!
  48      @function
  49      @abstract Set up encoding of a CMS message.
  50      @param outputfn callback function for delivery of BER-encoded output will
  51      not be called if NULL.
  52      @param outputarg first argument passed to outputfn when it is called.
  53      @param dest If non-NULL, pointer to a CSSM_DATA that will hold the
  54      BER-encoded output.
  55      @param destpoolp Pool to allocate BER-encoded output in.
  56      @param pwfn callback function for getting token password for enveloped
  57      data content with a password recipient.
  58      @param pwfn_arg first argument passed to pwfn when it is called.
  59      @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
  60      @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
  61      called.
  62      @param detached_digestalgs digest algorithms in detached_digests
  63      @param detached_digests digests from detached content (one for every element
  64      in detached_digestalgs).
  65      @result On success a pointer to a SecCmsMessage containing the decoded message
  66      is returned. On failure returns NULL. Call PR_GetError() to find out what
  67      went wrong in this case.
  68      @availability 10.4 through 10.7
  69  */
  70 #pragma clang diagnostic push
  71 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
  72 extern OSStatus
  73 SecCmsEncoderCreate(SecCmsMessageRef cmsg,
  74                     SecCmsContentCallback outputfn, void *outputarg,
  75                     CSSM_DATA_PTR dest, SecArenaPoolRef destpoolp,
  76                     PK11PasswordFunc pwfn, void *pwfn_arg,
  77                     SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg,
  78                     SECAlgorithmID **detached_digestalgs, CSSM_DATA_PTR *detached_digests,
  79                     SecCmsEncoderRef *outEncoder)
  80     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst);
  81 #pragma clang diagnostic pop
  82 #else // !TARGET_OS_OSX
  83 /*!
  84     @function
  85     @abstract Set up encoding of a CMS message.
  86         @param cmsg The SecCmsMessageRef to be encoded.
  87     @param outputfn callback function for delivery of BER-encoded output will
  88         not be called if NULL.
  89     @param outputarg first argument passed to outputfn when it is called.
  90     @param outBer If non-NULL, a CFMutableDataRef to which the
  91         BER-encoded output will be appended.
  92     @param pwfn callback function for getting token password for enveloped
  93            data content with a password recipient.
  94     @param pwfn_arg first argument passed to pwfn when it is called.
  95     @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
  96     @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
  97         called.
  98     @result On success a pointer to a SecCmsMessage containing the decoded message
  99         is returned. On failure returns NULL. Call PR_GetError() to find out what
 100         went wrong in this case.
 101     @availability 10.4 and later
 102  */
 103 extern OSStatus
 104 SecCmsEncoderCreate(SecCmsMessageRef cmsg,
 105                     SecCmsContentCallback outputfn, void *outputarg,
 106                     CFMutableDataRef outBer,
 107                     PK11PasswordFunc pwfn, void *pwfn_arg,
 108                     SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg,
 109                     SecCmsEncoderRef *outEncoder)
 110     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst);
 111 #endif // !TARGET_OS_OSX
 112
 113 /*!
 114     @function
 115     @abstract Take content data delivery from the user
 116     @param encoder encoder context
 117     @param data content data
 118     @param len length of content data
 119     @result On success 0 is returned. On failure returns non zero. Call
 120         PR_GetError() to find out what went wrong in this case.
 121     @availability 10.4 and later
 122  */
 123 extern OSStatus
 124 SecCmsEncoderUpdate(SecCmsEncoderRef encoder, const void *data, CFIndex len);
 125
 126 /*!
 127     @function
 128     @abstract Abort a (presumably failed) encoding process.
 129     @param encoder Pointer to a SecCmsEncoderContext created with SecCmsEncoderCreate().
 130     @availability 10.4 and later
 131  */
 132 extern void
 133 SecCmsEncoderDestroy(SecCmsEncoderRef encoder);
 134
 135 /*!
 136     @function
 137     @abstract Signal the end of data.
 138     @discussion Walks down the chain of encoders and the finishes them from the
 139         innermost out.
 140     @param encoder Pointer to a SecCmsEncoder created with SecCmsEncoderCreate().
 141     @result On success 0 is returned. On failure returns non zero. Call
 142         PR_GetError() to find out what went wrong in this case.
 143     @availability 10.4 and later
 144  */
 145 extern OSStatus
 146 SecCmsEncoderFinish(SecCmsEncoderRef encoder);
 147
 148 /*! @functiongroup One shot interface */
 149 #if TARGET_OS_OSX
 150 /*!
 151      @function
 152      @abstract BER Encode a CMS message.
 153      @discussion BER Encode a CMS message, with input being the plaintext message and outBer being the output, stored in arena's pool.
 154  */
 155 #pragma clang diagnostic push
 156 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
 157 extern OSStatus
 158 SecCmsMessageEncode(SecCmsMessageRef cmsg, const CSSM_DATA *input, SecArenaPoolRef arena,
 159                     CSSM_DATA_PTR outBer)
 160     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst);
 161 #pragma clang diagnostic pop
 162 #else // !TARGET_OS_OSX
 163 /*!
 164     @function
 165     @abstract BER Encode a CMS message.
 166         @param cmsg The SecCmsMessageRef to be encoded.
 167         @param input The inner content of the message.
 168     @param outBer A CFMutableDataRef to which the
 169         BER-encoded output will be appended.
 170     @discussion BER Encode a CMS message, with input being the plaintext message and outBer being the output, stored in arena's pool.
 171  */
 172 extern OSStatus
 173 SecCmsMessageEncode(SecCmsMessageRef cmsg, const SecAsn1Item *input,
 174                     CFMutableDataRef outBer)
 175     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst);
 176 #endif // !TARGET_OS_OSX
 177
 178 __END_DECLS
 179
 180 #endif /* _SECURITY_SECCMSENCODER_H_ */