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_ */