OSX/libsecurity_smime/lib/SecCmsMessage.h

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