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