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 SecCmsSignedData.h
26    @Copyright (c) 2004,2008,2010 Apple Inc. All Rights Reserved.
27
28    @availability 10.4 and later
29    @abstract Interfaces of the CMS implementation.
30    @discussion The functions here implement functions for encoding
31                and decoding Cryptographic Message Syntax (CMS) objects
32                as described in rfc3369.
33 */
34
35#ifndef _SECURITY_SECCMSSIGNEDDATA_H_
36#define _SECURITY_SECCMSSIGNEDDATA_H_  1
37
38#include <Security/SecCmsBase.h>
39#include <Security/SecTrust.h>
40
41#if defined(__cplusplus)
42extern "C" {
43#endif
44
45/*!
46    @function
47    @abstract Create a new SecCmsSignedData object.
48    @param cmsg Pointer to a SecCmsMessage in which this SecCmsSignedData
49        should be created.
50 */
51extern SecCmsSignedDataRef
52SecCmsSignedDataCreate(SecCmsMessageRef cmsg);
53
54/*!
55    @function
56 */
57extern void
58SecCmsSignedDataDestroy(SecCmsSignedDataRef sigd);
59
60/*!
61    @function
62    @abstract Retrieve the SignedData's signer list.
63 */
64extern SecCmsSignerInfoRef *
65SecCmsSignedDataGetSignerInfos(SecCmsSignedDataRef sigd);
66
67/*!
68    @function
69 */
70extern int
71SecCmsSignedDataSignerInfoCount(SecCmsSignedDataRef sigd);
72
73/*!
74    @function
75 */
76extern SecCmsSignerInfoRef
77SecCmsSignedDataGetSignerInfo(SecCmsSignedDataRef sigd, int i);
78
79/*!
80    @function
81    @abstract Retrieve the SignedData's digest algorithm list.
82 */
83extern SECAlgorithmID **
84SecCmsSignedDataGetDigestAlgs(SecCmsSignedDataRef sigd);
85
86/*!
87    @function
88    @abstract Return pointer to this signedData's contentinfo.
89 */
90extern SecCmsContentInfoRef
91SecCmsSignedDataGetContentInfo(SecCmsSignedDataRef sigd);
92
93/*!
94    @function
95    @discussion XXX Should be obsoleted.
96 */
97extern OSStatus
98SecCmsSignedDataImportCerts(SecCmsSignedDataRef sigd, SecKeychainRef keychain,
99				SECCertUsage certusage, Boolean keepcerts);
100
101/*!
102    @function
103    @abstract See if we have digests in place.
104 */
105extern Boolean
106SecCmsSignedDataHasDigests(SecCmsSignedDataRef sigd);
107
108/*!
109    @function
110    @abstract Check the signatures.
111    @discussion The digests were either calculated during decoding (and are stored in the
112                signedData itself) or set after decoding using SecCmsSignedDataSetDigests.
113
114                The verification checks if the signing cert is valid and has a trusted chain
115                for the purpose specified by "policies".
116
117                If trustRef is NULL the cert chain is verified and the VerificationStatus is set accordingly.
118                Otherwise a SecTrust object is returned for the caller to evaluate using SecTrustEvaluate().
119 */
120extern OSStatus
121SecCmsSignedDataVerifySignerInfo(SecCmsSignedDataRef sigd, int i, SecKeychainRef keychainOrArray,
122				 CFTypeRef policies, SecTrustRef *trustRef);
123
124/*!
125    @function
126    @abstract Verify the certs in a certs-only message.
127*/
128extern OSStatus
129SecCmsSignedDataVerifyCertsOnly(SecCmsSignedDataRef sigd,
130                                  SecKeychainRef keychainOrArray,
131                                  CFTypeRef policies);
132
133/*!
134    @function
135 */
136extern OSStatus
137SecCmsSignedDataAddCertList(SecCmsSignedDataRef sigd, CFArrayRef certlist);
138
139/*!
140    @function
141    @abstract Add cert and its entire chain to the set of certs.
142 */
143extern OSStatus
144SecCmsSignedDataAddCertChain(SecCmsSignedDataRef sigd, SecCertificateRef cert);
145
146/*!
147    @function
148 */
149extern OSStatus
150SecCmsSignedDataAddCertificate(SecCmsSignedDataRef sigd, SecCertificateRef cert);
151
152/*!
153    @function
154 */
155extern Boolean
156SecCmsSignedDataContainsCertsOrCrls(SecCmsSignedDataRef sigd);
157
158/*!
159    @function
160    @abstract Retrieve the SignedData's certificate list.
161 */
162extern SecAsn1Item * *
163SecCmsSignedDataGetCertificateList(SecCmsSignedDataRef sigd);
164
165/*!
166    @function
167    @abstract Create a certs-only SignedData.
168    @param cert Base certificate that will be included
169    @param include_chain If true, include the complete cert chain for cert.
170    @discussion More certs and chains can be added via AddCertificate and AddCertChain.
171    @result An error results in a return value of NULL and an error set.
172 */
173extern SecCmsSignedDataRef
174SecCmsSignedDataCreateCertsOnly(SecCmsMessageRef cmsg, SecCertificateRef cert, Boolean include_chain);
175
176/*!
177	@function
178    @abstract Finalize the digests in digestContext and apply them to sigd.
179    @param sigd A SecCmsSignedDataRef for which the digests have been calculated
180    @param digestContext A digestContext created with SecCmsDigestContextStartMultiple.
181	@result The digest will have been applied to sigd.  After this call completes sigd is ready to accept
182	SecCmsSignedDataVerifySignerInfo() calls.  The caller should still destroy digestContext with a SecCmsDigestContextDestroy() call.
183
184 */
185extern OSStatus SecCmsSignedDataSetDigestContext(SecCmsSignedDataRef sigd,
186												 SecCmsDigestContextRef digestContext);
187
188#if defined(__cplusplus)
189}
190#endif
191
192#endif /* _SECURITY_SECCMSSIGNEDDATA_H_ */
193