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