CMS/SecCmsMessage.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 SecCmsMessage.h
  26
  27     @availability 10.4 and later
  28     @abstract CMS message object interfaces
  29     @abstract Interfaces of the CMS implementation.
  30     @discussion A SecCmsMessage represent a Cryptographic Message
  31                 Syntax (CMS) object as described in rfc3369.
  32                 It can be encoded using a SecCmsEncoder into BER
  33                 data or obtained from a SecCmsDecoder and examined
  34                 using the functions below.
  35  */
  36
  37 #ifndef _SECURITY_SECCMSMESSAGE_H_
  38 #define _SECURITY_SECCMSMESSAGE_H_  1
  39
  40 #include <Security/SecCmsBase.h>
  41
  42 __BEGIN_DECLS
  43
  44 #if TARGET_OS_OSX
  45
  46 /*!
  47      @function
  48      @abstract Create a CMS message object.
  49      @param poolp Arena to allocate memory from, or NULL if new arena should
  50      be created.
  51      @result A pointer to a newly created SecCmsMessage.  When finished using
  52      this the caller should call SecCmsMessageDestroy().  On failure
  53      returns NULL.  In this case call PR_GetError() to find out what went
  54      wrong.
  55  */
  56 extern SecCmsMessageRef
  57 SecCmsMessageCreate(SecArenaPoolRef poolp)
  58     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst);
  59
  60 #else // !TARGET_OS_OSX
  61
  62 /*!
  63     @function
  64     @abstract Create a CMS message object.
  65     @result A pointer to a newly created SecCmsMessage.  When finished using
  66         this the caller should call SecCmsMessageDestroy().  On failure
  67         returns NULL.  In this case call PR_GetError() to find out what went
  68         wrong.
  69  */
  70 extern SecCmsMessageRef
  71 SecCmsMessageCreate(void)
  72     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst);
  73
  74 #endif // !TARGET_OS_OSX
  75
  76 /*!
  77     @function
  78     @abstract Destroy a CMS message and all of its sub-pieces.
  79     @param cmsg Pointer to a SecCmsMessage object.
  80  */
  81 extern void
  82 SecCmsMessageDestroy(SecCmsMessageRef cmsg);
  83
  84 /*!
  85     @function
  86     @abstract Return a copy of the given message.
  87     @discussion  The copy may be virtual or may be real -- either way, the
  88         result needs to be passed to SecCmsMessageDestroy later (as does the
  89         original).
  90     @param cmsg Pointer to a SecCmsMessage object.
  91  */
  92 extern SecCmsMessageRef
  93 SecCmsMessageCopy(SecCmsMessageRef cmsg);
  94
  95 #if SEC_OS_OSX
  96 /*!
  97     @function
  98     @abstract Return a pointer to the message's arena pool.
  99  */
 100 extern SecArenaPoolRef
 101 SecCmsMessageGetArena(SecCmsMessageRef cmsg);
 102 #endif
 103
 104 /*!
 105     @function
 106     @abstract Return a pointer to the top level contentInfo.
 107  */
 108 extern SecCmsContentInfoRef
 109 SecCmsMessageGetContentInfo(SecCmsMessageRef cmsg);
 110
 111 #if TARGET_OS_OSX
 112 /*!
 113      @function
 114      @abstract Return a pointer to the actual content.
 115      @discussion In the case of those types which are encrypted, this returns the *plain* content.
 116      In case of nested contentInfos, this descends and retrieves the innermost content.
 117  */
 118 #pragma clang diagnostic push
 119 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
 120 extern CSSM_DATA_PTR
 121 SecCmsMessageGetContent(SecCmsMessageRef cmsg)
 122     API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst);
 123 #pragma clang diagnostic pop
 124 #else // !TARGET_OS_OSX
 125 /*!
 126     @function
 127     @abstract Return a pointer to the actual content.
 128     @discussion In the case of those types which are encrypted, this returns the *plain* content.
 129                 In case of nested contentInfos, this descends and retrieves the innermost content.
 130  */
 131 extern const SecAsn1Item *
 132 SecCmsMessageGetContent(SecCmsMessageRef cmsg)
 133     API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst);
 134 #endif // !TARGET_OS_OSX
 135
 136 /*!
 137     @function
 138     @abstract Count number of levels of CMS content objects in this message.
 139     @discussion CMS data content objects do not count.
 140  */
 141 extern int
 142 SecCmsMessageContentLevelCount(SecCmsMessageRef cmsg);
 143
 144 /*!
 145     @function
 146     @abstract Find content level #n.
 147     @discussion CMS data content objects do not count.
 148  */
 149 extern SecCmsContentInfoRef
 150 SecCmsMessageContentLevel(SecCmsMessageRef cmsg, int n);
 151
 152 /*!
 153     @function
 154     @abstract See if message contains certs along the way.
 155  */
 156 extern Boolean
 157 SecCmsMessageContainsCertsOrCrls(SecCmsMessageRef cmsg);
 158
 159 /*!
 160     @function
 161     @abstract See if message contains a encrypted submessage.
 162  */
 163 extern Boolean
 164 SecCmsMessageIsEncrypted(SecCmsMessageRef cmsg);
 165
 166 /*!
 167     @function
 168     @abstract See if message contains a signed submessage
 169     @discussion If the CMS message has a SignedData with a signature (not just a SignedData)
 170                 return true; false otherwise.  This can/should be called before calling
 171                 VerifySignature, which will always indicate failure if no signature is
 172                 present, but that does not mean there even was a signature!
 173                 Note that the content itself can be empty (detached content was sent
 174                 another way); it is the presence of the signature that matters.
 175  */
 176 extern Boolean
 177 SecCmsMessageIsSigned(SecCmsMessageRef cmsg);
 178
 179 /*!
 180     @function
 181     @abstract See if content is empty.
 182     @result Returns PR_TRUE is innermost content length is < minLen
 183     @discussion XXX need the encrypted content length (why?)
 184  */
 185 extern Boolean
 186 SecCmsMessageIsContentEmpty(SecCmsMessageRef cmsg, unsigned int minLen);
 187
 188 #if TARGET_OS_OSX
 189 extern Boolean
 190 SecCmsMessageContainsTSTInfo(SecCmsMessageRef cmsg);
 191 #endif
 192
 193 __END_DECLS
 194
 195 #endif /* _SECURITY_SECCMSMESSAGE_H_ */