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) 45extern "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 */ 59extern SecCmsMessageRef 60SecCmsMessageCreate(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 */ 67extern void 68SecCmsMessageDestroy(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 */ 78extern SecCmsMessageRef 79SecCmsMessageCopy(SecCmsMessageRef cmsg); 80 81/*! 82 @function 83 @abstract Return a pointer to the message's arena pool. 84 */ 85extern SecArenaPoolRef 86SecCmsMessageGetArena(SecCmsMessageRef cmsg); 87 88/*! 89 @function 90 @abstract Return a pointer to the top level contentInfo. 91 */ 92extern SecCmsContentInfoRef 93SecCmsMessageGetContentInfo(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 */ 101extern CSSM_DATA_PTR 102SecCmsMessageGetContent(SecCmsMessageRef cmsg); 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 */ 109extern int 110SecCmsMessageContentLevelCount(SecCmsMessageRef cmsg); 111 112/*! 113 @function 114 @abstract Find content level #n. 115 @discussion CMS data content objects do not count. 116 */ 117extern SecCmsContentInfoRef 118SecCmsMessageContentLevel(SecCmsMessageRef cmsg, int n); 119 120/*! 121 @function 122 @abstract See if message contains certs along the way. 123 */ 124extern Boolean 125SecCmsMessageContainsCertsOrCrls(SecCmsMessageRef cmsg); 126 127/*! 128 @function 129 @abstract See if message contains a encrypted submessage. 130 */ 131extern Boolean 132SecCmsMessageIsEncrypted(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 */ 144extern Boolean 145SecCmsMessageIsSigned(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 */ 153extern Boolean 154SecCmsMessageIsContentEmpty(SecCmsMessageRef cmsg, unsigned int minLen); 155 156extern Boolean 157SecCmsMessageContainsTSTInfo(SecCmsMessageRef cmsg); 158 159#if defined(__cplusplus) 160} 161#endif 162 163#endif /* _SECURITY_SECCMSMESSAGE_H_ */ 164