1/* 2 * Copyright (c) 2004,2008,2010 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,2008,2010 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(void); 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 top level contentInfo. 84 */ 85extern SecCmsContentInfoRef 86SecCmsMessageGetContentInfo(SecCmsMessageRef cmsg); 87 88/*! 89 @function 90 @abstract Return a pointer to the actual content. 91 @discussion In the case of those types which are encrypted, this returns the *plain* content. 92 In case of nested contentInfos, this descends and retrieves the innermost content. 93 */ 94extern const SecAsn1Item * 95SecCmsMessageGetContent(SecCmsMessageRef cmsg); 96 97/*! 98 @function 99 @abstract Count number of levels of CMS content objects in this message. 100 @discussion CMS data content objects do not count. 101 */ 102extern int 103SecCmsMessageContentLevelCount(SecCmsMessageRef cmsg); 104 105/*! 106 @function 107 @abstract Find content level #n. 108 @discussion CMS data content objects do not count. 109 */ 110extern SecCmsContentInfoRef 111SecCmsMessageContentLevel(SecCmsMessageRef cmsg, int n); 112 113/*! 114 @function 115 @abstract See if message contains certs along the way. 116 */ 117extern Boolean 118SecCmsMessageContainsCertsOrCrls(SecCmsMessageRef cmsg); 119 120/*! 121 @function 122 @abstract See if message contains a encrypted submessage. 123 */ 124extern Boolean 125SecCmsMessageIsEncrypted(SecCmsMessageRef cmsg); 126 127/*! 128 @function 129 @abstract See if message contains a signed submessage 130 @discussion If the CMS message has a SignedData with a signature (not just a SignedData) 131 return true; false otherwise. This can/should be called before calling 132 VerifySignature, which will always indicate failure if no signature is 133 present, but that does not mean there even was a signature! 134 Note that the content itself can be empty (detached content was sent 135 another way); it is the presence of the signature that matters. 136 */ 137extern Boolean 138SecCmsMessageIsSigned(SecCmsMessageRef cmsg); 139 140/*! 141 @function 142 @abstract See if content is empty. 143 @result Returns PR_TRUE is innermost content length is < minLen 144 @discussion XXX need the encrypted content length (why?) 145 */ 146extern Boolean 147SecCmsMessageIsContentEmpty(SecCmsMessageRef cmsg, unsigned int minLen); 148 149 150#if defined(__cplusplus) 151} 152#endif 153 154#endif /* _SECURITY_SECCMSMESSAGE_H_ */ 155