CMS/SecCmsContentInfo.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 SecCmsContentInfo.h
  26
  27     @availability 10.4 and later
  28     @abstract Interfaces of the CMS implementation.
  29     @discussion The functions here implement functions for creating and
  30                 accessing ContentInfo objects that are part of Cryptographic
  31                 Message Syntax (CMS) objects as described in rfc3369.
  32  */
  33
  34 #ifndef _SECURITY_SECCMSCONTENTINFO_H_
  35 #define _SECURITY_SECCMSCONTENTINFO_H_  1
  36
  37 #include <Security/SecCmsBase.h>
  38 #include <CoreFoundation/CFData.h>
  39
  40
  41 __BEGIN_DECLS
  42
  43 #pragma clang diagnostic push
  44 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
  45
  46 /*! @functiongroup ContentInfo accessors */
  47 /*!
  48     @function
  49     @abstract Get content's contentInfo (if it exists).
  50     @param cinfo A ContentInfo object of which we want to get the child contentInfo.
  51     @result The child ContentInfo object, or NULL if there is none.
  52     @discussion This function requires a ContentInfo object which is usually created by decoding and SecCmsMessage using a SecCmsDecoder.
  53     @availability 10.4 and later
  54  */
  55 extern SecCmsContentInfoRef
  56 SecCmsContentInfoGetChildContentInfo(SecCmsContentInfoRef cinfo);
  57
  58 /*!
  59     @function
  60     @abstract Get pointer to inner content
  61     @discussion needs to be casted...
  62  */
  63 extern void *
  64 SecCmsContentInfoGetContent(SecCmsContentInfoRef cinfo);
  65
  66 #if TARGET_OS_OSX
  67 /*!
  68      @function
  69      @abstract Get pointer to innermost content
  70      @discussion This is typically only called by SecCmsMessageGetContent().
  71  */
  72 extern CSSM_DATA_PTR
  73 SecCmsContentInfoGetInnerContent(SecCmsContentInfoRef cinfo)
  74     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
  75 #else // !TARGET_OS_OSX
  76 /*!
  77     @function
  78     @abstract Get pointer to innermost content
  79     @discussion This is typically only called by SecCmsMessageGetContent().
  80  */
  81 extern const SecAsn1Item *
  82 SecCmsContentInfoGetInnerContent(SecCmsContentInfoRef cinfo)
  83     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
  84 #endif // !TARGET_OS_OSX
  85
  86 /*!
  87     @function
  88     @abstract Find out and return the inner content type.
  89  */
  90 extern SECOidTag
  91 SecCmsContentInfoGetContentTypeTag(SecCmsContentInfoRef cinfo);
  92
  93
  94 #if TARGET_OS_OSX
  95 /*!
  96      @function
  97      @abstract Find out and return the inner content type.
  98      @discussion Caches pointer to lookup result for future reference.
  99  */
 100 extern CSSM_OID *
 101 SecCmsContentInfoGetContentTypeOID(SecCmsContentInfoRef cinfo)
 102     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 103 #else // !TARGET_OS_OSX
 104 /*!
 105     @function
 106     @abstract Find out and return the inner content type.
 107     @discussion Caches pointer to lookup result for future reference.
 108  */
 109 extern SecAsn1Oid *
 110 SecCmsContentInfoGetContentTypeOID(SecCmsContentInfoRef cinfo)
 111     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 112 #endif // !TARGET_OS_OSX
 113
 114 /*!
 115     @function
 116     @abstract Find out and return the content encryption algorithm tag.
 117  */
 118 extern SECOidTag
 119 SecCmsContentInfoGetContentEncAlgTag(SecCmsContentInfoRef cinfo);
 120
 121 /*!
 122     @function
 123     @abstract Find out and return the content encryption algorithm.
 124     @discussion Caches pointer to lookup result for future reference.
 125  */
 126 extern SECAlgorithmID *
 127 SecCmsContentInfoGetContentEncAlg(SecCmsContentInfoRef cinfo)
 128     API_AVAILABLE(macos(10.4), ios(2.0));
 129
 130 /*! @functiongroup Message construction */
 131
 132 #if TARGET_OS_OSX
 133 /*!
 134      @function
 135      @abstract Set a ContentInfos content to a Data
 136      @param cmsg A Message object to which the cinfo object belongs.
 137      @param cinfo A ContentInfo object of which we want set the content.
 138      @param data A pointer to a CSSM_DATA object or NULL if data will be provided during SecCmsEncoderUpdate calls.
 139      @param detached True if the content is to be deattched from the CMS message rather than included within it.
 140      @result A result code. See "SecCmsBase.h" for possible results.
 141      @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object.  If the call succeeds the passed in data will be owned by the reciever.  The data->Data must have been allocated using the cmsg's SecArenaPool if it is present.
 142      @availability 10.4 through 10.7
 143  */
 144 extern OSStatus
 145 SecCmsContentInfoSetContentData(SecCmsMessageRef cmsg, SecCmsContentInfoRef cinfo, CSSM_DATA_PTR data, Boolean detached)
 146     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 147 #else // !TARGET_OS_OSX
 148 /*!
 149     @function
 150     @abstract Set a ContentInfos content to a Data
 151     @param cinfo A ContentInfo object of which we want set the content.
 152     @param data A CFDataRef or NULL if data will be provided during SecCmsEncoderUpdate calls.
 153     @param detached True if the content is to be deattched from the CMS message rather than included within it.
 154     @result A result code. See "SecCmsBase.h" for possible results.
 155     @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object.
 156     @availability 10.4 and later
 157  */
 158 extern OSStatus
 159 SecCmsContentInfoSetContentData(SecCmsContentInfoRef cinfo, CFDataRef data, Boolean detached)
 160     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 161 #endif // !TARGET_OS_OSX
 162
 163 #if TARGET_OS_OSX
 164 /*!
 165      @function
 166      @abstract Set a ContentInfos content to a SignedData.
 167      @param cmsg A Message object to which the cinfo object belongs.
 168      @param cinfo A ContentInfo object of which we want set the content.
 169      @param sigd A SignedData object to set as the content of the cinfo object.
 170      @result A result code. See "SecCmsBase.h" for possible results.
 171      @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object and a SignedData which can be made by calling SecCmsSignedDataCreate().  If the call succeeds the passed in SignedData object will be owned by the reciever.  The Message object of the SignedData object must be the same as cmsg.
 172      @availability 10.4 and later
 173  */
 174 extern OSStatus
 175 SecCmsContentInfoSetContentSignedData(SecCmsMessageRef cmsg, SecCmsContentInfoRef cinfo, SecCmsSignedDataRef sigd)
 176     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 177 #else // !TARGET_OS_OSX
 178 /*!
 179     @function
 180     @abstract Set a ContentInfos content to a SignedData.
 181     @param cinfo A ContentInfo object of which we want set the content.
 182     @param sigd A SignedData object to set as the content of the cinfo object.
 183     @result A result code. See "SecCmsBase.h" for possible results.
 184     @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object and a SignedData which can be made by calling SecCmsSignedDataCreate().  If the call succeeds the passed in SignedData object will be owned by the reciever.  The Message object of the SignedData object must be the same as cmsg.
 185     @availability 10.4 and later
 186  */
 187 extern OSStatus
 188 SecCmsContentInfoSetContentSignedData(SecCmsContentInfoRef cinfo, SecCmsSignedDataRef sigd)
 189     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 190 #endif // TARGET_OS_OSX
 191
 192 #if TARGET_OS_OSX
 193 /*!
 194      @function
 195      @abstract Set a ContentInfos content to a EnvelopedData.
 196      @param cmsg A Message object to which the cinfo object belongs.
 197      @param cinfo A ContentInfo object of which we want set the content.
 198      @param envd A EnvelopedData object to set as the content of the cinfo object.
 199      @result A result code. See "SecCmsBase.h" for possible results.
 200      @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object and a EnvelopedData which can be made by calling SecCmsEnvelopedDataCreate().  If the call succeeds the passed in EnvelopedData object will be owned by the reciever.  The Message object of the EnvelopedData object must be the same as cmsg.
 201      @availability 10.4 and later
 202  */
 203 extern OSStatus
 204 SecCmsContentInfoSetContentEnvelopedData(SecCmsMessageRef cmsg, SecCmsContentInfoRef cinfo, SecCmsEnvelopedDataRef envd)
 205     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 206 #else // !TARGET_OS_OSX
 207 /*!
 208     @function
 209     @abstract Set a ContentInfos content to a EnvelopedData.
 210     @param cinfo A ContentInfo object of which we want set the content.
 211     @param envd A EnvelopedData object to set as the content of the cinfo object.
 212     @result A result code. See "SecCmsBase.h" for possible results.
 213     @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object and a EnvelopedData which can be made by calling SecCmsEnvelopedDataCreate().  If the call succeeds the passed in EnvelopedData object will be owned by the reciever.  The Message object of the EnvelopedData object must be the same as cmsg.
 214     @availability 10.4 and later
 215  */
 216 extern OSStatus
 217 SecCmsContentInfoSetContentEnvelopedData(SecCmsContentInfoRef cinfo, SecCmsEnvelopedDataRef envd)
 218     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 219 #endif // !TARGET_OS_OSX
 220
 221 #if TARGET_OS_OSX
 222 /*!
 223      @function
 224      @abstract Set a ContentInfos content to a DigestedData.
 225      @param cmsg A Message object to which the cinfo object belongs.
 226      @param cinfo A ContentInfo object of which we want set the content.
 227      @param digd A DigestedData object to set as the content of the cinfo object.
 228      @result A result code. See "SecCmsBase.h" for possible results.
 229      @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object and a DigestedData which can be made by calling SecCmsDigestedDataCreate().  If the call succeeds the passed in DigestedData object will be owned by the reciever.  The Message object of the DigestedData object must be the same as cmsg.
 230      @availability 10.4 and later
 231  */
 232 extern OSStatus
 233 SecCmsContentInfoSetContentDigestedData(SecCmsMessageRef cmsg, SecCmsContentInfoRef cinfo, SecCmsDigestedDataRef digd)
 234     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 235 #else // !TARGET_OS_OSX
 236 /*!
 237     @function
 238     @abstract Set a ContentInfos content to a DigestedData.
 239     @param cinfo A ContentInfo object of which we want set the content.
 240     @param digd A DigestedData object to set as the content of the cinfo object.
 241     @result A result code. See "SecCmsBase.h" for possible results.
 242     @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object and a DigestedData which can be made by calling SecCmsDigestedDataCreate().  If the call succeeds the passed in DigestedData object will be owned by the reciever.  The Message object of the DigestedData object must be the same as cmsg.
 243     @availability 10.4 and later
 244  */
 245 extern OSStatus
 246 SecCmsContentInfoSetContentDigestedData(SecCmsContentInfoRef cinfo, SecCmsDigestedDataRef digd)
 247     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 248 #endif // !TARGET_OS_OSX
 249
 250 #if TARGET_OS_OSX
 251 /*!
 252  @function
 253  @abstract Set a ContentInfos content to a EncryptedData.
 254  @param cmsg A Message object to which the cinfo object belongs.
 255  @param cinfo A ContentInfo object of which we want set the content.
 256  @param encd A EncryptedData object to set as the content of the cinfo object.
 257  @result A result code. See "SecCmsBase.h" for possible results.
 258  @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object and a EncryptedData which can be made by calling SecCmsEncryptedDataCreate().  If the call succeeds the passed in EncryptedData object will be owned by the reciever.  The Message object of the EncryptedData object must be the same as cmsg.
 259  @availability 10.4 and later
 260  */
 261 extern OSStatus
 262 SecCmsContentInfoSetContentEncryptedData(SecCmsMessageRef cmsg, SecCmsContentInfoRef cinfo, SecCmsEncryptedDataRef encd)
 263     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 264 #else // !TARGET_OS_OSX
 265 /*!
 266     @function
 267     @abstract Set a ContentInfos content to a EncryptedData.
 268     @param cinfo A ContentInfo object of which we want set the content.
 269     @param encd A EncryptedData object to set as the content of the cinfo object.
 270     @result A result code. See "SecCmsBase.h" for possible results.
 271     @discussion This function requires a ContentInfo object which can be made by creating a SecCmsMessage object and a EncryptedData which can be made by calling SecCmsEncryptedDataCreate().  If the call succeeds the passed in EncryptedData object will be owned by the reciever.  The Message object of the EncryptedData object must be the same as cmsg.
 272     @availability 10.4 and later
 273  */
 274 extern OSStatus
 275 SecCmsContentInfoSetContentEncryptedData(SecCmsContentInfoRef cinfo, SecCmsEncryptedDataRef encd)
 276     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 277 #endif // !TARGET_OS_OSX
 278
 279 #if TARGET_OS_OSX
 280 OSStatus
 281 SecCmsContentInfoSetContentOther(SecCmsMessageRef cmsg, SecCmsContentInfoRef cinfo, CSSM_DATA_PTR data, Boolean detached, const CSSM_OID *eContentType)
 282     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 283 #else // !TARGET_OS_OSX
 284 OSStatus
 285 SecCmsContentInfoSetContentOther(SecCmsContentInfoRef cinfo, SecAsn1Item *data, Boolean detached, const SecAsn1Oid *eContentType)
 286     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 287 #endif // !TARGET_OS_OSX
 288
 289 #if TARGET_OS_OSX
 290 extern OSStatus
 291 SecCmsContentInfoSetContentEncAlg(SecArenaPoolRef pool, SecCmsContentInfoRef cinfo,
 292                                   SECOidTag bulkalgtag, CSSM_DATA_PTR parameters, int keysize)
 293     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 294 #else // !TARGET_OS_OSX
 295 extern OSStatus
 296 SecCmsContentInfoSetContentEncAlg(SecCmsContentInfoRef cinfo,
 297                                     SECOidTag bulkalgtag, const SecAsn1Item *parameters, int keysize)
 298     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 299 #endif // !TARGET_OS_OSX
 300
 301 #if TARGET_OS_OSX
 302 extern OSStatus
 303 SecCmsContentInfoSetContentEncAlgID(SecArenaPoolRef pool, SecCmsContentInfoRef cinfo,
 304                                     SECAlgorithmID *algid, int keysize)
 305     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(iosmac);
 306 #else // !TARGET_OS_OSX
 307 extern OSStatus
 308 SecCmsContentInfoSetContentEncAlgID(SecCmsContentInfoRef cinfo,
 309                                     SECAlgorithmID *algid, int keysize)
 310     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 311 #endif // !!TARGET_OS_OSX
 312
 313 /*!
 314     @function
 315  */
 316 extern void
 317 SecCmsContentInfoSetBulkKey(SecCmsContentInfoRef cinfo, SecSymmetricKeyRef bulkkey)
 318     API_AVAILABLE(macos(10.4),ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 319
 320 /*!
 321     @function
 322  */
 323 extern SecSymmetricKeyRef
 324 SecCmsContentInfoGetBulkKey(SecCmsContentInfoRef cinfo)
 325     API_AVAILABLE(macos(10.4),ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(iosmac);
 326
 327 /*!
 328     @function
 329  */
 330 extern int
 331 SecCmsContentInfoGetBulkKeySize(SecCmsContentInfoRef cinfo);
 332
 333 #pragma clang diagnostic pop
 334
 335 __END_DECLS
 336
 337 #endif /* _SECURITY_SECCMSCONTENTINFO_H_ */